brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add PaintVolume to the API reference

Browse Source 
And document the various related functions.
This commit is contained in:
Emmanuele Bassi 2010-08-19 15:27:51 +01:00 committed by Robert Bragg
parent a6e5ecebe3
commit 044809edb8
2 changed files with 182 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

166
clutter/clutter-actor.c
View File

@ -11514,6 +11514,17 @@ clutter_paint_volume_get_type (void)
return our_type; return our_type;
} }
/*<private>
* _clutter_paint_volume_new:
* @actor: a #ClutterActor
*
* Creates a new #ClutterPaintVolume for the given @actor.
*
* Return value: the newly allocated #ClutterPaintVolume. Use
* clutter_paint_volume_free() to free the resources it uses
*
* Since: 1.4
*/
ClutterPaintVolume * ClutterPaintVolume *
_clutter_paint_volume_new (ClutterActor *actor) _clutter_paint_volume_new (ClutterActor *actor)
{ {
@ -11527,6 +11538,16 @@ _clutter_paint_volume_new (ClutterActor *actor)
return pv; return pv;
} }
/**
* clutter_paint_volume_copy:
* @pv: a #ClutterPaintVolume
*
* Copies @pv into a new #ClutterPaintVolume
*
* Return value: a newly allocated copy of a #ClutterPaintVolume
*
* Since: 1.4
*/
ClutterPaintVolume * ClutterPaintVolume *
clutter_paint_volume_copy (const ClutterPaintVolume *pv) clutter_paint_volume_copy (const ClutterPaintVolume *pv)
{ {
@ -11541,6 +11562,14 @@ clutter_paint_volume_copy (const ClutterPaintVolume *pv)
return copy; return copy;
} }
/**
* clutter_paint_volume_free:
* @pv: a #ClutterPaintVolume
*
* Frees the resources allocated by @pv
*
* Since: 1.4
*/
void void
clutter_paint_volume_free (ClutterPaintVolume *pv) clutter_paint_volume_free (ClutterPaintVolume *pv)
{ {
@ -11553,6 +11582,20 @@ clutter_paint_volume_free (ClutterPaintVolume *pv)
} }
} }
/**
* clutter_paint_volume_set_origin:
* @pv: a #ClutterPaintVolume
* @origin: a #ClutterVertex
*
* Sets the origin of the paint volume.
*
* The origin is defined as the X and Y coordinates of the top-left corner
* of an actor's paint volume, with a Z coordinate of 0.
*
* The default is origin is assumed at: (0, 0, 0)
*
* Since: 1.4
*/
void void
clutter_paint_volume_set_origin (ClutterPaintVolume *pv, clutter_paint_volume_set_origin (ClutterPaintVolume *pv,
const ClutterVertex *origin) const ClutterVertex *origin)
@ -11562,6 +11605,15 @@ clutter_paint_volume_set_origin (ClutterPaintVolume *pv,
pv->vertices[0] = *origin; pv->vertices[0] = *origin;
} }
/**
* clutter_paint_volume_get_origin:
* @pv: a #ClutterPaintVolume
* @vertex: (out): the return location for a #ClutterVertex
*
* Retrieves the origin of the #ClutterPaintVolume.
*
* Since: 1.4
*/
void void
clutter_paint_volume_get_origin (const ClutterPaintVolume *pv, clutter_paint_volume_get_origin (const ClutterPaintVolume *pv,
ClutterVertex *vertex) ClutterVertex *vertex)
@ -11572,6 +11624,19 @@ clutter_paint_volume_get_origin (const ClutterPaintVolume *pv,
*vertex = pv->vertices[0]; *vertex = pv->vertices[0];
} }
/**
* clutter_paint_volume_set_width:
* @pv: a #ClutterPaintVolume
* @width: the width vector of the paint volume, in pixels
*
* Sets the magnitude of the width vector of the paint volume.
*
* The width vector is defined as the vector that has the initial
* point in the origin, the sense of the X axis and the magnitude
* as the horizontal span of an actor.
*
* Since: 1.4
*/
void void
clutter_paint_volume_set_width (ClutterPaintVolume *pv, clutter_paint_volume_set_width (ClutterPaintVolume *pv,
gfloat width) gfloat width)
@ -11582,6 +11647,16 @@ clutter_paint_volume_set_width (ClutterPaintVolume *pv,
pv->vertices[1].x = width; pv->vertices[1].x = width;
} }
/**
* clutter_paint_volume_get_width:
* @pv: a #ClutterPaintVolume
*
* Retrieves the width set using clutter_paint_volume_get_width()
*
* Return value: the width, in pixels
*
* Since: 1.4
*/
gfloat gfloat
clutter_paint_volume_get_width (const ClutterPaintVolume *pv) clutter_paint_volume_get_width (const ClutterPaintVolume *pv)
{ {
@ -11590,6 +11665,19 @@ clutter_paint_volume_get_width (const ClutterPaintVolume *pv)
return pv->vertices[1].x; return pv->vertices[1].x;
} }
/**
* clutter_paint_volume_set_height:
* @pv: a #ClutterPaintVolume
* @height: the magnitude of the height vector of the paint volume, in pixels
*
* Sets the magnitude of the height vector of the paint volume.
*
* The height vector is defined as the vector that has the initial
* point in the origin, the sense of the Y axis and the magnitude
* as the vertical span of an actor.
*
* Since: 1.4
*/
void void
clutter_paint_volume_set_height (ClutterPaintVolume *pv, clutter_paint_volume_set_height (ClutterPaintVolume *pv,
gfloat height) gfloat height)
@ -11600,6 +11688,16 @@ clutter_paint_volume_set_height (ClutterPaintVolume *pv,
pv->vertices[2].y = height; pv->vertices[2].y = height;
} }
/**
* clutter_paint_volume_get_height:
* @pv: a #ClutterPaintVolume
*
* Retrieves the height set using clutter_paint_volume_get_height()
*
* Return value: the height, in pixels
*
* Since: 1.4
*/
gfloat gfloat
clutter_paint_volume_get_height (const ClutterPaintVolume *pv) clutter_paint_volume_get_height (const ClutterPaintVolume *pv)
{ {
@ -11608,6 +11706,19 @@ clutter_paint_volume_get_height (const ClutterPaintVolume *pv)
return pv->vertices[2].y; return pv->vertices[2].y;
} }
/**
* clutter_paint_volume_set_depth:
* @pv: a #ClutterPaintVolume
* @depth: the magnitude of the depth vector of the paint volume
*
* Sets the magnitude of the depth vector of the paint volume.
*
* The height vector is defined as the vector that has the initial
* point in the origin, the sense of the Z axis and the magnitude
* as the depth span of an actor.
*
* Since: 1.4
*/
void void
clutter_paint_volume_set_depth (ClutterPaintVolume *pv, clutter_paint_volume_set_depth (ClutterPaintVolume *pv,
gfloat depth) gfloat depth)
@ -11617,6 +11728,16 @@ clutter_paint_volume_set_depth (ClutterPaintVolume *pv,
pv->vertices[3].z = depth; pv->vertices[3].z = depth;
} }
/**
* clutter_paint_volume_get_depth:
* @pv: a #ClutterPaintVolume
*
* Retrieves the depth set using clutter_paint_volume_get_depth()
*
* Return value: the depth
*
* Since: 1.4
*/
gfloat gfloat
clutter_paint_volume_get_depth (const ClutterPaintVolume *pv) clutter_paint_volume_get_depth (const ClutterPaintVolume *pv)
{ {
@ -11625,6 +11746,15 @@ clutter_paint_volume_get_depth (const ClutterPaintVolume *pv)
return pv->vertices[3].z; return pv->vertices[3].z;
} }
/*<private>
* _clutter_paint_volume_get_box:
* @pv: a #ClutterPaintVolume
* @box: a #ClutterActorBox
*
* Transforms a 3D paint volume into a 2D bounding box
*
* Since: 1.4
*/
void void
_clutter_paint_volume_get_box (ClutterPaintVolume *pv, _clutter_paint_volume_get_box (ClutterPaintVolume *pv,
ClutterActorBox *box) ClutterActorBox *box)
@ -11695,6 +11825,29 @@ _clutter_paint_volume_get_box (ClutterPaintVolume *pv,
clutter_actor_box_clamp_to_pixel (box); clutter_actor_box_clamp_to_pixel (box);
} }
/**
* clutter_actor_get_paint_volume:
* @self: a #ClutterActor
*
* Retrieves the paint volume of the passed #ClutterActor.
*
* The paint volume is defined as the 3D space occupied by an actor
* when being painted.
*
* This function will call the <function>get_paint_volume()</function>
* virtual function of the #ClutterActor class. Sub-classes of #ClutterActor
* should not usually care about overriding the default implementation,
* unless they are, for instance, painting outside their allocation area.
*
* <note>Overriding the <function>get_paint_box()</function> for 2D actors
* should set a degenerate depth vector using the same value as the Z
* coordinate of the origin.</note>
*
* Return value: (transfer full): a newly allocated #ClutterPaintVolume.
* Use clutter_paint_volume_free() to free the resources when done.
*
* Since: 1.4
*/
ClutterPaintVolume * ClutterPaintVolume *
clutter_actor_get_paint_volume (ClutterActor *self) clutter_actor_get_paint_volume (ClutterActor *self)
{ {
@ -11742,6 +11895,19 @@ clutter_actor_get_paint_volume (ClutterActor *self)
return pv; return pv;
} }
/**
* clutter_actor_get_paint_box:
* @self: a #ClutterActor
* @box: (out): return location for a #ClutterActorBox
*
* Retrieves the paint volume of the passed #ClutterActor, and transforms it
* into a 2D bounding box in stage coordinates.
*
* This function is useful to determine the on screen area occupied by the
* actor.
*
* Since: 1.4
*/
void void
clutter_actor_get_paint_box (ClutterActor *self, clutter_actor_get_paint_box (ClutterActor *self,
ClutterActorBox *box) ClutterActorBox *box)

