Base geometric types

Base geometric types — Common geometric data types used by Clutter

Functions

#define CLUTTER_POINT_INIT()
const ClutterPoint * clutter_point_zero ()
ClutterPoint * clutter_point_alloc ()
ClutterPoint * clutter_point_init ()
ClutterPoint * clutter_point_copy ()
void clutter_point_free ()
gboolean clutter_point_equals ()
float clutter_point_distance ()
#define CLUTTER_SIZE_INIT()
ClutterSize * clutter_size_alloc ()
ClutterSize * clutter_size_init ()
ClutterSize * clutter_size_copy ()
void clutter_size_free ()
gboolean clutter_size_equals ()
#define CLUTTER_RECT_INIT()
const ClutterRect * clutter_rect_zero ()
ClutterRect * clutter_rect_alloc ()
ClutterRect * clutter_rect_init ()
ClutterRect * clutter_rect_copy ()
void clutter_rect_free ()
gboolean clutter_rect_equals ()
ClutterRect * clutter_rect_normalize ()
void clutter_rect_get_center ()
gboolean clutter_rect_contains_point ()
gboolean clutter_rect_contains_rect ()
void clutter_rect_union ()
gboolean clutter_rect_intersection ()
void clutter_rect_offset ()
void clutter_rect_inset ()
void clutter_rect_clamp_to_pixel ()
float clutter_rect_get_x ()
float clutter_rect_get_y ()
float clutter_rect_get_width ()
float clutter_rect_get_height ()
#define CLUTTER_VERTEX_INIT()
ClutterVertex * clutter_vertex_new ()
ClutterVertex * clutter_vertex_alloc ()
ClutterVertex * clutter_vertex_init ()
ClutterVertex * clutter_vertex_copy ()
void clutter_vertex_free ()
gboolean clutter_vertex_equal ()
#define CLUTTER_ACTOR_BOX_INIT()
ClutterActorBox * clutter_actor_box_new ()
ClutterActorBox * clutter_actor_box_alloc ()
ClutterActorBox * clutter_actor_box_init ()
void clutter_actor_box_init_rect ()
ClutterActorBox * clutter_actor_box_copy ()
void clutter_actor_box_free ()
gboolean clutter_actor_box_equal ()
gfloat clutter_actor_box_get_x ()
gfloat clutter_actor_box_get_y ()
gfloat clutter_actor_box_get_width ()
gfloat clutter_actor_box_get_height ()
void clutter_actor_box_set_origin ()
void clutter_actor_box_get_origin ()
void clutter_actor_box_set_size ()
void clutter_actor_box_get_size ()
gfloat clutter_actor_box_get_area ()
gboolean clutter_actor_box_contains ()
void clutter_actor_box_from_vertices ()
void clutter_actor_box_clamp_to_pixel ()
void clutter_actor_box_interpolate ()
void clutter_actor_box_union ()
ClutterPaintVolume * clutter_paint_volume_copy ()
void clutter_paint_volume_free ()
void clutter_paint_volume_set_origin ()
void clutter_paint_volume_get_origin ()
void clutter_paint_volume_set_width ()
gfloat clutter_paint_volume_get_width ()
void clutter_paint_volume_set_height ()
gfloat clutter_paint_volume_get_height ()
void clutter_paint_volume_set_depth ()
gfloat clutter_paint_volume_get_depth ()
gboolean clutter_paint_volume_set_from_allocation ()
void clutter_paint_volume_union ()
void clutter_paint_volume_union_box ()
ClutterMatrix * clutter_matrix_alloc ()
void clutter_matrix_free ()
ClutterMatrix * clutter_matrix_init_from_array ()
ClutterMatrix * clutter_matrix_init_from_matrix ()
ClutterMatrix * clutter_matrix_init_identity ()
ClutterKnot * clutter_knot_copy ()
void clutter_knot_free ()
gboolean clutter_knot_equal ()
void clutter_geometry_union ()
gboolean clutter_geometry_intersects ()

Object Hierarchy

    GBoxed
    ├── ClutterActorBox
    ├── ClutterGeometry
    ├── ClutterKnot
    ├── ClutterMatrix
    ├── ClutterPaintVolume
    ├── ClutterPoint
    ├── ClutterRect
    ├── ClutterSize
    ╰── ClutterVertex

Description

Clutter defines a set of geometric data structures that are commonly used across the whole API.

Functions

CLUTTER_POINT_INIT()

#define CLUTTER_POINT_INIT(x,y)         { (x), (y) }

A simple macro for initializing a ClutterPoint when declaring it, e.g.:

1
ClutterPoint p = CLUTTER_POINT_INIT (100, 100);

Parameters

x

X coordinate

 

y

Y coordinate

 

Since: 1.12


clutter_point_zero ()

const ClutterPoint *
clutter_point_zero (void);

A point centered at (0, 0).

The returned value can be used as a guard.

Returns

a point centered in (0, 0); the returned ClutterPoint is owned by Clutter and it should not be modified or freed.

Since: 1.12


clutter_point_alloc ()

ClutterPoint *
clutter_point_alloc (void);

Allocates a new ClutterPoint.

[constructor]

Returns

the newly allocated ClutterPoint. Use clutter_point_free() to free its resources.

[transfer full]

Since: 1.12


clutter_point_init ()

ClutterPoint *
clutter_point_init (ClutterPoint *point,
                    float x,
                    float y);

Initializes point with the given coordinates.

Parameters

point

a ClutterPoint

 

