Shaders: Clutter Reference Manual

## Shaders Shaders — Programmable pipeline abstraction |

## Functions

ClutterShader * | clutter_shader_new ()
void | clutter_shader_set_vertex_source ()
const gchar * | clutter_shader_get_vertex_source ()
void | clutter_shader_set_fragment_source ()
const gchar * | clutter_shader_get_fragment_source ()
gboolean | clutter_shader_compile ()
void | clutter_shader_release ()
gboolean | clutter_shader_is_compiled ()
void | clutter_shader_set_is_enabled ()
gboolean | clutter_shader_get_is_enabled ()
void | clutter_shader_set_uniform ()
CoglHandle | clutter_shader_get_cogl_program ()
CoglHandle | clutter_shader_get_cogl_fragment_shader ()
CoglHandle | clutter_shader_get_cogl_vertex_shader ()
#define | CLUTTER_VALUE_HOLDS_SHADER_FLOAT()
void | clutter_value_set_shader_float ()
const gfloat * | clutter_value_get_shader_float ()
#define | CLUTTER_VALUE_HOLDS_SHADER_INT()
void | clutter_value_set_shader_int ()
const gint * | clutter_value_get_shader_int ()
#define | CLUTTER_VALUE_HOLDS_SHADER_MATRIX()
void | clutter_value_set_shader_matrix ()
const gfloat * | clutter_value_get_shader_matrix ()

## Properties

gboolean | compiled | Read
gboolean | enabled | Read / Write
gchar * | fragment-source | Read / Write
gchar * | vertex-source | Read / Write

## Types and Values

enum | ClutterShaderError
| ClutterShader
struct | ClutterShaderClass

## Object Hierarchy

        ClutterShaderFloat
        ClutterShaderInt
        ClutterShaderMatrix
        GObject
        ╰── ClutterShader

## Description

ClutterShader is an object providing an abstraction over the OpenGL programmable pipeline. By using ClutterShaders is possible to override the drawing pipeline by using small programs also known as "shaders".

ClutterShader is available since Clutter 0.6.

ClutterShader is deprecated since Clutter 1.8; use ClutterShaderEffect in newly written code, instead.

## Functions

### clutter_shader_new ()

    ClutterShader *
    clutter_shader_new (void);

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

Use ClutterShaderEffect instead.

Create a new ClutterShader instance.

#### Returns

a new ClutterShader.

Since: 0.6

### clutter_shader_set_vertex_source ()

    void
    clutter_shader_set_vertex_source (ClutterShader *shader,
                                      const gchar *data,
                                      gssize length);

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

Use ClutterShaderEffect instead.

Sets the GLSL source code to be used by a ClutterShader for the vertex program.

#### Parameters

shader | a ClutterShader |
data | GLSL source code. |
length | length of source buffer (currently ignored) |

Since: 0.6

### clutter_shader_get_vertex_source ()

    const gchar *
    clutter_shader_get_vertex_source (ClutterShader *shader);

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

Use ClutterShaderEffect instead.

Query the current GLSL vertex source set on `shader` .

#### Parameters

shader | a ClutterShader |

#### Returns

the source of the vertex shader for this ClutterShader object or `NULL`. The returned string is owned by the shader object and should never be modified or freed

Since: 0.6

### clutter_shader_set_fragment_source ()

    void
    clutter_shader_set_fragment_source (ClutterShader *shader,
                                        const gchar *data,
                                        gssize length);

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

Use ClutterShaderEffect instead.

Sets the GLSL source code to be used by a ClutterShader for the fragment program.

#### Parameters

shader | a ClutterShader |
data | GLSL source code. |
length | length of source buffer (currently ignored) |

Since: 0.6

### clutter_shader_get_fragment_source ()

    const gchar *
    clutter_shader_get_fragment_source (ClutterShader *shader);

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

Use ClutterShaderEffect instead.

Query the current GLSL fragment source set on `shader` .

#### Parameters

shader | a ClutterShader |

#### Returns

the source of the fragment shader for this ClutterShader object or `NULL`. The returned string is owned by the shader object and should never be modified or freed

Since: 0.6

### clutter_shader_compile ()

    gboolean
    clutter_shader_compile (ClutterShader *shader,
                            GError **error);

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

Use ClutterShaderEffect instead.

Compiles and links GLSL sources set for vertex and fragment shaders for a ClutterShader. If the compilation fails and a GError return location is provided the error will contain the errors from the compiler, if any.

#### Parameters

shader | a ClutterShader |
error | return location for a GError, or `NULL` |

#### Returns

returns TRUE if the shader was succesfully compiled.

Since: 0.8

### clutter_shader_release ()

    void
    clutter_shader_release (ClutterShader *shader);

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

