Base geometric types: Clutter Reference Manual

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

## Types and Values

struct | ClutterPoint
struct | ClutterSize
struct | ClutterRect
struct | ClutterVertex
struct | ClutterActorBox
struct | ClutterGeometry
struct | ClutterKnot
| ClutterPaintVolume
typedef | ClutterMatrix
#define | CLUTTER_POINT_INIT_ZERO
#define | CLUTTER_SIZE_INIT_ZERO
#define | CLUTTER_RECT_INIT_ZERO
#define | CLUTTER_VERTEX_INIT_ZERO
#define | CLUTTER_ACTOR_BOX_INIT_ZERO

## 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:

    1
    clutter_vertex_init (clutter_vertex_alloc (), x, y, z);

#### 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` ClutterActorBox<!-- -->es 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

pv | a ClutterPaintVolume |

#### 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

pv | a ClutterPaintVolume |

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

pv | a ClutterPaintVolume |

#### 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

pv | a ClutterPaintVolume |

#### 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

pv | a ClutterPaintVolume |

#### 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