Shader routines

These functions are declared in the main Allegro header file:

     #include <allegro5/allegro.h>

# ALLEGRO_SHADER

    typedef struct ALLEGRO_SHADER ALLEGRO_SHADER;

Source Code

An ALLEGRO_SHADER is a program that runs on the GPU. It combines both a vertex and a pixel shader. (In OpenGL terms, an ALLEGRO_SHADER is actually a program which has one or more shaders attached. This can be confusing.)

The source code for the underlying vertex or pixel shader can be provided either as GLSL or HLSL, depending on the value of ALLEGRO_SHADER_PLATFORM used when creating it.

Since: 5.1.0

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# ALLEGRO_SHADER_TYPE

    typedef enum ALLEGRO_SHADER_TYPE ALLEGRO_SHADER_TYPE;

Source Code

Used with al_attach_shader_source and al_attach_shader_source_file to specify how to interpret the attached source.

ALLEGRO_VERTEX_SHADER

  A vertex shader is executed for each vertex it is used with. The program will output exactly one vertex at a time.

  When Allegro’s graphics are being used then in addition to all vertices of primitives from the primitives addon, each drawn bitmap also consists of four vertices.

ALLEGRO_PIXEL_SHADER

  A pixel shader is executed for each pixel it is used with. The program will output exactly one pixel at a time - either in the backbuffer or in the current target bitmap.

  With Allegro’s builtin graphics this means the shader is for example called for each destination pixel of the output of an al_draw_bitmap call.

  A more accurate term for pixel shader would be fragment shader since one final pixel in the target bitmap is not necessarily composed of only a single output but of multiple fragments (for example when multi-sampling is being used).

Since: 5.1.0

# ALLEGRO_SHADER_PLATFORM

    typedef enum ALLEGRO_SHADER_PLATFORM ALLEGRO_SHADER_PLATFORM;

Source Code

The underlying platform which the ALLEGRO_SHADER is built on top of, which dictates the language used to program the shader.

- ALLEGRO_SHADER_AUTO - Pick a platform automatically given the current display flags.
- ALLEGRO_SHADER_GLSL - OpenGL Shading Language
- ALLEGRO_SHADER_HLSL - High Level Shader Language (for Direct3D)
- ALLEGRO_SHADER_AUTO_MINIMAL - Like ALLEGRO_SHADER_AUTO, but pick a more minimal implementation that may not support alpha testing.
- ALLEGRO_SHADER_GLSL_MINIMAL - Minimal GLSL shader.
- ALLEGRO_SHADER_HLSL_MINIMAL - Minimal HLSL shader.
- ALLEGRO_SHADER_HLSL_SM_3_0 - HLSL shader using shader model 3_0.

Since: 5.1.0

Examples:

- ex_shader.cpp
- ex_shader_target.c

# al_create_shader

    ALLEGRO_SHADER *al_create_shader(ALLEGRO_SHADER_PLATFORM platform)

Source Code

Create a shader object.

The platform argument is one of the ALLEGRO_SHADER_PLATFORM values, and specifies the type of shader object to create, and which language is used to program the shader.

The shader platform must be compatible with the type of display that you will use the shader with. For example, you cannot create and use a HLSL shader on an OpenGL display, nor a GLSL shader on a Direct3D display.

The ALLEGRO_SHADER_AUTO value automatically chooses the appropriate platform for the display currently targeted by the calling thread; there must be such a display. It will create a GLSL shader for an OpenGL display, and a HLSL shader for a Direct3D display.

Returns the shader object on success. Otherwise, returns NULL.

Since: 5.1.0

See also: al_attach_shader_source, al_attach_shader_source_file, al_build_shader, al_use_shader, al_destroy_shader, al_get_shader_platform

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_attach_shader_source

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

Source Code

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

Since: 5.1.0

See also: al_attach_shader_source_file, al_build_shader, al_get_default_shader_source, al_get_shader_log, ALLEGRO_PRIM_ATTR

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_attach_shader_source_file

    bool al_attach_shader_source_file(ALLEGRO_SHADER *shader,
       ALLEGRO_SHADER_TYPE type, const char *filename)

Source Code

Like al_attach_shader_source but reads the source code for the shader from the named file.

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.

Since: 5.1.0

See also: al_attach_shader_source, al_build_shader, al_get_shader_log

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_build_shader

    bool al_build_shader(ALLEGRO_SHADER *shader)

Source Code

This is required before the shader can be used with al_use_shader. It should be called after successfully attaching the pixel and/or vertex shaders with al_attach_shader_source or al_attach_shader_source_file.

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.

> Note: If you are using the ALLEGRO_PROGRAMMABLE_PIPELINE flag, then you must specify both a pixel and a vertex shader sources for anything to be rendered.

Since: 5.1.6

See also: al_use_shader, al_get_shader_log

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_get_shader_log

    const char *al_get_shader_log(ALLEGRO_SHADER *shader)

Source Code

Return a read-only string containing the information log for a shader program. The log is updated by certain functions, such as al_attach_shader_source or al_build_shader when there is an error.

This function never returns NULL.

Since: 5.1.0

See also: al_attach_shader_source, al_attach_shader_source_file, al_build_shader

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_get_shader_platform

    ALLEGRO_SHADER_PLATFORM al_get_shader_platform(ALLEGRO_SHADER *shader)

