---
name: "al_attach_shader_source"
section: "3"
platform: "linux"
package: "allegro"
version: "5.2.11.3-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/al_attach_shader_source"
---

# al\_attach\_shader\_source(3)

Allegro 5 API

## NAME

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

Attaches the shader’s source code to the shader object and compiles it. Passing NULL deletes the underlying (OpenGL or DirectX) shader. See also [al\_attach\_shader\_source\_file(3)](/al_attach_shader_source_file/3.md) if you prefer to obtain your shader source from an external file.

If you do not use ALLEGRO\_PROGRAMMABLE\_PIPELINE Allegro’s graphics functions will not use any shader specific functions themselves. 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.

TODO: Is ALLEGRO\_PROGRAMMABLE\_PIPELINE set automatically in this case?

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)](/al_use_transform/3.md) 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.

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)](/ALLEGRO_RENDER_FUNCTION/3.md) 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)](/ALLEGRO_RENDER_STATE/3.md).

- 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`.

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

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`.

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 as that will lead to undefined behavior.

- •

  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)](/al_get_default_shader_source/3.md) for an example of how to use the above uniforms and attributes.

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)](/al_get_shader_log/3.md).

## SINCE

5\.1.0

## SEE ALSO

[al\_attach\_shader\_source\_file(3)](/al_attach_shader_source_file/3.md), [al\_build\_shader(3)](/al_build_shader/3.md), [al\_get\_default\_shader\_source(3)](/al_get_default_shader_source/3.md), [al\_get\_shader\_log(3)](/al_get_shader_log/3.md), [ALLEGRO\_PRIM\_ATTR(3)](/ALLEGRO_PRIM_ATTR/3.md)