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);
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);
gchar *             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);
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);
int                 cogl_program_get_uniform_location   (CoglHandle handle,
                                                         const char *uniform_name);
void                cogl_program_uniform_1f             (int uniform_no,
                                                         float value);
void                cogl_program_uniform_1i             (int uniform_no,
                                                         int value);
void                cogl_program_uniform_float          (int uniform_no,
                                                         int size,
                                                         int count,
                                                         const GLfloat *value);
void                cogl_program_uniform_int            (int uniform_no,
                                                         int size,
                                                         int count,
                                                         const int *value);
void                cogl_program_uniform_matrix         (int uniform_no,
                                                         int size,
                                                         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 :

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

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

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

void                cogl_program_uniform_1f             (int uniform_no,
                                                         float value);

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

uniform_no :

the unform to set.

value :

the new value of the uniform.

cogl_program_uniform_1i ()

void                cogl_program_uniform_1i             (int uniform_no,
                                                         int value);

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

uniform_no :

the unform to set.

value :

the new value of the uniform.

cogl_program_uniform_float ()

void                cogl_program_uniform_float          (int uniform_no,
                                                         int size,
                                                         int count,
                                                         const GLfloat *value);

Changes the value of a float vector uniform, or uniform array in the currently used (see cogl_program_use) shader program.

uniform_no :

the uniform to set.

size :

Size of float vector.

count :

Size of array of uniforms.

value :

the new value of the uniform.

cogl_program_uniform_int ()

void                cogl_program_uniform_int            (int uniform_no,
                                                         int size,
                                                         int count,
                                                         const int *value);

Changes the value of a int vector uniform, or uniform array in the currently used (see cogl_program_use()) shader program.

uniform_no :

the uniform to set.

size :

Size of int vector.

count :

Size of array of uniforms.

value :

the new value of the uniform.

cogl_program_uniform_matrix ()

void                cogl_program_uniform_matrix         (int uniform_no,
                                                         int size,
                                                         int count,
                                                         gboolean transpose,
                                                         const float *value);

Changes the value of a matrix uniform, or uniform array in the currently used (see cogl_program_use()) shader program. The size parameter is used to determine the square size of the matrix.

uniform_no :

the uniform to set.

size :

Size of matrix.

count :

Size of array of uniforms.

transpose :

Whether to transpose the matrix when setting the uniform.

value :

the new value of the uniform.