ClutterOffscreenEffect: Clutter Reference Manual

## ClutterOffscreenEffect ClutterOffscreenEffect — Base class for effects using offscreen buffers |

## Functions

CoglMaterial * | clutter_offscreen_effect_get_target ()
CoglHandle | clutter_offscreen_effect_get_texture ()
CoglHandle | clutter_offscreen_effect_create_texture ()
void | clutter_offscreen_effect_paint_target ()
gboolean | clutter_offscreen_effect_get_target_size ()
gboolean | clutter_offscreen_effect_get_target_rect ()

## Types and Values

struct | ClutterOffscreenEffect
struct | ClutterOffscreenEffectClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActorMeta
                ╰── ClutterEffect
                    ╰── ClutterOffscreenEffect
                        ├── ClutterBlurEffect
                        ├── ClutterBrightnessContrastEffect
                        ├── ClutterColorizeEffect
                        ├── ClutterDeformEffect
                        ├── ClutterDesaturateEffect
                        ╰── ClutterShaderEffect

## Description

ClutterOffscreenEffect is an abstract class that can be used by ClutterEffect sub-classes requiring access to an offscreen buffer.

Some effects, like the fragment shader based effects, can only use GL textures, and in order to apply those effects to any kind of actor they require that all drawing operations are applied to an offscreen framebuffer that gets redirected to a texture.

ClutterOffscreenEffect provides all the heavy-lifting for creating the offscreen framebuffer, the redirection and the final paint of the texture on the desired stage.

ClutterOffscreenEffect is available since Clutter 1.4

#### Implementing a ClutterOffscreenEffect

Creating a sub-class of ClutterOffscreenEffect requires, in case of overriding the ClutterEffect virtual functions, to chain up to the ClutterOffscreenEffect's implementation.

On top of the ClutterEffect's virtual functions, ClutterOffscreenEffect also provides a `ClutterOffscreenEffectClass.paint_target()` function, which encapsulates the effective painting of the texture that contains the result of the offscreen redirection.

The size of the target material is defined to be as big as the transformed size of the ClutterActor using the offscreen effect. Sub-classes of ClutterOffscreenEffect can change the texture creation code to provide bigger textures by overriding the `ClutterOffscreenEffectClass.create_texture()` virtual function; no chain up to the ClutterOffscreenEffect implementation is required in this case.

## Functions

### clutter_offscreen_effect_get_target ()

    CoglMaterial *
    clutter_offscreen_effect_get_target (ClutterOffscreenEffect *effect);

Retrieves the material used as a render target for the offscreen buffer created by `effect`

You should only use the returned CoglMaterial when painting. The returned material might change between different frames.

#### Parameters

effect | a ClutterOffscreenEffect |

#### Returns

a CoglMaterial or `NULL`. The returned material is owned by Clutter and it should not be modified or freed.

[transfer none]

Since: 1.4

### clutter_offscreen_effect_get_texture ()

    CoglHandle
    clutter_offscreen_effect_get_texture (ClutterOffscreenEffect *effect);

Retrieves the texture used as a render target for the offscreen buffer created by `effect`

You should only use the returned texture when painting. The texture may change after ClutterEffect::pre_paint is called so the effect implementation should update any references to the texture after chaining-up to the parent's pre_paint implementation. This can be used instead of `clutter_offscreen_effect_get_target()` when the effect subclass wants to paint using its own material.

#### Parameters

effect | a ClutterOffscreenEffect |

#### Returns

a CoglHandle or `COGL_INVALID_HANDLE`. The returned texture is owned by Clutter and it should not be modified or freed.

[transfer none]

Since: 1.10

### clutter_offscreen_effect_create_texture ()

    CoglHandle
    clutter_offscreen_effect_create_texture
                                   (ClutterOffscreenEffect *effect,
                                    gfloat width,
                                    gfloat height);

Calls the `create_texture()` virtual function of the `effect`

#### Parameters

effect | a ClutterOffscreenEffect |
width | the minimum width of the target texture |
height | the minimum height of the target texture |

#### Returns

a handle to a Cogl texture, or `COGL_INVALID_HANDLE`. The returned handle has its reference count increased.

[transfer full]

Since: 1.4

### clutter_offscreen_effect_paint_target ()

    void
    clutter_offscreen_effect_paint_target (ClutterOffscreenEffect *effect);

Calls the `paint_target()` virtual function of the `effect`

#### Parameters

effect | a ClutterOffscreenEffect |

Since: 1.4

### clutter_offscreen_effect_get_target_size ()

    gboolean
    clutter_offscreen_effect_get_target_size
                                   (ClutterOffscreenEffect *effect,
                                    gfloat *width,
                                    gfloat *height);

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

Use `clutter_offscreen_effect_get_target_rect()` instead

Retrieves the size of the offscreen buffer used by `effect` to paint the actor to which it has been applied.

This function should only be called by ClutterOffscreenEffect implementations, from within the `ClutterOffscreenEffectClass.paint_target()` virtual function.

#### Parameters

effect | a ClutterOffscreenEffect |
width | return location for the target width, or `NULL`. | [out]
height | return location for the target height, or `NULL`. | [out]

#### Returns

`TRUE` if the offscreen buffer has a valid size, and `FALSE` otherwise

Since: 1.8

### clutter_offscreen_effect_get_target_rect ()

    gboolean
    clutter_offscreen_effect_get_target_rect
                                   (ClutterOffscreenEffect *effect,
                                    ClutterRect *rect);

Retrieves the origin and size of the offscreen buffer used by `effect` to paint the actor to which it has been applied.

This function should only be called by ClutterOffscreenEffect implementations, from within the `ClutterOffscreenEffectClass.paint_target()` virtual function.

#### Parameters

effect | a ClutterOffscreenEffect |
rect | return location for the target area. | [out caller-allocates]

#### Returns

`TRUE` if the offscreen buffer has a valid rectangle, and `FALSE` otherwise

Since: 1.14

## Types and Values

### struct ClutterOffscreenEffect

    struct ClutterOffscreenEffect;

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

Since: 1.4

### struct ClutterOffscreenEffectClass

    struct ClutterOffscreenEffectClass {
      CoglHandle (* create_texture) (ClutterOffscreenEffect *effect,
                                     gfloat                  width,
                                     gfloat                  height);
      void       (* paint_target)   (ClutterOffscreenEffect *effect);
    };

The ClutterOffscreenEffectClass structure contains only private data

#### Members

`create_texture` () | virtual function |
`paint_target` () | virtual function |

Since: 1.4

## See Also

ClutterBlurEffect, ClutterEffect