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

SINCE

       5.1.0

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)