## Shaders and Programmable Pipeline

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

## Synopsis

    CoglHandle          cogl_create_shader                  (COGLenum shader_type);
    CoglHandle          cogl_shader_ref                     (CoglHandle handle);
    void                cogl_shader_unref                   (CoglHandle handle);
    gboolean            cogl_is_shader                      (CoglHandle handle);
    void                cogl_shader_source                  (CoglHandle shader,
                                                             const gchar *source);
    void                cogl_shader_compile                 (CoglHandle handle);
    void                cogl_shader_get_info_log            (CoglHandle handle,
                                                             guint size,
                                                             gchar *buffer);
    void                cogl_shader_get_parameteriv         (CoglHandle handle,
                                                             COGLenum pname,
                                                             COGLint *dest);

    CoglHandle          cogl_create_program                 (void);
    CoglHandle          cogl_program_ref                    (CoglHandle handle);
    void                cogl_program_unref                  (CoglHandle handle);
    gboolean            cogl_is_program                     (CoglHandle handle);
    void                cogl_program_attach_shader          (CoglHandle program_handle,
                                                             CoglHandle shader_handle);
    void                cogl_program_link                   (CoglHandle handle);
    void                cogl_program_use                    (CoglHandle handle);
    COGLint             cogl_program_get_uniform_location   (CoglHandle handle,
                                                             const gchar *uniform_name);
    void                cogl_program_uniform_1f             (COGLint uniform_no,
                                                             gfloat 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

### cogl_create_shader ()

    CoglHandle          cogl_create_shader                  (COGLenum shader_type);

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

`shader_type` : | CGL_VERTEX_SHADER or CGL_FRAGMENT_SHADER.
Returns : | a new shader handle.

### cogl_shader_ref ()

    CoglHandle          cogl_shader_ref                     (CoglHandle handle);

Add an extra reference to a shader.

`handle` : | A CoglHandle to a shader.
Returns : | `handle`

### cogl_shader_unref ()

    void                cogl_shader_unref                   (CoglHandle handle);

Removes a reference to a shader. If it was the last reference the shader object will be destroyed.

`handle` : | A CoglHandle to a shader.

### 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 gchar *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 ()

    void                cogl_shader_get_info_log            (CoglHandle handle,
                                                             guint size,
                                                             gchar *buffer);

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.
`size` : | maximum number of bytes to retrieve.
`buffer` : | location for info log.

### cogl_shader_get_parameteriv ()

    void                cogl_shader_get_parameteriv         (CoglHandle handle,
                                                             COGLenum pname,
                                                             COGLint *dest);

Retrieve a named parameter from a shader can be used to query to compile satus of a shader by passing in CGL_OBJECT_COMPILE_STATUS for `pname`.

`handle` : | CoglHandle for a shader.
`pname` : | the named COGL parameter to retrieve.
`dest` : | storage location for COGLint return value.

### 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_program_ref ()

    CoglHandle          cogl_program_ref                    (CoglHandle handle);

Add an extra reference to a program.

`handle` : | A CoglHandle to a program.
Returns : | `handle`

### cogl_program_unref ()

    void                cogl_program_unref                  (CoglHandle handle);

Removes a reference to a program. If it was the last reference the program object will be destroyed.

`handle` : | A CoglHandle to a 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_use ()

    void                cogl_program_use                    (CoglHandle handle);

Activate a specific shader program replacing that part of the GL rendering pipeline, if passed in COGL_INVALID_HANDLE the default behavior of GL is reinstated.

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

### cogl_program_get_uniform_location ()

    COGLint             cogl_program_get_uniform_location   (CoglHandle handle,
                                                             const gchar *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_uniform_1f ()

    void                cogl_program_uniform_1f             (COGLint uniform_no,
                                                             gfloat value);

Changes the value of a uniform in the currently used (see cogl_program_use) shader program.

`uniform_no` : | the unform to set.
`value` : | the new value of the uniform.