al_attach_shader_source(3)

💖 NAME 💖

okay so this is al_attach_shader_source(3) from the Allegro reference manual, and it's literally the attach + compile a shader source page bestie ✨

al_attach_shader_source — Allegro 5 API.

✨ SYNOPSIS ✨

#include <allegro5/allegro.h>

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

🦋 DESCRIPTION 🦋

Okay so what this function does: it attaches the shader's source code to the shader object and compiles it. Slay. 💅 If you pass NULL, it deletes the underlying (OpenGL or DirectX) shader. Also, if you'd rather grab your shader source from an external file, see al_attach_shader_source_file(3) — that's the file-based bestie.

If you do not use ALLEGRO_PROGRAMMABLE_PIPELINE, Allegro's graphics functions will not use any shader specific functions themselves. And in case of a system with no fixed function pipeline (like OpenGL ES 2 or OpenGL 3 or 4), this means Allegro's drawing functions cannot be used. Like... cannot. 😭

TODO: Is ALLEGRO_PROGRAMMABLE_PIPELINE set automatically in this case?

🫶 the uniform situation when ALLEGRO_PROGRAMMABLE_PIPELINE is on

When ALLEGRO_PROGRAMMABLE_PIPELINE is used, the following shader uniforms are provided by Allegro and can be accessed in your shaders:

• al_projview_matrix — matrix for Allegro's orthographic projection multiplied by the al_use_transform(3) 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 extras

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(3) 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(3).
• 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 the following 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 attributes

For HLSL shaders, the vertex attributes are passed using the following semantics:

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

👑 macro name cheat sheet

Also, each shader variable has a corresponding macro name that can be used when defining the shaders using string literals. Do not use these macros with the other shader functions — that will lead to undefined behavior. Not cute. 💀

• 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"

Examine the output of al_get_default_shader_source(3) for an example of how to use the above uniforms and attributes. Fr fr, it's the reference example. 👀

It returns true on success and false on error, in which case the error log is updated. The error log can be retrieved with al_get_shader_log(3). So if it fails, go check the log bestie. 🫶

🌈 SINCE 🌈

5.1.0 — iconic since then. ⭐

🎀 SEE ALSO 🎀

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

---

source/version: Allegro reference manual · date: not printed on this page — bye bestie! 🫶💖