Base geometric types

## Base geometric types Base geometric types — Common geometric data types used by Clutter |

## Synopsis

    struct              ClutterPoint;
    struct              ClutterSize;
    struct              ClutterRect;
    struct              ClutterVertex;
    struct              ClutterActorBox;
    struct              ClutterGeometry;
    struct              ClutterKnot;
                        ClutterPaintVolume;
    typedef             ClutterMatrix;

    #define             CLUTTER_POINT_INIT                  (x,
                                                             y)
    #define             CLUTTER_POINT_INIT_ZERO
    const ClutterPoint * clutter_point_zero                 (void);
    ClutterPoint *      clutter_point_alloc                 (void);
    ClutterPoint *      clutter_point_init                  (ClutterPoint *point,
                                                             float x,
                                                             float y);
    ClutterPoint *      clutter_point_copy                  (const ClutterPoint *point);
    void                clutter_point_free                  (ClutterPoint *point);
    gboolean            clutter_point_equals                (const ClutterPoint *a,
                                                             const ClutterPoint *b);
    float               clutter_point_distance              (const ClutterPoint *a,
                                                             const ClutterPoint *b,
                                                             float *x_distance,
                                                             float *y_distance);

    #define             CLUTTER_SIZE_INIT                   (width,
                                                             height)
    #define             CLUTTER_SIZE_INIT_ZERO
    ClutterSize *       clutter_size_alloc                  (void);
    ClutterSize *       clutter_size_init                   (ClutterSize *size,
                                                             float width,
                                                             float height);
    ClutterSize *       clutter_size_copy                   (const ClutterSize *size);
    void                clutter_size_free                   (ClutterSize *size);
    gboolean            clutter_size_equals                 (const ClutterSize *a,
                                                             const ClutterSize *b);

    #define             CLUTTER_RECT_INIT                   (x,
                                                             y,
                                                             width,
                                                             height)
    #define             CLUTTER_RECT_INIT_ZERO
    const ClutterRect * clutter_rect_zero                   (void);
    ClutterRect *       clutter_rect_alloc                  (void);
    ClutterRect *       clutter_rect_init                   (ClutterRect *rect,
                                                             float x,
                                                             float y,
                                                             float width,
                                                             float height);
    ClutterRect *       clutter_rect_copy                   (const ClutterRect *rect);
    void                clutter_rect_free                   (ClutterRect *rect);
    gboolean            clutter_rect_equals                 (ClutterRect *a,
                                                             ClutterRect *b);
    ClutterRect *       clutter_rect_normalize              (ClutterRect *rect);
    void                clutter_rect_get_center             (ClutterRect *rect,
                                                             ClutterPoint *center);
    gboolean            clutter_rect_contains_point         (ClutterRect *rect,
                                                             ClutterPoint *point);
    gboolean            clutter_rect_contains_rect          (ClutterRect *a,
                                                             ClutterRect *b);
    void                clutter_rect_union                  (ClutterRect *a,
                                                             ClutterRect *b,
                                                             ClutterRect *res);
    gboolean            clutter_rect_intersection           (ClutterRect *a,
                                                             ClutterRect *b,
                                                             ClutterRect *res);
    void                clutter_rect_offset                 (ClutterRect *rect,
                                                             float d_x,
                                                             float d_y);
    void                clutter_rect_inset                  (ClutterRect *rect,
                                                             float d_x,
                                                             float d_y);
    void                clutter_rect_clamp_to_pixel         (ClutterRect *rect);
    float               clutter_rect_get_x                  (ClutterRect *rect);
    float               clutter_rect_get_y                  (ClutterRect *rect);
    float               clutter_rect_get_width              (ClutterRect *rect);
    float               clutter_rect_get_height             (ClutterRect *rect);

    #define             CLUTTER_VERTEX_INIT                 (x,
                                                             y,
                                                             z)
    #define             CLUTTER_VERTEX_INIT_ZERO
    ClutterVertex *     clutter_vertex_new                  (gfloat x,
                                                             gfloat y,
                                                             gfloat z);
    ClutterVertex *     clutter_vertex_alloc                (void);
    ClutterVertex *     clutter_vertex_init                 (ClutterVertex *vertex,
                                                             gfloat x,
                                                             gfloat y,
                                                             gfloat z);
    ClutterVertex *     clutter_vertex_copy                 (const ClutterVertex *vertex);
    void                clutter_vertex_free                 (ClutterVertex *vertex);
    gboolean            clutter_vertex_equal                (const ClutterVertex *vertex_a,
                                                             const ClutterVertex *vertex_b);

    #define             CLUTTER_ACTOR_BOX_INIT              (x_1,
                                                             y_1,
                                                             x_2,
                                                             y_2)
    #define             CLUTTER_ACTOR_BOX_INIT_ZERO
    ClutterActorBox *   clutter_actor_box_new               (gfloat x_1,
                                                             gfloat y_1,
                                                             gfloat x_2,
                                                             gfloat y_2);
    ClutterActorBox *   clutter_actor_box_alloc             (void);
    ClutterActorBox *   clutter_actor_box_init              (ClutterActorBox *box,
                                                             gfloat x_1,
                                                             gfloat y_1,
                                                             gfloat x_2,
                                                             gfloat y_2);
    void                clutter_actor_box_init_rect         (ClutterActorBox *box,
                                                             gfloat x,
                                                             gfloat y,
                                                             gfloat width,
                                                             gfloat height);
    ClutterActorBox *   clutter_actor_box_copy              (const ClutterActorBox *box);
    void                clutter_actor_box_free              (ClutterActorBox *box);
    gboolean            clutter_actor_box_equal             (const ClutterActorBox *box_a,
                                                             const ClutterActorBox *box_b);
    gfloat              clutter_actor_box_get_x             (const ClutterActorBox *box);
    gfloat              clutter_actor_box_get_y             (const ClutterActorBox *box);
    gfloat              clutter_actor_box_get_width         (const ClutterActorBox *box);
    gfloat              clutter_actor_box_get_height        (const ClutterActorBox *box);
    void                clutter_actor_box_set_origin        (ClutterActorBox *box,
                                                             gfloat x,
                                                             gfloat y);
    void                clutter_actor_box_get_origin        (const ClutterActorBox *box,
                                                             gfloat *x,
                                                             gfloat *y);
    void                clutter_actor_box_set_size          (ClutterActorBox *box,
                                                             gfloat width,
                                                             gfloat height);
    void                clutter_actor_box_get_size          (const ClutterActorBox *box,
                                                             gfloat *width,
                                                             gfloat *height);
    gfloat              clutter_actor_box_get_area          (const ClutterActorBox *box);
    gboolean            clutter_actor_box_contains          (const ClutterActorBox *box,
                                                             gfloat x,
                                                             gfloat y);
    void                clutter_actor_box_from_vertices     (ClutterActorBox *box,
                                                             const ClutterVertex verts[]);
    void                clutter_actor_box_clamp_to_pixel    (ClutterActorBox *box);
    void                clutter_actor_box_interpolate       (const ClutterActorBox *initial,
                                                             const ClutterActorBox *final,
                                                             gdouble progress,
                                                             ClutterActorBox *result);
    void                clutter_actor_box_union             (const ClutterActorBox *a,
                                                             const ClutterActorBox *b,
                                                             ClutterActorBox *result);

    ClutterPaintVolume * clutter_paint_volume_copy          (const ClutterPaintVolume *pv);
    void                clutter_paint_volume_free           (ClutterPaintVolume *pv);
    void                clutter_paint_volume_set_origin     (ClutterPaintVolume *pv,
                                                             const ClutterVertex *origin);
    void                clutter_paint_volume_get_origin     (const ClutterPaintVolume *pv,
                                                             ClutterVertex *vertex);
    void                clutter_paint_volume_set_width      (ClutterPaintVolume *pv,
                                                             gfloat width);
    gfloat              clutter_paint_volume_get_width      (const ClutterPaintVolume *pv);
    void                clutter_paint_volume_set_height     (ClutterPaintVolume *pv,
                                                             gfloat height);
    gfloat              clutter_paint_volume_get_height     (const ClutterPaintVolume *pv);
    void                clutter_paint_volume_set_depth      (ClutterPaintVolume *pv,
                                                             gfloat depth);
    gfloat              clutter_paint_volume_get_depth      (const ClutterPaintVolume *pv);
    gboolean            clutter_paint_volume_set_from_allocation
                                                            (ClutterPaintVolume *pv,
                                                             ClutterActor *actor);
    void                clutter_paint_volume_union          (ClutterPaintVolume *pv,
                                                             const ClutterPaintVolume *another_pv);
    void                clutter_paint_volume_union_box      (ClutterPaintVolume *pv,
                                                             const ClutterActorBox *box);

    ClutterMatrix *     clutter_matrix_alloc                (void);
    void                clutter_matrix_free                 (ClutterMatrix *matrix);
    ClutterMatrix *     clutter_matrix_init_from_array      (ClutterMatrix *matrix,
                                                             const float values[16]);
    ClutterMatrix *     clutter_matrix_init_from_matrix     (ClutterMatrix *a,
                                                             const ClutterMatrix *b);
    ClutterMatrix *     clutter_matrix_init_identity        (ClutterMatrix *matrix);

    ClutterKnot *       clutter_knot_copy                   (const ClutterKnot *knot);
    void                clutter_knot_free                   (ClutterKnot *knot);
    gboolean            clutter_knot_equal                  (const ClutterKnot *knot_a,
                                                             const ClutterKnot *knot_b);

    void                clutter_geometry_union              (const ClutterGeometry *geometry_a,
                                                             const ClutterGeometry *geometry_b,
                                                             ClutterGeometry *result);
    gboolean            clutter_geometry_intersects         (const ClutterGeometry *geometry0,
                                                             const ClutterGeometry *geometry1);

