Class
ClutterEffect
Description [src]
abstract class Clutter.Effect : Clutter.ActorMeta
{
/* No available fields */
}Base class for actor effects
The ClutterEffect class provides a default type and API for creating
effects for generic actors.
Effects are a ClutterActorMeta sub-class that modify the way an actor
is painted in a way that is not part of the actor’s implementation.
Effects should be the preferred way to affect the paint sequence of an
actor without sub-classing the actor itself and overriding the
Clutter.ActorClass.paint virtual function.
Implementing a ClutterEffect
Creating a sub-class of ClutterEffect requires overriding the
Clutter.EffectClass.paint method. The implementation of the function should look
something like this:
void effect_paint (ClutterEffect *effect, ClutterEffectPaintFlags flags)
{
// Set up initialisation of the paint such as binding a
// CoglOffscreen or other operations
// Chain to the next item in the paint sequence. This will either call
// ‘paint’ on the next effect or just paint the actor if this is
// the last effect.
ClutterActor *actor =
clutter_actor_meta_get_actor (CLUTTER_ACTOR_META (effect));
clutter_actor_continue_paint (actor);
// perform any cleanup of state, such as popping the CoglOffscreen
}
The effect can optionally avoid calling clutter_actor_continue_paint() to skip any
further stages of the paint sequence. This is useful for example if the effect
contains a cached image of the actor. In that case it can optimise painting by
avoiding the actor paint and instead painting the cached image.
The CLUTTER_EFFECT_PAINT_ACTOR_DIRTY flag is useful in this case. Clutter will set
this flag when a redraw has been queued on the actor since it was last painted. The
effect can use this information to decide if the cached image is still valid.
A simple ClutterEffect implementation
The example below creates two rectangles: one will be painted “behind” the actor, while another will be painted “on top” of the actor.
The ClutterActorMetaClass.set_actor() implementation will create the two materials
used for the two different rectangles; the ClutterEffectClass.paint() implementation
will paint the first material using cogl_rectangle(), before continuing and then it
will paint paint the second material after.
typedef struct {
ClutterEffect parent_instance;
CoglPipeline *rect_1;
CoglPipeline *rect_2;
} MyEffect;
typedef struct _ClutterEffectClass MyEffectClass;
G_DEFINE_TYPE (MyEffect, my_effect, CLUTTER_TYPE_EFFECT);
static void
my_effect_set_actor (ClutterActorMeta *meta,
ClutterActor *actor)
{
MyEffect *self = MY_EFFECT (meta);
CoglColor color;
// Clear the previous state //
if (self->rect_1)
{
g_object_unref (self->rect_1);
self->rect_1 = NULL;
}
if (self->rect_2)
{
g_object_unref (self->rect_2);
self->rect_2 = NULL;
}
// Maintain a pointer to the actor
self->actor = actor;
// If we've been detached by the actor then we should just bail out here
if (self->actor == NULL)
return;
// Create a red material
self->rect_1 = cogl_pipeline_new ();
cogl_color_init_from_4f (&color, 1.0, 1.0, 1.0, 1.0);
cogl_pipeline_set_color (self->rect_1, &color);
// Create a green material
self->rect_2 = cogl_pipeline_new ();
cogl_color_init_from_4f (&color, 0.0, 1.0, 0.0, 1.0);
cogl_pipeline_set_color (self->rect_2, &color);
}
static gboolean
my_effect_paint (ClutterEffect *effect)
{
MyEffect *self = MY_EFFECT (effect);
gfloat width, height;
clutter_actor_get_size (self->actor, &width, &height);
// Paint the first rectangle in the upper left quadrant
cogl_set_source (self->rect_1);
cogl_rectangle (0, 0, width / 2, height / 2);
// Continue to the rest of the paint sequence
clutter_actor_continue_paint (self->actor);
// Paint the second rectangle in the lower right quadrant
cogl_set_source (self->rect_2);
cogl_rectangle (width / 2, height / 2, width, height);
}
static void
my_effect_class_init (MyEffectClass *klass)
{
ClutterActorMetaClass *meta_class = CLUTTER_ACTOR_META_CLASS (klass);
meta_class->set_actor = my_effect_set_actor;
klass->paint = my_effect_paint;
}
Instance methods
clutter_effect_queue_repaint
Queues a repaint of the effect. The effect can detect when the ‘paint’
method is called as a result of this function because it will not
have the CLUTTER_EFFECT_PAINT_ACTOR_DIRTY flag set. In that case the
effect is free to assume that the actor has not changed its
appearance since the last time it was painted so it doesn’t need to
call clutter_actor_continue_paint() if it can draw a cached
image. This is mostly intended for effects that are using a
%CoglOffscreen to redirect the actor (such as
%ClutterOffscreenEffect). In that case the effect can save a bit of
rendering time by painting the cached texture without causing the
entire actor to be painted.
Methods inherited from ClutterActorMeta (5)
clutter_actor_meta_get_actor
Retrieves a pointer to the ClutterActor that owns meta.
clutter_actor_meta_get_enabled
Retrieves whether meta is enabled.
clutter_actor_meta_get_name
Retrieves the name set using clutter_actor_meta_set_name().
clutter_actor_meta_set_enabled
Sets whether meta should be enabled or not.
clutter_actor_meta_set_name
Sets the name of meta.
Properties
Properties inherited from ClutterActorMeta (3)
Clutter.ActorMeta:actor
The ClutterActor attached to the ClutterActorMeta instance.
Clutter.ActorMeta:enabled
Whether or not the ClutterActorMeta is enabled.
Clutter.ActorMeta:name
The unique name to access the ClutterActorMeta.
Signals
Signals inherited from GObject (1)
GObject::notify
The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.
Class structure
struct ClutterEffectClass {
gboolean (* pre_paint) (
ClutterEffect* effect,
ClutterPaintNode* node,
ClutterPaintContext* paint_context
);
void (* post_paint) (
ClutterEffect* effect,
ClutterPaintNode* node,
ClutterPaintContext* paint_context
);
gboolean (* modify_paint_volume) (
ClutterEffect* effect,
ClutterPaintVolume* volume
);
void (* paint) (
ClutterEffect* effect,
ClutterPaintNode* node,
ClutterPaintContext* paint_context,
ClutterEffectPaintFlags flags
);
void (* paint_node) (
ClutterEffect* effect,
ClutterPaintNode* node,
ClutterPaintContext* paint_context,
ClutterEffectPaintFlags flags
);
void (* pick) (
ClutterEffect* effect,
ClutterPickContext* pick_context
);
}The ClutterEffectClass structure contains only private data.
Class members
pre_paint: gboolean (* pre_paint) ( ClutterEffect* effect, ClutterPaintNode* node, ClutterPaintContext* paint_context )Virtual function.
post_paint: void (* post_paint) ( ClutterEffect* effect, ClutterPaintNode* node, ClutterPaintContext* paint_context )Virtual function.
modify_paint_volume: gboolean (* modify_paint_volume) ( ClutterEffect* effect, ClutterPaintVolume* volume )Virtual function.
paint: void (* paint) ( ClutterEffect* effect, ClutterPaintNode* node, ClutterPaintContext* paint_context, ClutterEffectPaintFlags flags )Virtual function.
paint_node: void (* paint_node) ( ClutterEffect* effect, ClutterPaintNode* node, ClutterPaintContext* paint_context, ClutterEffectPaintFlags flags )No description available.
pick: void (* pick) ( ClutterEffect* effect, ClutterPickContext* pick_context )Virtual function.