Use ClutterShaderEffect instead.

Frees up any GL context resources held by the shader.

#### Parameters

shader | a ClutterShader |

Since: 0.6

### clutter_shader_is_compiled ()

    gboolean
    clutter_shader_is_compiled (ClutterShader *shader);

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

Use ClutterShaderEffect instead.

Checks whether `shader` is is currently compiled, linked and bound to the GL context.

#### Parameters

shader | a ClutterShader |

#### Returns

`TRUE` if the shader is compiled, linked and ready for use.

Since: 0.8

### clutter_shader_set_is_enabled ()

    void
    clutter_shader_set_is_enabled (ClutterShader *shader,
                                   gboolean enabled);

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

Use ClutterShaderEffect instead.

Enables a shader. This function will attempt to compile and link the shader, if it isn't already.

When `enabled` is `FALSE` the default state of the GL pipeline will be used instead.

#### Parameters

shader | a ClutterShader |
enabled | The new state of the shader. |

Since: 0.6

### clutter_shader_get_is_enabled ()

    gboolean
    clutter_shader_get_is_enabled (ClutterShader *shader);

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

Use ClutterShaderEffect instead.

Checks whether `shader` is enabled.

#### Parameters

shader | a ClutterShader |

#### Returns

`TRUE` if the shader is enabled.

Since: 0.6

### clutter_shader_set_uniform ()

    void
    clutter_shader_set_uniform (ClutterShader *shader,
                                const gchar *name,
                                const GValue *value);

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

Use ClutterShaderEffect instead.

Sets a user configurable variable in the GLSL shader programs attached to a ClutterShader.

#### Parameters

shader | a ClutterShader. |
name | name of uniform in GLSL shader program to set. |
value | a ClutterShaderFloat, ClutterShaderInt or ClutterShaderMatrix GValue. |

Since: 1.0

### clutter_shader_get_cogl_program ()

    CoglHandle
    clutter_shader_get_cogl_program (ClutterShader *shader);

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

Use ClutterShaderEffect instead.

Retrieves the underlying CoglHandle for the shader program.

#### Parameters

shader | a ClutterShader |

#### Returns

A CoglHandle for the shader program, or `NULL`. The handle is owned by the ClutterShader and it should not be unreferenced.

[transfer none]

Since: 1.0

### clutter_shader_get_cogl_fragment_shader ()

    CoglHandle
    clutter_shader_get_cogl_fragment_shader
                                   (ClutterShader *shader);

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

Use ClutterShaderEffect instead.

Retrieves the underlying CoglHandle for the fragment shader.

#### Parameters

shader | a ClutterShader |

#### Returns

A CoglHandle for the fragment shader, or `NULL`. The handle is owned by the ClutterShader and it should not be unreferenced.

[transfer none]

Since: 1.0

### clutter_shader_get_cogl_vertex_shader ()

    CoglHandle
    clutter_shader_get_cogl_vertex_shader (ClutterShader *shader);

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

Use ClutterShaderEffect instead.

Retrieves the underlying CoglHandle for the vertex shader.

#### Parameters

shader | a ClutterShader |

#### Returns

A CoglHandle for the vertex shader, or `NULL`. The handle is owned by the ClutterShader and it should not be unreferenced.

[transfer none]

Since: 1.0

### CLUTTER_VALUE_HOLDS_SHADER_FLOAT()

    #define CLUTTER_VALUE_HOLDS_SHADER_FLOAT(x) (G_VALUE_HOLDS ((x), CLUTTER_TYPE_SHADER_FLOAT))

Evaluates to `TRUE` if `x` holds a ClutterShaderFloat.

#### Parameters

x | a GValue |

Since: 1.0

### clutter_value_set_shader_float ()

    void
    clutter_value_set_shader_float (GValue *value,
                                    gint size,
                                    const gfloat *floats);

Sets `floats` as the contents of `value` . The passed GValue must have been initialized using `CLUTTER_TYPE_SHADER_FLOAT`.

#### Parameters

value | a GValue |
size | number of floating point values in `floats` |
floats | an array of floating point values. | [array length=size]

Since: 0.8

### clutter_value_get_shader_float ()

    const gfloat *
    clutter_value_get_shader_float (const GValue *value,
                                    gsize *length);

Retrieves the list of floating point values stored inside the passed GValue. `value` must have been initialized with `CLUTTER_TYPE_SHADER_FLOAT`.

#### Parameters

value | a GValue |
length | return location for the number of returned floating point values, or `NULL`. | [out]

#### Returns

the pointer to a list of floating point values. The returned value is owned by the GValue and should never be modified or freed.

[array length=length]

Since: 0.8