## Description

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

## Details

### struct ClutterPoint

    struct ClutterPoint {
      float x;
      float y;
    };

A point in 2D space.

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.

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.

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

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

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;
    };

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

### Warning

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.

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.

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

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

`x` : | X coordinate
`y` : | Y coordinate

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_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.

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.

`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`.

`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`.

`point` : | a ClutterPoint

Since 1.12

### clutter_point_equals ()

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

Compares two ClutterPoint for equality.

`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.

`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);

`width` : | the width
`height` : | the height

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

    ClutterSize *       clutter_size_alloc                  (void);

Allocates a new ClutterSize.

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.

`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`.

`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`.

`size` : | a ClutterSize

Since 1.12

### clutter_size_equals ()

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

Compares two ClutterSize for equality.

`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);

`x` : | the X coordinate
`y` : | the Y coordinate
`width` : | the width
`height` : | the height

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_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);

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.

`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.

`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`.

`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.

`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.

`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.

`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.

`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.

`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.

`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`.

`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.

`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.

`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.

`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`.

`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`.

`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`.

`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`.

`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);

`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_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_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);

`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.

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.

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

`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()`.

`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

`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);

`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_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

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

`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.

`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.

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

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

`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

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

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

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

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

`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.

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

`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.

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

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

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

`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()`.

`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

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

`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`.

`a` : | (in) the first ClutterActorBox
`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

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

`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)

`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.

`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.

`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.

### Note

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; after `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.

### Note

There are no accuracy guarantees for the reported width, except that it must always be >= to the true width. This is because actors may report simple, loose fitting paint-volumes for efficiency

`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.

`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.

### Note

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; after `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.

### Note

There are no accuracy guarantees for the reported height, except that it must always be >= to the true height. This is because actors may report simple, loose fitting paint-volumes for efficiency

`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.

`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.

### Note

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; after `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.

### Note

There are no accuracy guarantees for the reported depth, except that it must always be >= to the true depth. This is because actors may report simple, loose fitting paint-volumes for efficiency.

`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);
    }

`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`.

### Note

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

`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.

`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()`.

`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.

`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`.

`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

`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.

`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.

`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.

`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);

Find the union of two rectangles represented as ClutterGeometry.

`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);

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

`geometry0` : | The first geometry to test
`geometry1` : | The second geometry to test
Returns : | `TRUE` of `geometry0` and geometry1 intersect else `FALSE`.

Since 1.4