oracular (3) al_attach_shader_source.3alleg5.gz

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)