x

the X coordinate of the point

 

y

the Y coordinate of the point

 

Returns

the initialized ClutterPoint.

[transfer none]

Since: 1.12


clutter_point_copy ()

ClutterPoint *
clutter_point_copy (const ClutterPoint *point);

Creates a new ClutterPoint with the same coordinates of point .

Parameters

point

a ClutterPoint

 

Returns

a newly allocated ClutterPoint. Use clutter_point_free() to free its resources.

[transfer full]

Since: 1.12


clutter_point_free ()

void
clutter_point_free (ClutterPoint *point);

Frees the resources allocated for point .

Parameters

point

a ClutterPoint

 

Since: 1.12


clutter_point_equals ()

gboolean
clutter_point_equals (const ClutterPoint *a,
                      const ClutterPoint *b);

Compares two ClutterPoint for equality.

Parameters

a

the first ClutterPoint to compare

 

b

the second ClutterPoint to compare

 

Returns

TRUE if the ClutterPoints are equal

Since: 1.12


clutter_point_distance ()

float
clutter_point_distance (const ClutterPoint *a,
                        const ClutterPoint *b,
                        float *x_distance,
                        float *y_distance);

Computes the distance between two ClutterPoint.

Parameters

a

a ClutterPoint

 

b

a ClutterPoint

 

x_distance

return location for the horizontal distance between the points.

[out][allow-none]

y_distance

return location for the vertical distance between the points.

[out][allow-none]

Returns

the distance between the points.

Since: 1.12


CLUTTER_SIZE_INIT()

#define CLUTTER_SIZE_INIT(width,height) { (width), (height) }

A simple macro for initializing a ClutterSize when declaring it, e.g.:

1
ClutterSize s = CLUTTER_SIZE_INIT (200, 200);

Parameters

width

the width

 

height

the height

 

Since: 1.12


clutter_size_alloc ()

ClutterSize *
clutter_size_alloc (void);

Allocates a new ClutterSize.

[constructor]

Returns

the newly allocated ClutterSize. Use clutter_size_free() to free its resources.

[transfer full]

Since: 1.12


clutter_size_init ()

ClutterSize *
clutter_size_init (ClutterSize *size,
                   float width,
                   float height);

Initializes a ClutterSize with the given dimensions.

Parameters

size

a ClutterSize

 

width

the width

 

height

the height

 

Returns

the initialized ClutterSize.

[transfer none]

Since: 1.12


clutter_size_copy ()

ClutterSize *
clutter_size_copy (const ClutterSize *size);

Creates a new ClutterSize and duplicates size .

Parameters

size

a ClutterSize

 

Returns

the newly allocated ClutterSize. Use clutter_size_free() to free its resources.

[transfer full]

Since: 1.12


clutter_size_free ()

void
clutter_size_free (ClutterSize *size);

Frees the resources allocated for size .

Parameters

size

a ClutterSize

 

Since: 1.12


clutter_size_equals ()

gboolean
clutter_size_equals (const ClutterSize *a,
                     const ClutterSize *b);

Compares two ClutterSize for equality.

Parameters

a

a ClutterSize to compare

 

b

a ClutterSize to compare

 

Returns

TRUE if the two ClutterSize are equal

Since: 1.12


CLUTTER_RECT_INIT()

#define CLUTTER_RECT_INIT(x,y,width,height)     { { (x), (y) }, { (width), (height) } }

A simple macro for initializing a ClutterRect when declaring it, e.g.:

1
ClutterRect r = CLUTTER_RECT_INIT (100, 100, 200, 200);

Parameters

x

the X coordinate

 

y

the Y coordinate

 

width

the width

 

height

the height

 

Since: 1.12


clutter_rect_zero ()

const ClutterRect *
clutter_rect_zero (void);

A ClutterRect with ClutterRect.origin set at (0, 0) and a size of 0.

The returned value can be used as a guard.

Returns

a rectangle with origin in (0, 0) and a size of 0. The returned ClutterRect is owned by Clutter and it should not be modified or freed.

Since: 1.12


clutter_rect_alloc ()

ClutterRect *
clutter_rect_alloc (void);

Creates a new, empty ClutterRect.

You can use clutter_rect_init() to initialize the returned rectangle, for instance:

1
rect = clutter_rect_init (clutter_rect_alloc (), x, y, width, height);

[constructor]

Returns

the newly allocated ClutterRect. Use clutter_rect_free() to free its resources.

[transfer full]

Since: 1.12


clutter_rect_init ()

ClutterRect *
clutter_rect_init (ClutterRect *rect,
                   float x,
                   float y,
                   float width,
                   float height);

Initializes a ClutterRect with the given origin and size.

Parameters

rect

a ClutterRect

 

x

X coordinate of the origin

 

y

Y coordinate of the origin

 

width

width of the rectangle

 

height

height of the rectangle

 

Returns

the updated rectangle.

[transfer none]

Since: 1.12


clutter_rect_copy ()

ClutterRect *
clutter_rect_copy (const ClutterRect *rect);

Copies rect into a new ClutterRect instance.

Parameters

rect

a ClutterRect

 

Returns

the newly allocate copy of rect . Use clutter_rect_free() to free the associated resources.

[transfer full]

Since: 1.12


clutter_rect_free ()

void
clutter_rect_free (ClutterRect *rect);

Frees the resources allocated by rect .

Parameters

rect

a ClutterRect

 

Since: 1.12


clutter_rect_equals ()

