Shaders and Programmable Pipeline

## Shaders and Programmable Pipeline Shaders and Programmable Pipeline — Fuctions for accessing the programmable GL pipeline |

## Functions

CoglHandle | cogl_create_shader ()
CoglBool | cogl_is_shader ()
void | cogl_shader_source ()
void | cogl_shader_compile ()
char * | cogl_shader_get_info_log ()
CoglShaderType | cogl_shader_get_type ()
CoglBool | cogl_shader_is_compiled ()
CoglHandle | cogl_create_program ()
CoglBool | cogl_is_program ()
void | cogl_program_attach_shader ()
void | cogl_program_link ()
int | cogl_program_get_uniform_location ()
void | cogl_program_set_uniform_1f ()
void | cogl_program_set_uniform_1i ()
void | cogl_program_set_uniform_float ()
void | cogl_program_set_uniform_int ()
void | cogl_program_set_uniform_matrix ()

## Types and Values

enum | CoglShaderType

## Description

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:

uniform mat4 cogl_modelview_matrix

  The current modelview matrix. This is equivalent to gl_ModelViewMatrix.

uniform mat4 cogl_projection_matrix

  The current projection matrix. This is equivalent to gl_ProjectionMatrix.

uniform mat4 cogl_modelview_projection_matrix

  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.

uniform mat4 cogl_texture_matrix[]

  An array of matrices for transforming the texture coordinates. This is equivalent to gl_TextureMatrix.

In a vertex shader, the following are also available:

attribute vec4 cogl_position_in

  The incoming vertex position. This is equivalent to gl_Vertex.

attribute vec4 cogl_color_in

  The incoming vertex color. This is equivalent to gl_Color.

attribute vec4 cogl_tex_coord_in

  The texture coordinate for the first texture unit. This is equivalent to gl_MultiTexCoord0.

attribute vec4 cogl_tex_coord0_in

  The texture coordinate for the first texture unit. This is equivalent to gl_MultiTexCoord0. There is also cogl_tex_coord1_in and so on.

attribute vec3 cogl_normal_in

  The normal of the vertex. This is equivalent to gl_Normal.

vec4 cogl_position_out

  The calculated position of the vertex. This must be written to in all vertex shaders. This is equivalent to gl_Position.

float cogl_point_size_out

  The calculated size of a point. This is equivalent to gl_PointSize.

varying vec4 cogl_color_out

  The calculated color of a vertex. This is equivalent to gl_FrontColor.

varying vec4 cogl_tex_coord_out[]

  An array of calculated texture coordinates for a vertex. This is equivalent to gl_TexCoord.

In a fragment shader, the following are also available:

varying vec4 cogl_color_in

  The calculated color of a vertex. This is equivalent to gl_FrontColor.

varying vec4 cogl_tex_coord_in[]

  An array of calculated texture coordinates for a vertex. This is equivalent to gl_TexCoord.

vec4 cogl_color_out

  The final calculated color of the fragment. All fragment shaders must write to this variable. This is equivalent to gl_FrontColor.

float cogl_depth_out

  An optional output variable specifying the depth value to use for this fragment. This is equivalent to gl_FragDepth.

bool cogl_front_facing

  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 in the long term and it may be removed in Cogl 2.0. The experimental CoglShader API is the proposed replacement.

## Functions

### cogl_create_shader ()

    CoglHandle
    cogl_create_shader (CoglShaderType shader_type);

`cogl_create_shader` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

Create a new shader handle, use `cogl_shader_source()` to set the source code to be used on it.

#### Parameters

shader_type | COGL_SHADER_TYPE_VERTEX or COGL_SHADER_TYPE_FRAGMENT. |

#### Returns

a new shader handle.

### cogl_is_shader ()

    CoglBool
    cogl_is_shader (CoglHandle handle);

`cogl_is_shader` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

Gets whether the given handle references an existing shader object.

#### Parameters

handle | A CoglHandle |

#### Returns

`TRUE` if the handle references a shader, `FALSE` otherwise

### cogl_shader_source ()

    void
    cogl_shader_source (CoglHandle shader,
                        const char *source);

`cogl_shader_source` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

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.

#### Parameters

shader | CoglHandle for a shader. |
source | Shader source. |

### cogl_shader_compile ()

    void
    cogl_shader_compile (CoglHandle handle);

`cogl_shader_compile` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

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.

#### Parameters

handle | CoglHandle for a shader. |

### cogl_shader_get_info_log ()

    char *
    cogl_shader_get_info_log (CoglHandle handle);

`cogl_shader_get_info_log` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

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.

#### Parameters

handle | CoglHandle for a shader. |

#### Returns

a newly allocated string containing the info log. Use `g_free()` to free it

### cogl_shader_get_type ()

    CoglShaderType
    cogl_shader_get_type (CoglHandle handle);

`cogl_shader_get_type` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

Retrieves the type of a shader CoglHandle

#### Parameters

handle | 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

### cogl_shader_is_compiled ()

    CoglBool
    cogl_shader_is_compiled (CoglHandle handle);

