al_attach_shader_source - Allegro 5 API
-
#include <allegro5/allegro.h>
bool al_attach_shader_source(ALLEGRO_SHADER *shader, ALLEGRO_SHADER_TYPE type,
const char *source)
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(3alleg5) 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(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.
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.
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(3alleg5) 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(3alleg5).