offscreen-effect: Rename create_target to create_buffer

*** This is an API change ***

The create_target() virtual function should return a CoglHandle to a
texture; clutter_offscreen_effect_get_target(), instead, returns a
CoglMaterial to be painted in the implementation of the paint_target()
virtual function.

Instead of equating textures with materials, and confusing the user of
the API, we should mark the difference more prominently.

First of all, we should return a CoglMaterial* (now that we have that
as a public type) in get_target(); having handles all over the place
does not make it easier to distinguish the semantics of the virtual
functions.

Then we should rename create_target() to create_texture(), to make it
clear that what should be returned is a texture that is used as the
backing for the offscreen framebuffer.
This commit is contained in:
Emmanuele Bassi 2010-09-01 17:56:15 +01:00
parent 6c40b10083
commit 12a5bf2e06
3 changed files with 32 additions and 29 deletions

View File

@ -53,7 +53,7 @@
* 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
* <function>create_target()</function> virtual function; no chain up
* <function>create_texture()</function> virtual function; no chain up
* to the #ClutterOffscreenEffect implementation is required in this
* case.</para>
* </refsect2>
@ -75,7 +75,7 @@
struct _ClutterOffscreenEffectPrivate
{
CoglHandle offscreen;
CoglHandle target;
CoglMaterial *target;
ClutterActor *actor;
ClutterActor *stage;
@ -120,7 +120,7 @@ clutter_offscreen_effect_set_actor (ClutterActorMeta *meta,
}
static CoglHandle
clutter_offscreen_effect_real_create_target (ClutterOffscreenEffect *effect,
clutter_offscreen_effect_real_create_texture (ClutterOffscreenEffect *effect,
gfloat width,
gfloat height)
{
@ -166,7 +166,7 @@ update_fbo (ClutterEffect *effect)
priv->target = cogl_material_new ();
texture = clutter_offscreen_effect_create_target (self, width, height);
texture = clutter_offscreen_effect_create_texture (self, width, height);
if (texture == COGL_INVALID_HANDLE)
return FALSE;
@ -174,7 +174,7 @@ update_fbo (ClutterEffect *effect)
cogl_handle_unref (texture);
/* we need to use the size of the texture target and not the minimum
* size we passed to the create_target() vfunc, as any sub-class might
* size we passed to the create_texture() vfunc, as any sub-class might
* give use a bigger texture
*/
priv->target_width = cogl_texture_get_width (texture);
@ -401,7 +401,7 @@ clutter_offscreen_effect_class_init (ClutterOffscreenEffectClass *klass)
g_type_class_add_private (klass, sizeof (ClutterOffscreenEffectPrivate));
klass->create_target = clutter_offscreen_effect_real_create_target;
klass->create_texture = clutter_offscreen_effect_real_create_texture;
klass->paint_target = clutter_offscreen_effect_real_paint_target;
meta_class->set_actor = clutter_offscreen_effect_set_actor;
@ -427,13 +427,16 @@ clutter_offscreen_effect_init (ClutterOffscreenEffect *self)
* Retrieves the material used as a render target for the offscreen
* buffer created by @effect
*
* Return value: (transfer none): a handle for a #CoglMaterial, or
* %COGL_INVALID_HANDLE. The returned handle is owned by Clutter
* and it should not be modified or freed
* You should only use the returned #CoglMaterial when painting. The
* returned material might change between different frames.
*
* Return value: (transfer none): a #CoglMaterial or %NULL. The
* returned material is owned by Clutter and it should not be
* modified or freed
*
* Since: 1.4
*/
CoglHandle
CoglMaterial *
clutter_offscreen_effect_get_target (ClutterOffscreenEffect *effect)
{
g_return_val_if_fail (CLUTTER_IS_OFFSCREEN_EFFECT (effect),
@ -459,26 +462,26 @@ clutter_offscreen_effect_paint_target (ClutterOffscreenEffect *effect)
}
/**
* clutter_offscreen_effect_create_target:
* clutter_offscreen_effect_create_texture:
* @effect: a #ClutterOffscreenEffect
* @width: the minimum width of the target texture
* @height: the minimum height of the target texture
*
* Calls the create_target() virtual function of the @effect
* Calls the create_texture() virtual function of the @effect
*
* Return value: a handle to the target texture
* Return value: a handle to a Cogl texture, or %COGL_INVALID_HANDLE
*
* Since: 1.4
*/
CoglHandle
clutter_offscreen_effect_create_target (ClutterOffscreenEffect *effect,
clutter_offscreen_effect_create_texture (ClutterOffscreenEffect *effect,
gfloat width,
gfloat height)
{
g_return_val_if_fail (CLUTTER_IS_OFFSCREEN_EFFECT (effect),
COGL_INVALID_HANDLE);
return CLUTTER_OFFSCREEN_EFFECT_GET_CLASS (effect)->create_target (effect,
return CLUTTER_OFFSCREEN_EFFECT_GET_CLASS (effect)->create_texture (effect,
width,
height);
}

View File

@ -62,7 +62,7 @@ struct _ClutterOffscreenEffect
/**
* ClutterOffscreenEffectClass:
* @create_target: virtual function
* @create_texture: virtual function
* @paint_target: virtual function
*
* The #ClutterOffscreenEffectClass structure contains only private data
@ -75,7 +75,7 @@ struct _ClutterOffscreenEffectClass
ClutterEffectClass parent_class;
/*< public >*/
CoglHandle (* create_target) (ClutterOffscreenEffect *effect,
CoglHandle (* create_texture) (ClutterOffscreenEffect *effect,
gfloat min_width,
gfloat min_height);
void (* paint_target) (ClutterOffscreenEffect *effect);
@ -92,10 +92,10 @@ struct _ClutterOffscreenEffectClass
GType clutter_offscreen_effect_get_type (void) G_GNUC_CONST;
CoglHandle clutter_offscreen_effect_get_target (ClutterOffscreenEffect *effect);
CoglMaterial *clutter_offscreen_effect_get_target (ClutterOffscreenEffect *effect);
void clutter_offscreen_effect_paint_target (ClutterOffscreenEffect *effect);
CoglHandle clutter_offscreen_effect_create_target (ClutterOffscreenEffect *effect,
CoglHandle clutter_offscreen_effect_create_texture (ClutterOffscreenEffect *effect,
gfloat width,
gfloat height);

View File

@ -2388,7 +2388,7 @@ clutter_effect_get_type
ClutterOffscreenEffect
ClutterOffscreenEffectClass
clutter_offscreen_effect_get_target
clutter_offscreen_effect_create_target
clutter_offscreen_effect_create_texture
clutter_offscreen_effect_paint_target
<SUBSECTION Standard>
CLUTTER_TYPE_OFFSCREEN_EFFECT