16
doc/reference/clutter/clutter-sections.txt
View File

@ -384,6 +384,8 @@ clutter_actor_get_paint_opacity
clutter_actor_get_paint_visibility clutter_actor_get_paint_visibility
clutter_actor_get_abs_allocation_vertices clutter_actor_get_abs_allocation_vertices
clutter_actor_get_transformation_matrix clutter_actor_get_transformation_matrix
clutter_actor_get_paint_volume
clutter_actor_get_paint_box
<SUBSECTION> <SUBSECTION>
clutter_actor_set_anchor_point clutter_actor_set_anchor_point
@ -467,10 +469,24 @@ ClutterGeometry
clutter_geometry_union clutter_geometry_union
clutter_geometry_intersects clutter_geometry_intersects
<SUBSECTION>
ClutterPaintVolume
clutter_paint_volume_copy
clutter_paint_volume_free
clutter_paint_volume_set_origin
clutter_paint_volume_get_origin
clutter_paint_volume_set_width
clutter_paint_volume_get_width
clutter_paint_volume_set_height
clutter_paint_volume_get_height
clutter_paint_volume_set_depth
clutter_paint_volume_get_depth
<SUBSECTION Standard> <SUBSECTION Standard>
CLUTTER_TYPE_GEOMETRY CLUTTER_TYPE_GEOMETRY
CLUTTER_TYPE_ACTOR_BOX CLUTTER_TYPE_ACTOR_BOX
CLUTTER_TYPE_VERTEX CLUTTER_TYPE_VERTEX
CLUTTER_TYPE_PAINT_VOLUME
CLUTTER_ACTOR CLUTTER_ACTOR
CLUTTER_IS_ACTOR CLUTTER_IS_ACTOR
CLUTTER_TYPE_ACTOR CLUTTER_TYPE_ACTOR