Shader addon
- ALLEGRO_SHADER
- ALLEGRO_SHADER_TYPE
- ALLEGRO_SHADER_PLATFORM
- al_create_shader
- al_attach_shader_source
- al_attach_shader_source_file
- al_link_shader
- al_get_shader_log
- al_use_shader
- al_destroy_shader
- al_set_shader_sampler
- al_set_shader_matrix
- al_set_shader_int
- al_set_shader_float
- al_set_shader_int_vector
- al_set_shader_float_vector
- al_set_shader_vertex_array
- al_set_shader_color_array
- al_set_shader_texcoord_array
- al_set_shader
- al_get_opengl_program_object
- al_get_direct3d_effect
These functions are declared in the following header file. Link with allegro_shader.
#include <allegro5/allegro_shader.h>
ALLEGRO_SHADER
typedef struct ALLEGRO_SHADER ALLEGRO_SHADER;
Represents a shader object. It can be either a vertex or a pixel shader. The shader source for the underlying shader can be provided either as GLSL, HLSL or Cg.
Since: 5.1.0
ALLEGRO_SHADER_TYPE
typedef enum ALLEGRO_SHADER_TYPE ALLEGRO_SHADER_TYPE;
Used with al_attach_shader_source to specify which kind of shader should be attached.
- 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;
Used with al_create_shader to select the type of shader.
- ALLEGRO_SHADER_AUTO
- ALLEGRO_SHADER_GLSL
- ALLEGRO_SHADER_HLSL
- ALLEGRO_SHADER_CG
Since: 5.1.0
al_create_shader
ALLEGRO_SHADER *al_create_shader(ALLEGRO_SHADER_PLATFORM platform)
Specify one of the ALLEGRO_SHADER_PLATFORM values to create a new shader object. The ALLEGRO_SHADER_AUTO value means GLSL is used if OpenGL is being used otherwise HLSL.
Since: 5.1.0
al_attach_shader_source
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.
When using the ALLEGRO_USE_PROGRAMMABLE_PIPELINE flag with al_set_new_display_flags Allegro itself will use shaders for all its graphics operations. No default shaders are provided so for anything to be drawn you have to setup at least one pair of shaders.
If you do not use ALLEGRO_USE_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_USE_PROGRAMMABLE_PIPELINE set automatically in this case?
When ALLEGRO_USE_PROGRAMMABLE_PIPELINE is used the following shader variables are provided by Allegro and can be accessed in your shaders:
projview_matrix - matrix for Allegro's orthographic projection multiplied by the al_use_transform matrix (vertex shader)
pos - vertex position attribute (vertex shader)
color - vertex color attribute (vertex shader, passed to fragment shader)
texcoord - vertex texture coordinate (vertex shader, passed to fragment shader)
use_tex - whether or not to use the bound texture (fragment shader)
tex - the sampler2D for the texture if one is bound (fragment shader)
use_tex_matric - whether or not to use a texture matrix (fragment shader)
tex_matrix - the texture matrix (fragment shader, used by the primitives addon)
Returns true on access 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
al_attach_shader_source_file
bool al_attach_shader_source_file(ALLEGRO_SHADER *shader,
ALLEGRO_SHADER_TYPE type, const char *filename)
Like al_attach_shader_source but reads the source code for the shader from the named file.
Since: 5.1.0
al_link_shader
bool al_link_shader(ALLEGRO_SHADER *shader)
This is reqired before the shader can be used with al_use_shader. It should be called after successfully compiling the shader with al_attach_shader_source or al_attach_shader_source_file.
Returns true on access 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
al_get_shader_log
const char *al_get_shader_log(ALLEGRO_SHADER *shader)
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_link_shader when there is an error.
This function never returns NULL.
Since: 5.1.0
al_use_shader
void al_use_shader(ALLEGRO_SHADER *shader, bool use)
Uses the shader for subsequent drawing operations.
Since: 5.1.0
al_destroy_shader
void al_destroy_shader(ALLEGRO_SHADER *shader)
This destroys the shader object as well as the underlying shader.
Since: 5.1.0
al_set_shader_sampler
bool al_set_shader_sampler(ALLEGRO_SHADER *shader, const char *name,
ALLEGRO_BITMAP *bitmap, int unit)
Adds a texture sampler variable for the given bitmap and texture unit to the shader.
Since: 5.1.0
al_set_shader_matrix
bool al_set_shader_matrix(ALLEGRO_SHADER *shader, const char *name,
ALLEGRO_TRANSFORM *matrix)
Adds a matrix variable to the shader.
Since: 5.1.0
al_set_shader_int
bool al_set_shader_int(ALLEGRO_SHADER *shader, const char *name, int i)
Adds an integer variable to the shader.
Since: 5.1.0
al_set_shader_float
bool al_set_shader_float(ALLEGRO_SHADER *shader, const char *name, float f)
Adds a float variable to the shader.
Since: 5.1.0
al_set_shader_int_vector
bool al_set_shader_int_vector(ALLEGRO_SHADER *shader, const char *name,
int elem_size, int *i, int num_elems)
Adds an array of integer vectors to the shader. The 'elem_size' parameter can take one of the values 1, 2, 3 or 4. If it is 1 then an array of 'num_elems' integer values is added. Otherwise each added array element is assumed to be a vector with 2, 3 or 4 elements in it.
Since: 5.1.0
al_set_shader_float_vector
bool al_set_shader_float_vector(ALLEGRO_SHADER *shader, const char *name,
int elem_size, float *f, int num_elems)
Same as al_set_shader_int_vector except all values are float instead of int.
Since: 5.1.0
al_set_shader_vertex_array
bool al_set_shader_vertex_array(ALLEGRO_SHADER *shader, float *v, int stride)
Sets a vertex attribute.
FIXME: Right now each array element is a 3-component vector.
Since: 5.1.0
al_set_shader_color_array
bool al_set_shader_color_array(ALLEGRO_SHADER *shader, unsigned char *c, int stride)
Sets a vertex attribute.
FIXME: Right now each array element is a 4-component vector.
Since: 5.1.0
al_set_shader_texcoord_array
bool al_set_shader_texcoord_array(ALLEGRO_SHADER *shader, float *u, int stride)
Sets a vertex attribute.
FIXME: Right now each array element is a 2-component vector.
Since: 5.1.0
al_set_shader
void al_set_shader(ALLEGRO_DISPLAY *display, ALLEGRO_SHADER *shader)
Not yet documented.
FIXME: Maybe this is not even needed as we have al_use_shader?
Since: 5.1.0
al_get_opengl_program_object
GLuint al_get_opengl_program_object(ALLEGRO_SHADER *shader)
Not yet documented.
Since: 5.1.0
al_get_direct3d_effect
LPD3DXEFFECT al_get_direct3d_effect(ALLEGRO_SHADER *shader)
Not yet documented.
Since: 5.1.0