gboolean
clutter_rect_equals (ClutterRect *a,
                     ClutterRect *b);

Checks whether a and b are equals.

This function will normalize both a and b before comparing their origin and size.

Parameters

a

a ClutterRect

 

b

a ClutterRect

 

Returns

TRUE if the rectangles match in origin and size.

Since: 1.12


clutter_rect_normalize ()

ClutterRect *
clutter_rect_normalize (ClutterRect *rect);

Normalizes a ClutterRect.

A ClutterRect is defined by the area covered by its size; this means that a ClutterRect with ClutterRect.origin in [ 0, 0 ] and a ClutterRect.size of [ 10, 10 ] is equivalent to a ClutterRect with ClutterRect.origin in [ 10, 10 ] and a ClutterRect.size of [ -10, -10 ].

This function is useful to ensure that a rectangle has positive width and height; it will modify the passed rect and normalize its size.

Parameters

rect

a ClutterRect

 

Since: 1.12


clutter_rect_get_center ()

void
clutter_rect_get_center (ClutterRect *rect,
                         ClutterPoint *center);

Retrieves the center of rect , after normalizing the rectangle, and updates center with the correct coordinates.

Parameters

rect

a ClutterRect

 

center

a ClutterPoint.

[out caller-allocates]

Since: 1.12


clutter_rect_contains_point ()

gboolean
clutter_rect_contains_point (ClutterRect *rect,
                             ClutterPoint *point);

Checks whether point is contained by rect , after normalizing the rectangle.

Parameters

rect

a ClutterRect

 

point

the point to check

 

Returns

TRUE if the point is contained by rect .

Since: 1.12


clutter_rect_contains_rect ()

gboolean
clutter_rect_contains_rect (ClutterRect *a,
                            ClutterRect *b);

Checks whether a contains b .

The first rectangle contains the second if the union of the two ClutterRect is equal to the first rectangle.

Parameters

a

a ClutterRect

 

b

a ClutterRect

 

Returns

TRUE if the first rectangle contains the second.

Since: 1.12


clutter_rect_union ()

void
clutter_rect_union (ClutterRect *a,
                    ClutterRect *b,
                    ClutterRect *res);

Computes the smallest possible rectangle capable of fully containing both a and b , and places it into res .

This function will normalize both a and b prior to computing their union.

Parameters

a

a ClutterRect

 

b

a ClutterRect

 

res

a ClutterRect.

[out caller-allocates]

Since: 1.12


clutter_rect_intersection ()

gboolean
clutter_rect_intersection (ClutterRect *a,
                           ClutterRect *b,
                           ClutterRect *res);

Computes the intersection of a and b , and places it in res , if res is not NULL.

This function will normalize both a and b prior to computing their intersection.

This function can be used to simply check if the intersection of a and b is not empty, by using NULL for res .

Parameters

a

a ClutterRect

 

b

a ClutterRect

 

res

a ClutterRect, or NULL.

[out caller-allocates][allow-none]

Returns

TRUE if the intersection of a and b is not empty

Since: 1.12


clutter_rect_offset ()

void
clutter_rect_offset (ClutterRect *rect,
                     float d_x,
                     float d_y);

Offsets the origin of rect by the given values, after normalizing the rectangle.

Parameters

rect

a ClutterRect

 

d_x

the horizontal offset value

 

d_y

the vertical offset value

 

Since: 1.12


clutter_rect_inset ()

void
clutter_rect_inset (ClutterRect *rect,
                    float d_x,
                    float d_y);

Normalizes the rect and offsets its origin by the d_x and d_y values; the size is adjusted by (2 * d_x , 2 * d_y ).

If d_x and d_y are positive the size of the rectangle is decreased; if the values are negative, the size of the rectangle is increased.

If the resulting rectangle has a negative width or height, the size is set to 0.

Parameters

rect

a ClutterRect

 

d_x

an horizontal value; a positive d_x will create an inset rectangle, and a negative value will create a larger rectangle

 

d_y

a vertical value; a positive d_x will create an inset rectangle, and a negative value will create a larger rectangle

 

Since: 1.12


clutter_rect_clamp_to_pixel ()

void
clutter_rect_clamp_to_pixel (ClutterRect *rect);

Rounds the origin of rect downwards to the nearest integer, and rounds the size of rect upwards to the nearest integer, so that rect is updated to the smallest rectangle capable of fully containing the original, fractional rectangle.

Parameters

rect

a ClutterRect

 

Since: 1.12


clutter_rect_get_x ()

float
clutter_rect_get_x (ClutterRect *rect);

Retrieves the X coordinate of the origin of rect .

Parameters

rect

a ClutterRect

 

Returns

the X coordinate of the origin of the rectangle

Since: 1.12


clutter_rect_get_y ()

float
clutter_rect_get_y (ClutterRect *rect);

Retrieves the Y coordinate of the origin of rect .

Parameters

rect

a ClutterRect

 

Returns

the Y coordinate of the origin of the rectangle

Since: 1.12


clutter_rect_get_width ()

float
clutter_rect_get_width (ClutterRect *rect);

Retrieves the width of rect .

Parameters

rect

a ClutterRect

 

Returns

the width of the rectangle

Since: 1.12


clutter_rect_get_height ()

float
clutter_rect_get_height (ClutterRect *rect);

Retrieves the height of rect .

Parameters

rect

a ClutterRect

 

Returns

the height of the rectangle

Since: 1.12


CLUTTER_VERTEX_INIT()

