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

        GObject
        ╰── ClutterShader

## Description

ClutterShader is an object providing an abstraction over the OpenGL programmable pipeline. By using ClutterShader<!-- -->s 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