Source Code

Returns the platform the shader was created with (either ALLEGRO_SHADER_HLSL or ALLEGRO_SHADER_GLSL).

Since: 5.1.6

See also: al_create_shader

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_use_shader

    bool al_use_shader(ALLEGRO_SHADER *shader)

Source Code

Uses the shader for subsequent drawing operations on the current target bitmap. Pass NULL to stop using any shader on the current target bitmap.

Returns true on success. Otherwise returns false, e.g. because the shader is incompatible with the target bitmap.

Since: 5.1.6

See also: al_destroy_shader, al_set_shader_sampler, al_set_shader_matrix, al_set_shader_int, al_set_shader_float, al_set_shader_bool, al_set_shader_int_vector, al_set_shader_float_vector, al_get_current_shader

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_get_current_shader

    ALLEGRO_SHADER *al_get_current_shader()

Source Code

Return the shader of the target bitmap, or NULL if one isn’t being used.

Since: 5.2.9

See also: al_use_shader

# al_destroy_shader

    void al_destroy_shader(ALLEGRO_SHADER *shader)

Source Code

Destroy a shader. Any bitmaps which currently use the shader will implicitly stop using the shader. In multi-threaded programs, be careful that no such bitmaps are being accessed by other threads at the time.

As a convenience, if the target bitmap of the calling thread is using the shader then the shader is implicitly unused before being destroyed.

This function does nothing if the shader argument is NULL.

Since: 5.1.0

See also: al_create_shader

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_set_shader_sampler

    bool al_set_shader_sampler(const char *name,
       ALLEGRO_BITMAP *bitmap, int unit)

Source Code

Sets a texture sampler uniform and texture unit of the current target bitmap’s shader. The given bitmap must be a video bitmap.

Different samplers should use different units. The bitmap passed to Allegro’s drawing functions uses the 0th unit, so if you’re planning on using the `al_tex` variable in your pixel shader as well as another sampler, set the other sampler to use a unit different from 0. With the primitives addon, it is possible to free up the 0th unit by passing `NULL` as the texture argument to the relevant drawing functions. In this case, you may set a sampler to use the 0th unit and thus not use `al_tex` (the `al_use_tex` variable will be set to `false`).

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_use_shader

Examples:

- ex_shader_multitex.c
- ex_palette.c
- ex_prim_wrap.c

# al_set_shader_matrix

    bool al_set_shader_matrix(const char *name,
       const ALLEGRO_TRANSFORM *matrix)

Source Code

Sets a matrix uniform of the current target bitmap’s shader.

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_use_shader

# al_set_shader_int

    bool al_set_shader_int(const char *name, int i)

Source Code

Sets an integer uniform of the current target bitmap’s shader.

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_use_shader

# al_set_shader_float

    bool al_set_shader_float(const char *name, float f)

Source Code

Sets a float uniform of the target bitmap’s shader.

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_use_shader

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_set_shader_bool

    bool al_set_shader_bool(const char *name, bool b)

Source Code

Sets a boolean uniform of the target bitmap’s shader.

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.6

See also: al_use_shader

# al_set_shader_int_vector

    bool al_set_shader_int_vector(const char *name,
       int num_components, const int *i, int num_elems)

Source Code

Sets an integer vector array uniform of the current target bitmap’s shader. The ‘num_components’ parameter can take one of the values 1, 2, 3 or 4. If it is 1 then an array of ‘num_elems’ integer elements is added. Otherwise each added array element is assumed to be a vector with 2, 3 or 4 components in it.

For example, if you have a GLSL uniform declared as `uniform ivec3 flowers[4]` or an HLSL uniform declared as `uniform int3 flowers[4]`, then you’d use this function from your code like so:

    int flowers[4][3] =
    {
       {1, 2, 3},
       {4, 5, 6},
       {7, 8, 9},
       {2, 5, 7}
    };

    al_set_shader_int_vector("flowers", 3, (int*)flowers, 4);

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_set_shader_float_vector, al_use_shader

# al_set_shader_float_vector

    bool al_set_shader_float_vector(const char *name,
       int num_components, const float *f, int num_elems)

Source Code

Same as al_set_shader_int_vector except all values are float instead of int.

Since: 5.1.0

See also: al_set_shader_int_vector, al_use_shader

Examples:

- ex_shader.cpp
- ex_shader_target.c
- ex_prim_shader.c

# al_get_default_shader_source

    char const *al_get_default_shader_source(ALLEGRO_SHADER_PLATFORM platform,
       ALLEGRO_SHADER_TYPE type)

Source Code

Returns a string containing the source code to Allegro’s default vertex or pixel shader appropriate for the passed platform. The ALLEGRO_SHADER_AUTO value means GLSL is used if OpenGL is being used otherwise HLSL. ALLEGRO_SHADER_AUTO requires that there is a current display set on the calling thread. This function can return NULL if Allegro was built without support for shaders of the selected platform.

Since: 5.1.6

See also: al_attach_shader_source

Examples:

- ex_shader_multitex.c
- ex_palette.c
- ex_prim_wrap.c

Allegro version 5.2.10 - Last updated: 2024-12-29 03:54:51 UTC