## Shaders and Programmable Pipeline

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

## Synopsis

    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);

## Description

COGL allows accessing the GL programmable pipeline in order to create vertex and fragment shaders.

The only supported format is GLSL shaders.

## Details

### enum CoglShaderType

    typedef enum {
      COGL_SHADER_TYPE_VERTEX,
      COGL_SHADER_TYPE_FRAGMENT
    } CoglShaderType;

Types of shaders

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

Since 1.0

### cogl_create_shader ()

    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.

`shader_type` : | COGL_SHADER_TYPE_VERTEX or COGL_SHADER_TYPE_FRAGMENT.
Returns : | a new shader handle.

### cogl_is_shader ()

    gboolean            cogl_is_shader                      (CoglHandle handle);

Gets whether the given handle references an existing shader object.

`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);

Replaces the current GLSL source associated with a shader with a new one.

`shader` : | CoglHandle for a shader.
`source` : | GLSL shader source.

### cogl_shader_compile ()

    void                cogl_shader_compile                 (CoglHandle handle);

Compiles the shader, no return value, but the shader is now ready for linking into a program.

`handle` : | CoglHandle for a shader.

### cogl_shader_get_info_log ()

    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.

`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);

Retrieves the type of a shader CoglHandle

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

    gboolean            cogl_shader_is_compiled             (CoglHandle handle);

Retrieves whether a shader CoglHandle has been compiled

`handle` : | CoglHandle for a shader.
Returns : | `TRUE` if the shader object has sucessfully be compiled

### cogl_create_program ()

    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.

### cogl_is_program ()

    gboolean            cogl_is_program                     (CoglHandle handle);

Gets whether the given handle references an existing program object.

`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);

Attaches a shader to a program object, a program can have one vertex shader and one fragment shader attached.

`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);

Links a program making it ready for use.

`handle` : | a CoglHandle for a shader program.

### cogl_program_get_uniform_location ()

    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.

`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);

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

`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);

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

`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);

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

`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);

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

`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,
                                                             gboolean transpose,
                                                             const float *value);

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

`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