#define CLUTTER_VERTEX_INIT(x,y,z)      { (x), (y), (z) }

A simple macro for initializing a ClutterVertex when declaring it, e.g.:

1
ClutterVertex v = CLUTTER_VERTEX_INIT (x, y, z);

Parameters

x

the X coordinate of the vertex

 

y

the Y coordinate of the vertex

 

z

the Z coordinate of the vertex

 

Since: 1.10


clutter_vertex_new ()

ClutterVertex *
clutter_vertex_new (gfloat x,
                    gfloat y,
                    gfloat z);

Creates a new ClutterVertex for the point in 3D space identified by the 3 coordinates x , y , z .

This function is the logical equivalent of:

Parameters

x

X coordinate

 

y

Y coordinate

 

z

Z coordinate

 

Returns

the newly allocated ClutterVertex. Use clutter_vertex_free() to free the resources.

[transfer full]

Since: 1.0


clutter_vertex_alloc ()

ClutterVertex *
clutter_vertex_alloc (void);

Allocates a new, empty ClutterVertex.

[constructor]

Returns

the newly allocated ClutterVertex. Use clutter_vertex_free() to free its resources.

[transfer full]

Since: 1.12


clutter_vertex_init ()

ClutterVertex *
clutter_vertex_init (ClutterVertex *vertex,
                     gfloat x,
                     gfloat y,
                     gfloat z);

Initializes vertex with the given coordinates.

Parameters

vertex

a ClutterVertex

 

x

X coordinate

 

y

Y coordinate

 

z

Z coordinate

 

Returns

the initialized ClutterVertex.

[transfer none]

Since: 1.10


clutter_vertex_copy ()

ClutterVertex *
clutter_vertex_copy (const ClutterVertex *vertex);

Copies vertex

Parameters

vertex

a ClutterVertex

 

Returns

a newly allocated copy of ClutterVertex. Use clutter_vertex_free() to free the allocated resources.

[transfer full]

Since: 1.0


clutter_vertex_free ()

void
clutter_vertex_free (ClutterVertex *vertex);

Frees a ClutterVertex allocated using clutter_vertex_alloc() or clutter_vertex_copy().

Parameters

vertex

a ClutterVertex

 

Since: 1.0


clutter_vertex_equal ()

gboolean
clutter_vertex_equal (const ClutterVertex *vertex_a,
                      const ClutterVertex *vertex_b);

Compares vertex_a and vertex_b for equality

Parameters

vertex_a

a ClutterVertex

 

vertex_b

a ClutterVertex

 

Returns

TRUE if the passed ClutterVertex are equal

Since: 1.0


CLUTTER_ACTOR_BOX_INIT()

#define CLUTTER_ACTOR_BOX_INIT(x_1,y_1,x_2,y_2)         { (x_1), (y_1), (x_2), (y_2) }

A simple macro for initializing a ClutterActorBox when declaring it, e.g.:

1
ClutterActorBox box = CLUTTER_ACTOR_BOX_INIT (0, 0, 400, 600);

Parameters

x_1

the X coordinate of the top left corner

 

y_1

the Y coordinate of the top left corner

 

x_2

the X coordinate of the bottom right corner

 

y_2

the Y coordinate of the bottom right corner

 

Since: 1.10


clutter_actor_box_new ()

ClutterActorBox *
clutter_actor_box_new (gfloat x_1,
                       gfloat y_1,
                       gfloat x_2,
                       gfloat y_2);

Allocates a new ClutterActorBox using the passed coordinates for the top left and bottom right points.

This function is the logical equivalent of:

1
2
3
clutter_actor_box_init (clutter_actor_box_alloc (),
                        x_1, y_1,
                        x_2, y_2);

Parameters

x_1

X coordinate of the top left point

 

y_1

Y coordinate of the top left point

 

x_2

X coordinate of the bottom right point

 

y_2

Y coordinate of the bottom right point

 

Returns

the newly allocated ClutterActorBox. Use clutter_actor_box_free() to free the resources.

[transfer full]

Since: 1.0


clutter_actor_box_alloc ()

ClutterActorBox *
clutter_actor_box_alloc (void);

Allocates a new ClutterActorBox.

Returns

the newly allocated ClutterActorBox. Use clutter_actor_box_free() to free its resources.

[transfer full]

Since: 1.12


clutter_actor_box_init ()

ClutterActorBox *
clutter_actor_box_init (ClutterActorBox *box,
                        gfloat x_1,
                        gfloat y_1,
                        gfloat x_2,
                        gfloat y_2);

Initializes box with the given coordinates.

Parameters

box

a ClutterActorBox

 

x_1

X coordinate of the top left point

 

y_1

Y coordinate of the top left point

 

x_2

X coordinate of the bottom right point

 

y_2

Y coordinate of the bottom right point

 

Returns

the initialized ClutterActorBox.

[transfer none]

Since: 1.10


clutter_actor_box_init_rect ()

void
clutter_actor_box_init_rect (ClutterActorBox *box,
                             gfloat x,
                             gfloat y,
                             gfloat width,
                             gfloat height);

Initializes box with the given origin and size.

Parameters

box

a ClutterActorBox

 

x

X coordinate of the origin

 

y

Y coordinate of the origin

 

width

width of the box

 

height

height of the box

 

Since: 1.10


clutter_actor_box_copy ()

ClutterActorBox *
clutter_actor_box_copy (const ClutterActorBox *box);

Copies box

Parameters

box

