ClutterOffscreenEffect

ClutterOffscreenEffect — Base class for effects using offscreen buffers

Synopsis

struct              ClutterOffscreenEffect;
struct              ClutterOffscreenEffectClass;
CoglMaterial *      clutter_offscreen_effect_get_target (ClutterOffscreenEffect *effect);
CoglHandle          clutter_offscreen_effect_create_texture
                                                        (ClutterOffscreenEffect *effect,
                                                         gfloat width,
                                                         gfloat height);
void                clutter_offscreen_effect_paint_target
                                                        (ClutterOffscreenEffect *effect);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----ClutterActorMeta
               +----ClutterEffect
                     +----ClutterOffscreenEffect
                           +----ClutterBlurEffect
                           +----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.

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 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 create_texture() virtual function; no chain up to the ClutterOffscreenEffect implementation is required in this case.

ClutterOffscreenEffect is available since Clutter 1.4

Details

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                  min_width,
                                gfloat                  min_height);
  void       (* paint_target)  (ClutterOffscreenEffect *effect);
};

The ClutterOffscreenEffectClass structure contains only private data

create_texture ()

virtual function

paint_target ()

virtual function

Since 1.4


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.

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

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

Calls the create_texture() virtual function of the effect

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

Since 1.4

See Also

ClutterBlurEffect, ClutterEffect