### CLUTTER_VALUE_HOLDS_SHADER_INT()

    #define CLUTTER_VALUE_HOLDS_SHADER_INT(x) (G_VALUE_HOLDS ((x), CLUTTER_TYPE_SHADER_INT))

Evaluates to `TRUE` if `x` holds a ClutterShaderInt.

#### Parameters

x | a GValue |

Since: 1.0

### clutter_value_set_shader_int ()

    void
    clutter_value_set_shader_int (GValue *value,
                                  gint size,
                                  const gint *ints);

Sets `ints` as the contents of `value` . The passed GValue must have been initialized using `CLUTTER_TYPE_SHADER_INT`.

#### Parameters

value | a GValue |
size | number of integer values in `ints` |
ints | an array of integer values. | [array length=size]

Since: 0.8

### clutter_value_get_shader_int ()

    const gint *
    clutter_value_get_shader_int (const GValue *value,
                                  gsize *length);

Retrieves the list of integer values stored inside the passed GValue. `value` must have been initialized with `CLUTTER_TYPE_SHADER_INT`.

#### Parameters

value | a GValue |
length | return location for the number of returned integer values, or `NULL`. | [out]

#### Returns

the pointer to a list of integer values. The returned value is owned by the GValue and should never be modified or freed.

[array length=length]

Since: 0.8

### CLUTTER_VALUE_HOLDS_SHADER_MATRIX()

    #define CLUTTER_VALUE_HOLDS_SHADER_MATRIX(x) (G_VALUE_HOLDS ((x), CLUTTER_TYPE_SHADER_MATRIX))

Evaluates to `TRUE` if `x` holds a ClutterShaderMatrix.

#### Parameters

x | a GValue |

Since: 1.0

### clutter_value_set_shader_matrix ()

    void
    clutter_value_set_shader_matrix (GValue *value,
                                     gint size,
                                     const gfloat *matrix);

Sets `matrix` as the contents of `value` . The passed GValue must have been initialized using `CLUTTER_TYPE_SHADER_MATRIX`.

#### Parameters

value | a GValue |
size | number of floating point values in `floats` |
matrix | a matrix of floating point values. | [array length=size]

Since: 0.8

### clutter_value_get_shader_matrix ()

    const gfloat *
    clutter_value_get_shader_matrix (const GValue *value,
                                     gsize *length);

Retrieves a matrix of floating point values stored inside the passed GValue. `value` must have been initialized with `CLUTTER_TYPE_SHADER_MATRIX`.

#### Parameters

value | a GValue |
length | return location for the number of returned floating point values, or `NULL`. | [out]

#### Returns

the pointer to a matrix of floating point values. The returned value is owned by the GValue and should never be modified or freed.

[array length=length][transfer none]

Since: 0.8

## Types and Values

### enum ClutterShaderError

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

ClutterShader error enumeration

#### Members

CLUTTER_SHADER_ERROR_NO_ASM | No ASM shaders support |
CLUTTER_SHADER_ERROR_NO_GLSL | No GLSL shaders support |
CLUTTER_SHADER_ERROR_COMPILE | Compilation error |

Since: 0.6

### ClutterShader

    typedef struct _ClutterShader ClutterShader;

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

Use ClutterShaderEffect instead

The ClutterShader structure contains only private data and should be accessed using the provided API

Since: 0.6

### struct ClutterShaderClass

    struct ClutterShaderClass {
    };

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

Use ClutterShaderEffectClass instead

The ClutterShaderClass structure contains only private data

Since: 0.6

## Property Details

### The `“compiled”` property

      “compiled”                 gboolean

Whether the shader is compiled and linked, ready for use in the GL context.

`ClutterShader:compiled` has been deprecated since version 1.8 and should not be used in newly-written code.

Use ClutterShaderEffect instead.

Flags: Read

Default value: FALSE

Since: 0.8

### The `“enabled”` property

      “enabled”                  gboolean

Whether the shader is currently used in the GL rendering pipeline.

`ClutterShader:enabled` has been deprecated since version 1.8 and should not be used in newly-written code.

Use ClutterShaderEffect instead.

Flags: Read / Write

Default value: FALSE

Since: 0.6

### The `“fragment-source”` property

      “fragment-source”          gchar *

GLSL source code for the fragment shader part of the shader program.

`ClutterShader:fragment-source` has been deprecated since version 1.8 and should not be used in newly-written code.

Use ClutterShaderEffect instead.

Flags: Read / Write

Default value: NULL

Since: 0.6

### The `“vertex-source”` property

      “vertex-source”            gchar *

GLSL source code for the vertex shader part of the shader program, if any

`ClutterShader:vertex-source` has been deprecated since version 1.8 and should not be used in newly-written code.

Use ClutterShaderEffect instead.

Flags: Read / Write

Default value: NULL

Since: 0.6