a ClutterActorBox

 

Returns

a newly allocated copy of ClutterActorBox. Use clutter_actor_box_free() to free the allocated resources

Since: 1.0


clutter_actor_box_free ()

void
clutter_actor_box_free (ClutterActorBox *box);

Frees a ClutterActorBox allocated using clutter_actor_box_new() or clutter_actor_box_copy()

Parameters

box

a ClutterActorBox

 

Since: 1.0


clutter_actor_box_equal ()

gboolean
clutter_actor_box_equal (const ClutterActorBox *box_a,
                         const ClutterActorBox *box_b);

Checks box_a and box_b for equality

Parameters

box_a

a ClutterActorBox

 

box_b

a ClutterActorBox

 

Returns

TRUE if the passed ClutterActorBox are equal

Since: 1.0


clutter_actor_box_get_x ()

gfloat
clutter_actor_box_get_x (const ClutterActorBox *box);

Retrieves the X coordinate of the origin of box

Parameters

box

a ClutterActorBox

 

Returns

the X coordinate of the origin

Since: 1.0


clutter_actor_box_get_y ()

gfloat
clutter_actor_box_get_y (const ClutterActorBox *box);

Retrieves the Y coordinate of the origin of box

Parameters

box

a ClutterActorBox

 

Returns

the Y coordinate of the origin

Since: 1.0


clutter_actor_box_get_width ()

gfloat
clutter_actor_box_get_width (const ClutterActorBox *box);

Retrieves the width of the box

Parameters

box

a ClutterActorBox

 

Returns

the width of the box

Since: 1.0


clutter_actor_box_get_height ()

gfloat
clutter_actor_box_get_height (const ClutterActorBox *box);

Retrieves the height of the box

Parameters

box

a ClutterActorBox

 

Returns

the height of the box

Since: 1.0


clutter_actor_box_set_origin ()

void
clutter_actor_box_set_origin (ClutterActorBox *box,
                              gfloat x,
                              gfloat y);

Changes the origin of box , maintaining the size of the ClutterActorBox.

Parameters

box

a ClutterActorBox

 

x

the X coordinate of the new origin

 

y

the Y coordinate of the new origin

 

Since: 1.6


clutter_actor_box_get_origin ()

void
clutter_actor_box_get_origin (const ClutterActorBox *box,
                              gfloat *x,
                              gfloat *y);

Retrieves the origin of box

Parameters

box

a ClutterActorBox

 

x

return location for the X coordinate, or NULL.

[out][allow-none]

y

return location for the Y coordinate, or NULL.

[out][allow-none]

Since: 1.0


clutter_actor_box_set_size ()

void
clutter_actor_box_set_size (ClutterActorBox *box,
                            gfloat width,
                            gfloat height);

Sets the size of box , maintaining the origin of the ClutterActorBox.

Parameters

box

a ClutterActorBox

 

width

the new width

 

height

the new height

 

Since: 1.6


clutter_actor_box_get_size ()

void
clutter_actor_box_get_size (const ClutterActorBox *box,
                            gfloat *width,
                            gfloat *height);

Retrieves the size of box

Parameters

box

a ClutterActorBox

 

width

return location for the width, or NULL.

[out][allow-none]

height

return location for the height, or NULL.

[out][allow-none]

Since: 1.0


clutter_actor_box_get_area ()

gfloat
clutter_actor_box_get_area (const ClutterActorBox *box);

Retrieves the area of box

Parameters

box

a ClutterActorBox

 

Returns

the area of a ClutterActorBox, in pixels

Since: 1.0


clutter_actor_box_contains ()

gboolean
clutter_actor_box_contains (const ClutterActorBox *box,
                            gfloat x,
                            gfloat y);

Checks whether a point with x , y coordinates is contained withing box

Parameters

box

a ClutterActorBox

 

x

X coordinate of the point

 

y

Y coordinate of the point

 

Returns

TRUE if the point is contained by the ClutterActorBox

Since: 1.0


clutter_actor_box_from_vertices ()

void
clutter_actor_box_from_vertices (ClutterActorBox *box,
                                 const ClutterVertex verts[]);

Calculates the bounding box represented by the four vertices; for details of the vertex array see clutter_actor_get_abs_allocation_vertices().

Parameters

box

a ClutterActorBox

 

verts

array of four ClutterVertex.

[array fixed-size=4]

Since: 1.0


clutter_actor_box_clamp_to_pixel ()

void
clutter_actor_box_clamp_to_pixel (ClutterActorBox *box);

Clamps the components of box to the nearest integer

Parameters

box

the ClutterActorBox to clamp.

[inout]

Since: 1.2


clutter_actor_box_interpolate ()

void
clutter_actor_box_interpolate (const ClutterActorBox *initial,
                               const ClutterActorBox *final,
                               gdouble progress,
                               ClutterActorBox *result);

Interpolates between initial and final ClutterActorBoxes using progress

Parameters

initial

the initial ClutterActorBox

 

final

the final ClutterActorBox

 

progress

the interpolation progress

 

result

return location for the interpolation.

[out]

Since: 1.2


clutter_actor_box_union ()

void
clutter_actor_box_union (const ClutterActorBox *a,
                         const ClutterActorBox *b,
                         ClutterActorBox *result);

Unions the two boxes a and b and stores the result in result .

Parameters

a

the first ClutterActorBox.

[in]

b

the second ClutterActorBox.

[in]

result

the ClutterActorBox representing a union of a and b .

[out]

