
@c %start of fragment

@node ClutterShaderEffect
@chapter ClutterShaderEffect
Base class for shader effects

@section Overview
@code{<clutter-shader-effect>} is a class that implements all the
plumbing for creating @code{<clutter-effect>}s using GLSL shaders.

@code{<clutter-shader-effect>} creates an offscreen buffer and then
applies the GLSL shader (after checking whether the compilation and
linking were successfull) to the buffer before painting it on screen.

@section Implementing a ClutterShaderEffect
Creating a sub-class of @code{<clutter-shader-effect>} requires the
overriding of the @code{@code{paint-target}} virtual function from the
@code{<clutter-offscreen-effect>} class as well as the
@code{@code{get-static-shader-source}} virtual from the
@code{<clutter-shader-effect>} class.

The @code{@code{get-static-shader-source}} function should return a copy
of the shader source to use. This function is only called once per
subclass of @code{<clutter-shader-effect>} regardless of how many
instances of the effect are created. The source for the shader is
typically stored in a static const string which is returned from this
function via @code{g-strdup}.

The @code{@code{paint-target}} should set the shader's uniforms if any.
This is done by calling @code{clutter-shader-effect-set-uniform-value}
or @code{clutter-shader-effect-set-uniform}. The sub-class should then
chain up to the @code{<clutter-shader-effect>} implementation.

@c (example (@ (id "ClutterShaderEffect-example-uniforms")))
@c (title "Setting uniforms on a ClutterShaderEffect")
The example below shows a typical implementation of the
@code{@code{get-static-shader-source}} and @code{@code{paint-target}}
phases of a @code{<clutter-shader-effect>} sub-class.

@example 

 static gchar *
 my_effect_get_static_shader_source (ClutterShaderEffect *effect)
 @{
   return g_strdup (shader_source);
 @}

 static gboolean
 my_effect_paint_target (ClutterOffscreenEffect *effect)
 @{
   MyEffect *self = MY_EFFECT (effect);
   ClutterShaderEffect *shader = CLUTTER_SHADER_EFFECT (effect);
   ClutterEffectClass *parent_class;
   gfloat component_r, component_g, component_b;

   /&#x002A; the "tex" uniform is declared in the shader as:
    &#x002A;
    &#x002A;   uniform int tex;
    &#x002A;
    &#x002A; and it is passed a constant value of 0
    &#x002A;/
   clutter_shader_effect_set_uniform (shader, "tex", G_TYPE_INT, 1, 0);

   /&#x002A; the "component" uniform is declared in the shader as:
    &#x002A;
    &#x002A;   uniform vec3 component;
    &#x002A;
    &#x002A; and it's defined to contain the normalized components
    &#x002A; of a ClutterColor
    &#x002A;/
   component_r = self->color.red   / 255.0f;
   component_g = self->color.green / 255.0f;
   component_b = self->color.blue  / 255.0f;
   clutter_shader_effect_set_uniform (shader, "component",
                                      G_TYPE_FLOAT, 3,
                                      component_r,
                                      component_g,
                                      component_b);

   /&#x002A; chain up to the parent's implementation &#x002A;/
   parent_class = CLUTTER_OFFSCREEN_EFFECT_CLASS (my_effect_parent_class);
   return parent_class->paint_target (effect);
 @}
    
@end example

@code{<clutter-shader-effect>} is available since Clutter 1.4

@section Usage
@include defuns-clutter-shader-effect.xml.texi

@c %end of fragment
