![]() |
![]() |
![]() |
Cogl Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
Shaders and Programmable PipelineShaders and Programmable Pipeline — Fuctions for accessing the programmable GL pipeline |
enum CoglShaderType; CoglHandle cogl_create_shader (CoglShaderType shader_type
); gboolean cogl_is_shader (CoglHandle handle
); void cogl_shader_source (CoglHandle shader
,const char *source
); void cogl_shader_compile (CoglHandle handle
); char * cogl_shader_get_info_log (CoglHandle handle
); CoglShaderType cogl_shader_get_type (CoglHandle handle
); gboolean cogl_shader_is_compiled (CoglHandle handle
); CoglHandle cogl_create_program (void
); gboolean cogl_is_program (CoglHandle handle
); void cogl_program_attach_shader (CoglHandle program_handle
,CoglHandle shader_handle
); void cogl_program_link (CoglHandle handle
); int cogl_program_get_uniform_location (CoglHandle handle
,const char *uniform_name
); void cogl_program_set_uniform_1f (CoglHandle program
,int uniform_location
,float value
); void cogl_program_set_uniform_1i (CoglHandle program
,int uniform_location
,int value
); void cogl_program_set_uniform_float (CoglHandle program
,int uniform_location
,int n_components
,int count
,const float *value
); void cogl_program_set_uniform_int (CoglHandle program
,int uniform_location
,int n_components
,int count
,const int *value
); void cogl_program_set_uniform_matrix (CoglHandle program
,int uniform_location
,int dimensions
,int count
,gboolean transpose
,const float *value
);
Cogl allows accessing the GL programmable pipeline in order to create vertex and fragment shaders.
The shader source code can either be GLSL or ARBfp. If the source
code is ARBfp, it must begin with the string “!!ARBfp1.0”. The
application should check for the COGL_FEATURE_SHADERS_GLSL
or
COGL_FEATURE_SHADERS_ARBFP
features before using shaders.
When using GLSL Cogl provides replacement names for most of the builtin varyings and uniforms. It is recommended to use these names wherever possible to increase portability between OpenGL 2.0 and GLES 2.0. GLES 2.0 does not have most of the builtins under their original names so they will only work with the Cogl names.
For use in all GLSL shaders, the Cogl builtins are as follows:
The current modelview matrix. This is equivalent to gl_ModelViewMatrix.
The current projection matrix. This is equivalent to gl_ProjectionMatrix.
The combined modelview and projection matrix. A vertex shader would typically use this to transform the incoming vertex position. The separate modelview and projection matrices are usually only needed for lighting calculations. This is equivalent to gl_ModelViewProjectionMatrix.
An array of matrices for transforming the texture coordinates. This is equivalent to gl_TextureMatrix.
In a vertex shader, the following are also available:
The incoming vertex position. This is equivalent to gl_Vertex.
The incoming vertex color. This is equivalent to gl_Color.
The texture coordinate for the first texture unit. This is equivalent to gl_MultiTexCoord0.
The texture coordinate for the first texture unit. This is equivalent to gl_MultiTexCoord0. There is also cogl_tex_coord1_in and so on.
The normal of the vertex. This is equivalent to gl_Normal.
The calculated position of the vertex. This must be written to in all vertex shaders. This is equivalent to gl_Position.
The calculated size of a point. This is equivalent to gl_PointSize.
The calculated color of a vertex. This is equivalent to gl_FrontColor.
An array of calculated texture coordinates for a vertex. This is equivalent to gl_TexCoord.
In a fragment shader, the following are also available:
The calculated color of a vertex. This is equivalent to gl_FrontColor.
An array of calculated texture coordinates for a vertex. This is equivalent to gl_TexCoord.
The final calculated color of the fragment. All fragment shaders must write to this variable. This is equivalent to gl_FrontColor.
An optional output variable specifying the depth value to use for this fragment. This is equivalent to gl_FragDepth.
A readonly variable that will be true if the current primitive is front facing. This can be used to implement two-sided coloring algorithms. This is equivalent to gl_FrontFacing.
It's worth nothing that this API isn't what Cogl would like to have and at some point it may become deprecated. In future Cogl would like to have an API where parts of the pipeline in a CoglMaterial can be replaced with snippets of shader code. This API only allows the entire fragment or vertex pipeline to be replaced with shader code.
typedef enum { COGL_SHADER_TYPE_VERTEX, COGL_SHADER_TYPE_FRAGMENT } CoglShaderType;
Types of shaders
A program for proccessing vertices | |
A program for processing fragments |
Since 1.0
CoglHandle cogl_create_shader (CoglShaderType shader_type
);
Create a new shader handle, use cogl_shader_source()
to set the
source code to be used on it.
|
COGL_SHADER_TYPE_VERTEX or COGL_SHADER_TYPE_FRAGMENT. |
Returns : |
a new shader handle. |
gboolean cogl_is_shader (CoglHandle handle
);
Gets whether the given handle references an existing shader object.
|
A CoglHandle |
Returns : |
TRUE if the handle references a shader,
FALSE otherwise |
void cogl_shader_source (CoglHandle shader
,const char *source
);
Replaces the current source associated with a shader with a new one.
Please see above for a description of the recommended format for the shader code.
|
CoglHandle for a shader. |
|
Shader source. |
void cogl_shader_compile (CoglHandle handle
);
Compiles the shader, no return value, but the shader is now ready for linking into a program. Note that calling this function is optional. If it is not called then the shader will be automatically compiled when it is linked.
|
CoglHandle for a shader. |
char * cogl_shader_get_info_log (CoglHandle handle
);
Retrieves the information log for a coglobject, can be used in conjunction
with cogl_shader_get_parameteriv()
to retrieve the compiler warnings/error
messages that caused a shader to not compile correctly, mainly useful for
debugging purposes.
|
CoglHandle for a shader. |
Returns : |
a newly allocated string containing the info log. Use
g_free() to free it |
CoglShaderType cogl_shader_get_type (CoglHandle handle
);
Retrieves the type of a shader CoglHandle
|
CoglHandle for a shader. |
Returns : |
COGL_SHADER_TYPE_VERTEX if the shader is a vertex processor
or COGL_SHADER_TYPE_FRAGMENT if the shader is a frament processor |
gboolean cogl_shader_is_compiled (CoglHandle handle
);
Retrieves whether a shader CoglHandle has been compiled
|
CoglHandle for a shader. |
Returns : |
TRUE if the shader object has sucessfully be compiled |
CoglHandle cogl_create_program (void
);
Create a new cogl program object that can be used to replace parts of the GL rendering pipeline with custom code.
Returns : |
a new cogl program. |
gboolean cogl_is_program (CoglHandle handle
);
Gets whether the given handle references an existing program object.
|
A CoglHandle |
Returns : |
TRUE if the handle references a program,
FALSE otherwise |
void cogl_program_attach_shader (CoglHandle program_handle
,CoglHandle shader_handle
);
Attaches a shader to a program object. A program can have multiple
vertex or fragment shaders but only one of them may provide a
main()
function. It is allowed to use a program with only a vertex
shader or only a fragment shader.
|
a CoglHandle for a shdaer program. |
|
a CoglHandle for a vertex of fragment shader. |
void cogl_program_link (CoglHandle handle
);
Links a program making it ready for use. Note that calling this function is optional. If it is not called the program will automatically be linked the first time it is used.
|
a CoglHandle for a shader program. |
int cogl_program_get_uniform_location (CoglHandle handle
,const char *uniform_name
);
Retrieve the location (offset) of a uniform variable in a shader program, a uniform is a variable that is constant for all vertices/fragments for a shader object and is possible to modify as an external parameter.
|
a CoglHandle for a shader program. |
|
the name of a uniform. |
Returns : |
the offset of a uniform in a specified program.
This uniform can be set using cogl_program_uniform_1f() when the
program is in use. |
void cogl_program_set_uniform_1f (CoglHandle program
,int uniform_location
,float value
);
Changes the value of a floating point uniform for the given linked
program
.
|
A CoglHandle for a linked program |
|
the uniform location retrieved from
cogl_program_get_uniform_location() . |
|
the new value of the uniform. |
Since 1.4
void cogl_program_set_uniform_1i (CoglHandle program
,int uniform_location
,int value
);
Changes the value of an integer uniform for the given linked
program
.
|
A CoglHandle for a linked program |
|
the uniform location retrieved from
cogl_program_get_uniform_location() . |
|
the new value of the uniform. |
Since 1.4
void cogl_program_set_uniform_float (CoglHandle program
,int uniform_location
,int n_components
,int count
,const float *value
);
Changes the value of a float vector uniform, or uniform array for
the given linked program
.
|
A CoglHandle for a linked program |
|
the uniform location retrieved from
cogl_program_get_uniform_location() . |
|
The number of components for the uniform. For example with glsl you'd use 3 for a vec3 or 4 for a vec4. |
|
For uniform arrays this is the array length otherwise just pass 1 |
|
the new value of the uniform[s]. [array length=count] |
Since 1.4
void cogl_program_set_uniform_int (CoglHandle program
,int uniform_location
,int n_components
,int count
,const int *value
);
Changes the value of a int vector uniform, or uniform array for
the given linked program
.
|
A CoglHandle for a linked program |
|
the uniform location retrieved from
cogl_program_get_uniform_location() . |
|
The number of components for the uniform. For example with glsl you'd use 3 for a vec3 or 4 for a vec4. |
|
For uniform arrays this is the array length otherwise just pass 1 |
|
the new value of the uniform[s]. [array length=count] |
Since 1.4
void cogl_program_set_uniform_matrix (CoglHandle program
,int uniform_location
,int dimensions
,int count
,gboolean transpose
,const float *value
);
Changes the value of a matrix uniform, or uniform array in the
given linked program
.
|
A CoglHandle for a linked program |
|
the uniform location retrieved from
cogl_program_get_uniform_location() . |
|
The dimensions of the matrix. So for for example pass 2 for a 2x2 matrix or 3 for 3x3. |
|
For uniform arrays this is the array length otherwise just pass 1 |
|
Whether to transpose the matrix when setting the uniform. |
|
the new value of the uniform. [array length=count] |
Since 1.4