Since: 1.4


clutter_paint_volume_copy ()

ClutterPaintVolume *
clutter_paint_volume_copy (const ClutterPaintVolume *pv);

Copies pv into a new ClutterPaintVolume

Parameters

Returns

a newly allocated copy of a ClutterPaintVolume

Since: 1.6


clutter_paint_volume_free ()

void
clutter_paint_volume_free (ClutterPaintVolume *pv);

Frees the resources allocated by pv

Parameters

Since: 1.6


clutter_paint_volume_set_origin ()

void
clutter_paint_volume_set_origin (ClutterPaintVolume *pv,
                                 const ClutterVertex *origin);

Sets the origin of the paint volume.

The origin is defined as the X, Y and Z coordinates of the top-left corner of an actor's paint volume, in actor coordinates.

The default is origin is assumed at: (0, 0, 0)

Parameters

pv

a ClutterPaintVolume

 

origin

a ClutterVertex

 

Since: 1.6


clutter_paint_volume_get_origin ()

void
clutter_paint_volume_get_origin (const ClutterPaintVolume *pv,
                                 ClutterVertex *vertex);

Retrieves the origin of the ClutterPaintVolume.

Parameters

pv

a ClutterPaintVolume

 

vertex

the return location for a ClutterVertex.

[out]

Since: 1.6


clutter_paint_volume_set_width ()

void
clutter_paint_volume_set_width (ClutterPaintVolume *pv,
                                gfloat width);

Sets the width of the paint volume. The width is measured along the x axis in the actor coordinates that pv is associated with.

Parameters

pv

a ClutterPaintVolume

 

width

the width of the paint volume, in pixels

 

Since: 1.6


clutter_paint_volume_get_width ()

gfloat
clutter_paint_volume_get_width (const ClutterPaintVolume *pv);

Retrieves the width of the volume's, axis aligned, bounding box.

In other words; this takes into account what actor's coordinate space pv belongs too and conceptually fits an axis aligned box around the volume. It returns the size of that bounding box as measured along the x-axis.

If, for example, clutter_actor_get_transformed_paint_volume() is used to transform a 2D child actor that is 100px wide, 100px high and 0px deep into container coordinates then the width might not simply be 100px if the child actor has a 3D rotation applied to it.

Remember: if clutter_actor_get_transformed_paint_volume() is used then a transformed child volume will be defined relative to the ancestor container actor and so a 2D child actor can have a 3D bounding volume.

There are no accuracy guarantees for the reported width, except that it must always be greater than, or equal to, the actor's width. This is because actors may report simple, loose fitting paint volumes for efficiency.

Parameters

Returns

the width, in units of pv 's local coordinate system.

Since: 1.6


clutter_paint_volume_set_height ()

void
clutter_paint_volume_set_height (ClutterPaintVolume *pv,
                                 gfloat height);

Sets the height of the paint volume. The height is measured along the y axis in the actor coordinates that pv is associated with.

Parameters

pv

a ClutterPaintVolume

 

height

the height of the paint volume, in pixels

 

Since: 1.6


clutter_paint_volume_get_height ()

gfloat
clutter_paint_volume_get_height (const ClutterPaintVolume *pv);

Retrieves the height of the volume's, axis aligned, bounding box.

In other words; this takes into account what actor's coordinate space pv belongs too and conceptually fits an axis aligned box around the volume. It returns the size of that bounding box as measured along the y-axis.

If, for example, clutter_actor_get_transformed_paint_volume() is used to transform a 2D child actor that is 100px wide, 100px high and 0px deep into container coordinates then the height might not simply be 100px if the child actor has a 3D rotation applied to it.

Remember: if clutter_actor_get_transformed_paint_volume() is used then a transformed child volume will be defined relative to the ancestor container actor and so a 2D child actor can have a 3D bounding volume.

There are no accuracy guarantees for the reported height, except that it must always be greater than, or equal to, the actor's height. This is because actors may report simple, loose fitting paint volumes for efficiency.

Parameters

Returns

the height, in units of pv 's local coordinate system.

Since: 1.6


clutter_paint_volume_set_depth ()

void
clutter_paint_volume_set_depth (ClutterPaintVolume *pv,
                                gfloat depth);

Sets the depth of the paint volume. The depth is measured along the z axis in the actor coordinates that pv is associated with.

Parameters

pv

a ClutterPaintVolume

 

depth

the depth of the paint volume, in pixels

 

Since: 1.6


clutter_paint_volume_get_depth ()

gfloat
clutter_paint_volume_get_depth (const ClutterPaintVolume *pv);

Retrieves the depth of the volume's, axis aligned, bounding box.

In other words; this takes into account what actor's coordinate space pv belongs too and conceptually fits an axis aligned box around the volume. It returns the size of that bounding box as measured along the z-axis.

If, for example, clutter_actor_get_transformed_paint_volume() is used to transform a 2D child actor that is 100px wide, 100px high and 0px deep into container coordinates then the depth might not simply be 0px if the child actor has a 3D rotation applied to it.

Remember: if clutter_actor_get_transformed_paint_volume() is used then the transformed volume will be defined relative to the container actor and in container coordinates a 2D child actor can have a 3D bounding volume.

There are no accuracy guarantees for the reported depth, except that it must always be greater than, or equal to, the actor's depth. This is because actors may report simple, loose fitting paint volumes for efficiency.

Parameters

Returns

the depth, in units of pv 's local coordinate system.

Since: 1.6


