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:

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

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