`cogl_shader_is_compiled` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

Retrieves whether a shader CoglHandle has been compiled

#### Parameters

handle | CoglHandle for a shader. |

#### Returns

`TRUE` if the shader object has sucessfully be compiled

### cogl_create_program ()

    CoglHandle
    cogl_create_program (void);

`cogl_create_program` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

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.

### cogl_is_program ()

    CoglBool
    cogl_is_program (CoglHandle handle);

`cogl_is_program` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

Gets whether the given handle references an existing program object.

#### Parameters

handle | A CoglHandle |

#### Returns

`TRUE` if the handle references a program, `FALSE` otherwise

### cogl_program_attach_shader ()

    void
    cogl_program_attach_shader (CoglHandle program_handle,
                                CoglHandle shader_handle);

`cogl_program_attach_shader` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

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.

#### Parameters

program_handle | a CoglHandle for a shdaer program. |
shader_handle | a CoglHandle for a vertex of fragment shader. |

### cogl_program_link ()

    void
    cogl_program_link (CoglHandle handle);

`cogl_program_link` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api

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.

#### Parameters

handle | a CoglHandle for a shader program. |

### cogl_program_get_uniform_location ()

    int
    cogl_program_get_uniform_location (CoglHandle handle,
                                       const char *uniform_name);

`cogl_program_get_uniform_location` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api instead

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.

#### Parameters

handle | a CoglHandle for a shader program. |
uniform_name | 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.

### cogl_program_set_uniform_1f ()

    void
    cogl_program_set_uniform_1f (CoglHandle program,
                                 int uniform_location,
                                 float value);

`cogl_program_set_uniform_1f` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api instead

Changes the value of a floating point uniform for the given linked `program` .

#### Parameters

program | A CoglHandle for a linked program |
uniform_location | the uniform location retrieved from `cogl_program_get_uniform_location()`. |
value | the new value of the uniform. |

Since 1.4

### cogl_program_set_uniform_1i ()

    void
    cogl_program_set_uniform_1i (CoglHandle program,
                                 int uniform_location,
                                 int value);

`cogl_program_set_uniform_1i` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api instead

Changes the value of an integer uniform for the given linked `program` .

#### Parameters

program | A CoglHandle for a linked program |
uniform_location | the uniform location retrieved from `cogl_program_get_uniform_location()`. |
value | the new value of the uniform. |

Since 1.4

### cogl_program_set_uniform_float ()

    void
    cogl_program_set_uniform_float (CoglHandle program,
                                    int uniform_location,
                                    int n_components,
                                    int count,
                                    const float *value);

`cogl_program_set_uniform_float` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api instead

Changes the value of a float vector uniform, or uniform array for the given linked `program` .

#### Parameters

program | A CoglHandle for a linked program |
uniform_location | the uniform location retrieved from `cogl_program_get_uniform_location()`. |
n_components | The number of components for the uniform. For example with glsl you'd use 3 for a vec3 or 4 for a vec4. |
count | For uniform arrays this is the array length otherwise just pass 1 |
value | the new value of the uniform[s]. | [array length=count]

Since 1.4

### cogl_program_set_uniform_int ()

    void
    cogl_program_set_uniform_int (CoglHandle program,
                                  int uniform_location,
                                  int n_components,
                                  int count,
                                  const int *value);

`cogl_program_set_uniform_int` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api instead

Changes the value of a int vector uniform, or uniform array for the given linked `program` .

#### Parameters

program | A CoglHandle for a linked program |
uniform_location | the uniform location retrieved from `cogl_program_get_uniform_location()`. |
n_components | The number of components for the uniform. For example with glsl you'd use 3 for a vec3 or 4 for a vec4. |
count | For uniform arrays this is the array length otherwise just pass 1 |
value | the new value of the uniform[s]. | [array length=count]

Since 1.4

### cogl_program_set_uniform_matrix ()

    void
    cogl_program_set_uniform_matrix (CoglHandle program,
                                     int uniform_location,
                                     int dimensions,
                                     int count,
                                     CoglBool transpose,
                                     const float *value);

`cogl_program_set_uniform_matrix` has been deprecated since version 1.16 and should not be used in newly-written code.

Use CoglSnippet api instead

Changes the value of a matrix uniform, or uniform array in the given linked `program` .

#### Parameters

program | A CoglHandle for a linked program |
uniform_location | the uniform location retrieved from `cogl_program_get_uniform_location()`. |
dimensions | The dimensions of the matrix. So for for example pass 2 for a 2x2 matrix or 3 for 3x3. |
count | For uniform arrays this is the array length otherwise just pass 1 |
transpose | Whether to transpose the matrix when setting the uniform. |
value | the new value of the uniform. | [array length=count]

Since 1.4

## Types and Values

### enum CoglShaderType

Types of shaders

#### Members

COGL_SHADER_TYPE_VERTEX | A program for proccessing vertices |
COGL_SHADER_TYPE_FRAGMENT | A program for processing fragments |

Since 1.0