clutter_paint_volume_set_from_allocation ()

gboolean
clutter_paint_volume_set_from_allocation
                               (ClutterPaintVolume *pv,
                                ClutterActor *actor);

Sets the ClutterPaintVolume from the allocation of actor .

This function should be used when overriding the ClutterActorClass.get_paint_volume() by ClutterActor sub-classes that do not paint outside their allocation.

A typical example is:

1
2
3
4
5
6
static gboolean
my_actor_get_paint_volume (ClutterActor       *self,
                           ClutterPaintVolume *volume)
{
  return clutter_paint_volume_set_from_allocation (volume, self);
}

Parameters

pv

a ClutterPaintVolume

 

actor

a ClutterActor

 

Returns

TRUE if the paint volume was successfully set, and FALSE otherwise

Since: 1.6


clutter_paint_volume_union ()

void
clutter_paint_volume_union (ClutterPaintVolume *pv,
                            const ClutterPaintVolume *another_pv);

Updates the geometry of pv to encompass pv and another_pv .

There are no guarantees about how precisely the two volumes will be unioned.

Parameters

pv

The first ClutterPaintVolume and destination for resulting union

 

another_pv

A second ClutterPaintVolume to union with pv

 

Since: 1.6


clutter_paint_volume_union_box ()

void
clutter_paint_volume_union_box (ClutterPaintVolume *pv,
                                const ClutterActorBox *box);

Unions the 2D region represented by box to a ClutterPaintVolume.

This function is similar to clutter_paint_volume_union(), but it is specific for 2D regions.

Parameters

pv

a ClutterPaintVolume

 

box

a ClutterActorBox to union to pv

 

Since: 1.10


clutter_matrix_alloc ()

ClutterMatrix *
clutter_matrix_alloc (void);

Allocates enough memory to hold a ClutterMatrix.

Returns

the newly allocated ClutterMatrix.

[transfer full]

Since: 1.12


clutter_matrix_free ()

void
clutter_matrix_free (ClutterMatrix *matrix);

Frees the memory allocated by clutter_matrix_alloc().

Parameters

matrix

a ClutterMatrix.

[allow-none]

Since: 1.12


clutter_matrix_init_from_array ()

ClutterMatrix *
clutter_matrix_init_from_array (ClutterMatrix *matrix,
                                const float values[16]);

Initializes matrix with the contents of a C array of floating point values.

Parameters

matrix

a ClutterMatrix

 

values

a C array of 16 floating point values, representing a 4x4 matrix, with column-major order.

[array fixed-size=16]

Returns

the initialzed ClutterMatrix.

[transfer none]

Since: 1.12


clutter_matrix_init_from_matrix ()

ClutterMatrix *
clutter_matrix_init_from_matrix (ClutterMatrix *a,
                                 const ClutterMatrix *b);

Initializes the ClutterMatrix a with the contents of the ClutterMatrix b .

Parameters

a

the ClutterMatrix to initialize

 

b

the ClutterMatrix to copy

 

Returns

the initialized ClutterMatrix.

[transfer none]

Since: 1.12


clutter_matrix_init_identity ()

ClutterMatrix *
clutter_matrix_init_identity (ClutterMatrix *matrix);

Initializes matrix with the identity matrix, i.e.:

1
2
3
4
.xx = 1.0, .xy = 0.0, .xz = 0.0, .xw = 0.0
.yx = 0.0, .yy = 1.0, .yz = 0.0, .yw = 0.0
.zx = 0.0, .zy = 0.0, .zz = 1.0, .zw = 0.0
.wx = 0.0, .wy = 0.0, .wz = 0.0, .ww = 1.0

Parameters

matrix

a ClutterMatrix

 

Returns

the initialized ClutterMatrix.

[transfer none]

Since: 1.12


clutter_knot_copy ()

ClutterKnot *
clutter_knot_copy (const ClutterKnot *knot);

Makes an allocated copy of a knot.

Parameters

knot

a ClutterKnot

 

Returns

the copied knot.

Since: 0.2


clutter_knot_free ()

void
clutter_knot_free (ClutterKnot *knot);

Frees the memory of an allocated knot.

Parameters

knot

a ClutterKnot

 

Since: 0.2


clutter_knot_equal ()

gboolean
clutter_knot_equal (const ClutterKnot *knot_a,
                    const ClutterKnot *knot_b);

Compares to knot and checks if the point to the same location.

Parameters

knot_a

First knot

 

knot_b

Second knot

 

Returns

TRUE if the knots point to the same location.

Since: 0.2


clutter_geometry_union ()

void
clutter_geometry_union (const ClutterGeometry *geometry_a,
                        const ClutterGeometry *geometry_b,
                        ClutterGeometry *result);

clutter_geometry_union has been deprecated since version 1.16 and should not be used in newly-written code.

Use ClutterRect and clutter_rect_union()

Find the union of two rectangles represented as ClutterGeometry.

Parameters

geometry_a

a ClutterGeometry

 

geometry_b

another ClutterGeometry

 

result

location to store the result.

[out]

Since: 1.4


clutter_geometry_intersects ()

gboolean
clutter_geometry_intersects (const ClutterGeometry *geometry0,
                             const ClutterGeometry *geometry1);

clutter_geometry_intersects has been deprecated since version 1.16 and should not be used in newly-written code.

Use ClutterRect and clutter_rect_intersection()

Determines if geometry0 and geometry1 intersect returning TRUE if they do else FALSE.

Parameters

geometry0

