al_attach_shader_source(3alleg5)

💖 al_attach_shader_source 💖

okay bestie, you found the Allegro 5 API manual page for al_attach_shader_source, and honestly? this one is a whole journey. shaders, uniforms, macros, the entire vibe. let's get into it ✨

---

✨ SYNOPSIS ✨

like, here's the summoning circle:

#include <allegro5/allegro.h>

bool al_attach_shader_source(ALLEGRO_SHADER *shader, ALLEGRO_SHADER_TYPE type,
    const char *source)

---

🌸 DESCRIPTION 🌸

so what this does is it attaches the shader's source code to the shader object and compiles it. that's it, that's the job. iconic behavior honestly.

Passing NULL deletes the underlying (OpenGL or DirectX) shader. poof. gone. no notes.

oh and if you'd rather pull your shader source out of an external file instead of a string, go look at al_attach_shader_source_file(3alleg5) — she's got you covered 🫶

now, the important lore: if you do not use ALLEGRO_PROGRAMMABLE_PIPELINE, Allegro's graphics functions will not use any shader specific functions themselves. and on a system with no fixed function pipeline (think OpenGL ES 2, or OpenGL 3 or 4), that means Allegro's drawing functions literally cannot be used. 💀

TODO: Is ALLEGRO_PROGRAMMABLE_PIPELINE set automatically in this case?

(yeah, that's straight from the source, even the manual is unsure. we love a mystery 🌈)

---

🎀 the uniforms Allegro gives you 🎀

when ALLEGRO_PROGRAMMABLE_PIPELINE is used, Allegro hands you these shader uniforms and you can access them in your shaders. free real estate:

• al_projview_matrix — the matrix for Allegro's orthographic projection multiplied by the al_use_transform(3alleg5) matrix. the type is mat4 in GLSL, and float4x4 in HLSL.
• al_use_tex — whether or not to use the bound texture. the type is bool in both GLSL and HLSL.
• al_tex — the texture if one is bound. the type is sampler2D in GLSL and texture in HLSL.
• al_use_tex_matrix — whether or not to use a texture matrix (used by the primitives addon). the type is bool in both GLSL and HLSL.
• al_tex_matrix — the texture matrix (used by the primitives addon). your shader should multiply the texture coordinates by this matrix. the type is mat4 in GLSL, and float4x4 in HLSL.

---

🦋 GLSL alpha testing uniforms 🦋

with GLSL, alpha testing is done in the shader and uses these additional uniforms:

• al_alpha_test — whether to do any alpha testing. if false, the shader should render the pixel, otherwise it should interpret the values of al_alpha_func and al_alpha_test_val.
• al_alpha_func — the alpha testing function used. one of the ALLEGRO_RENDER_FUNCTION(3alleg5) values. the default is ALLEGRO_RENDER_ALWAYS which means all pixels (even completely transparent ones) are rendered. the type is int. see ALLEGRO_RENDER_STATE(3alleg5).
• al_alpha_test_val — if alpha testing is not ALLEGRO_RENDER_NEVER or ALLEGRO_RENDER_ALWAYS, the alpha value to compare to for alpha testing. the type is float.

---

🌈 GLSL vertex attributes 🌈

for GLSL shaders the vertex attributes are passed using these variables:

• al_pos — vertex position attribute. type is vec4.
• al_texcoord — vertex texture coordinate attribute. type is vec2.
• al_color — vertex color attribute. type is vec4.
• al_user_attr_0 — the vertex attribute declared as ALLEGRO_PRIM_USER_ATTR.
• al_user_attr_1, ..., al_user_attr_9 — the vertex attribute declared as ALLEGRO_PRIM_USER_ATTR + X where X is an integer from 1 to 9.

---

⭐ HLSL vertex attribute semantics ⭐

for HLSL shaders the vertex attributes are passed using these semantics:

• POSITION0 — vertex position attribute. type is float4.
• TEXCOORD0 — vertex texture coordinate attribute. type is float2.
• TEXCOORD1 — vertex color attribute. type is float4.

---

👑 the macro girlies 👑

also, each shader variable has a corresponding macro name that can be used when defining the shaders using string literals. don't use these macros with the other shader functions, bestie, that will lead to undefined behavior. like, seriously. 🙈

• ALLEGRO_SHADER_VAR_PROJVIEW_MATRIX for "al_projview_matrix"
• ALLEGRO_SHADER_VAR_POS for "al_pos"
• ALLEGRO_SHADER_VAR_COLOR for "al_color"
• ALLEGRO_SHADER_VAR_TEXCOORD for "al_texcoord"
• ALLEGRO_SHADER_VAR_USE_TEX for "al_use_tex"
• ALLEGRO_SHADER_VAR_TEX for "al_tex"
• ALLEGRO_SHADER_VAR_USE_TEX_MATRIX for "al_use_tex_matrix"
• ALLEGRO_SHADER_VAR_TEX_MATRIX for "al_tex_matrix"
• ALLEGRO_SHADER_VAR_ALPHA_FUNCTION for "al_alpha_func"
• ALLEGRO_SHADER_VAR_ALPHA_TEST_VALUE for "al_alpha_test_val"

---

💅 how to actually learn this 💅

go examine the output of al_get_default_shader_source(3alleg5) — that's your example of how to use all the above uniforms and attributes. it's giving study guide, no cap.

---

💖 return value 💖

returns true on success and false on error, in which case the error log is updated. you can grab that error log with al_get_shader_log(3alleg5). so if things go sideways, check the log, she will tell you everything 🍓

---

🌸 SINCE 🌸

5.1.0 — she's been here a minute, and she ate.

---

✨ SEE ALSO ✨

• al_attach_shader_source_file(3alleg5)
• al_build_shader(3alleg5)
• al_get_default_shader_source(3alleg5)
• al_get_shader_log(3alleg5)
• ALLEGRO_PRIM_ATTR(3alleg5)

---

and that's the whole page, bestie 💜 this one came from the Allegro reference manual — you know, the one and only. go compile something gorgeous, and remember: NULL deletes the shader, so don't do it by accident ✨🧚💖