The first geometry to test

 

geometry1

The second geometry to test

 

Returns

TRUE of geometry0 and geometry1 intersect else FALSE.

Since: 1.4

Types and Values

struct ClutterPoint

struct ClutterPoint {
  float x;
  float y;
};

A point in 2D space.

Members

float x;

X coordinate, in pixels

 

float y;

Y coordinate, in pixels

 

Since: 1.12


struct ClutterSize

struct ClutterSize {
  float width;
  float height;
};

A size, in 2D space.

Members

float width;

the width, in pixels

 

float height;

the height, in pixels

 

Since: 1.12


struct ClutterRect

struct ClutterRect {
  ClutterPoint origin;
  ClutterSize size;
};

The location and size of a rectangle.

The width and height of a ClutterRect can be negative; Clutter considers a rectangle with an origin of [ 0.0, 0.0 ] and a size of [ 10.0, 10.0 ] to be equivalent to a rectangle with origin of [ 10.0, 10.0 ] and size of [ -10.0, -10.0 ].

Application code can normalize rectangles using clutter_rect_normalize(): this function will ensure that the width and height of a ClutterRect are positive values. All functions taking a ClutterRect as an argument will implicitly normalize it before computing eventual results. For this reason it is safer to access the contents of a ClutterRect by using the provided API at all times, instead of directly accessing the structure members.

Members

ClutterPoint origin;

the origin of the rectangle

 

ClutterSize size;

the size of the rectangle

 

Since: 1.12


struct ClutterVertex

struct ClutterVertex {
  gfloat x;
  gfloat y;
  gfloat z;
};

A point in 3D space, expressed in pixels

Members

gfloat x;

X coordinate of the vertex

 

gfloat y;

Y coordinate of the vertex

 

gfloat z;

Z coordinate of the vertex

 

Since: 0.4


struct ClutterActorBox

struct ClutterActorBox {
  gfloat x1;
  gfloat y1;

  gfloat x2;
  gfloat y2;
};

Bounding box of an actor. The coordinates of the top left and right bottom corners of an actor. The coordinates of the two points are expressed in pixels with sub-pixel precision

Members

gfloat x1;

X coordinate of the top left corner

 

gfloat y1;

Y coordinate of the top left corner

 

gfloat x2;

X coordinate of the bottom right corner

 

gfloat y2;

Y coordinate of the bottom right corner

 

struct ClutterGeometry

struct ClutterGeometry {
  gint   x;
  gint   y;
  guint  width;
  guint  height;
};

ClutterGeometry has been deprecated since version 1.16 and should not be used in newly-written code.

The rectangle containing an actor's bounding box, measured in pixels.

You should not use ClutterGeometry, or operate on its fields directly; you should use cairo_rectangle_int_t or ClutterRect if you need a rectangle type, depending on the precision required.

Members

gint x;

X coordinate of the top left corner of an actor

 

gint y;

Y coordinate of the top left corner of an actor

 

guint width;

width of an actor

 

guint height;

height of an actor

 

struct ClutterKnot

struct ClutterKnot {
  gint x;
  gint y;
};

Point in a path behaviour.

Members

gint x;

X coordinate of the knot

 

gint y;

Y coordinate of the knot

 

Since: 0.2


ClutterPaintVolume

typedef struct _ClutterPaintVolume ClutterPaintVolume;

ClutterPaintVolume is an opaque structure whose members cannot be directly accessed.

A ClutterPaintVolume represents an a bounding volume whose internal representation isn't defined but can be set and queried in terms of an axis aligned bounding box.

A ClutterPaintVolume for a ClutterActor is defined to be relative from the current actor modelview matrix.

Other internal representation and methods for describing the bounding volume may be added in the future.

Since: 1.4


ClutterMatrix

typedef CoglMatrix                              ClutterMatrix;

A type representing a 4x4 matrix.

It is identicaly to CoglMatrix.

Since: 1.12


CLUTTER_POINT_INIT_ZERO

#define CLUTTER_POINT_INIT_ZERO         CLUTTER_POINT_INIT (0.f, 0.f)

A simple macro for initializing a ClutterPoint to (0, 0) when declaring it.

Since: 1.12


CLUTTER_SIZE_INIT_ZERO

#define CLUTTER_SIZE_INIT_ZERO          CLUTTER_SIZE_INIT (0.f, 0.f)

A simple macro for initializing a ClutterSize to (0, 0) when declaring it.

Since: 1.12


CLUTTER_RECT_INIT_ZERO

#define CLUTTER_RECT_INIT_ZERO                  CLUTTER_RECT_INIT (0.f, 0.f, 0.f, 0.f)

A simple macro for initializing a ClutterRect to (0, 0, 0, 0) when declaring it.

Since: 1.12


CLUTTER_VERTEX_INIT_ZERO

#define CLUTTER_VERTEX_INIT_ZERO        CLUTTER_VERTEX_INIT (0.f, 0.f, 0.f)

A simple macro for initializing a ClutterVertex to (0, 0, 0).

Since: 1.12


CLUTTER_ACTOR_BOX_INIT_ZERO

#define CLUTTER_ACTOR_BOX_INIT_ZERO                     CLUTTER_ACTOR_BOX_INIT (0.f, 0.f, 0.f, 0.f)

A simple macro for initializing a ClutterActorBox to 0 when declaring it, e.g.:

1
ClutterActorBox box = CLUTTER_ACTOR_BOX_INIT_ZERO;

Since: 1.12