Rectangle

Rectangle — Rectangular shape type

Functions

Types and Values

Description

graphene_rect_t is a type representing a rectangle through an origin graphene_point_t point and a graphene_size_t size.

Operations on a graphene_rect_t will normalize the rectangle, to ensure that the origin is always the top-left corner of the rectangle and that the size is always positive.

Functions

GRAPHENE_RECT_INIT()

#define             GRAPHENE_RECT_INIT(x,y,w,h)

Initializes a graphene_rect_t when declaring it.

Parameters

x

the X coordinate of the origin

 

y

the Y coordinate of the origin

 

w

the width

 

h

the height

 

Since: 1.0


graphene_rect_alloc ()

graphene_rect_t *
graphene_rect_alloc (void);

Allocates a new graphene_rect_t.

The contents of the returned rectangle are undefined.

Returns

the newly allocated rectangle.

[transfer full]

Since: 1.0


graphene_rect_free ()

void
graphene_rect_free (graphene_rect_t *r);

Frees the resources allocated by graphene_rect_alloc().

Parameters

Since: 1.0


graphene_rect_init ()

graphene_rect_t *
graphene_rect_init (graphene_rect_t *r,
                    float x,
                    float y,
                    float width,
                    float height);

Initializes the given graphene_rect_t with the given values.

This function will implicitly normalize the graphene_rect_t before returning.

Parameters

r

a graphene_rect_t

 

x

the X coordinate of the graphene_rect_t.origin

 

y

the Y coordinate of the graphene_rect_t.origin

 

width

the width of the graphene_rect_t.size

 

height

the height of the graphene_rect_t.size

 

Returns

the initialized rectangle.

[transfer none]

Since: 1.0


graphene_rect_init_from_rect ()

graphene_rect_t *
graphene_rect_init_from_rect (graphene_rect_t *r,
                              const graphene_rect_t *src);

Initializes r using the given src rectangle.

This function will implicitly normalize the graphene_rect_t before returning.

Parameters

Returns

the initialized rectangle.

[transfer none]

Since: 1.0


graphene_rect_equal ()

bool
graphene_rect_equal (const graphene_rect_t *a,
                     const graphene_rect_t *b);

Checks whether the two given rectangle are equal.

Parameters

Returns

true if the rectangles are equal

Since: 1.0


graphene_rect_normalize ()

graphene_rect_t *
graphene_rect_normalize (graphene_rect_t *r);

Normalizes the passed rectangle.

This function ensures that the size of the rectangle is made of positive values, and that the origin is the top-left corner of the rectangle.

Parameters

Returns

the normalized rectangle.

[transfer none]

Since: 1.0


graphene_rect_get_center ()

void
graphene_rect_get_center (const graphene_rect_t *r,
                          graphene_point_t *p);

Retrieves the coordinates of the center of the given rectangle.

Parameters

r

a graphene_rect_t

 

p

return location for a graphene_point_t.

[out caller-allocates]

Since: 1.0


graphene_rect_get_top_left ()

void
graphene_rect_get_top_left (const graphene_rect_t *r,
                            graphene_point_t *p);

Retrieves the coordinates of the top-left corner of the given rectangle.

Parameters

r

a graphene_rect_t

 

p

return location for a graphene_point_t.

[out caller-allocates]

Since: 1.0


graphene_rect_get_top_right ()

void
graphene_rect_get_top_right (const graphene_rect_t *r,
                             graphene_point_t *p);

Retrieves the coordinates of the top-right corner of the given rectangle.

Parameters

r

a graphene_rect_t

 

p

return location for a graphene_point_t.

[out caller-allocates]

Since: 1.0


graphene_rect_get_bottom_right ()

void
graphene_rect_get_bottom_right (const graphene_rect_t *r,
                                graphene_point_t *p);

Retrieves the coordinates of the bottom-right corner of the given rectangle.

Parameters

r

a graphene_rect_t

 

p

return location for a graphene_point_t.

[out caller-allocates]

Since: 1.0


graphene_rect_get_bottom_left ()

void
graphene_rect_get_bottom_left (const graphene_rect_t *r,
                               graphene_point_t *p);

Retrieves the coordinates of the bottom-left corner of the given rectangle.

Parameters

r

a graphene_rect_t

 

p

return location for a graphene_point_t.

[out caller-allocates]

Since: 1.0


graphene_rect_get_x ()

float
graphene_rect_get_x (const graphene_rect_t *r);

Retrieves the normalized X coordinate of the origin of the given rectangle.

Parameters

Returns

the normalized X coordinate of the rectangle

Since: 1.0


graphene_rect_get_y ()

float
graphene_rect_get_y (const graphene_rect_t *r);

Retrieves the normalized Y coordinate of the origin of the given rectangle.

Parameters

Returns

the normalized Y coordinate of the rectangle

Since: 1.0


graphene_rect_get_width ()

float
graphene_rect_get_width (const graphene_rect_t *r);

Retrieves the normalized width of the given rectangle.

Parameters

Returns

the normalized width of the rectangle

Since: 1.0


graphene_rect_get_height ()

float
graphene_rect_get_height (const graphene_rect_t *r);

Retrieves the normalized height of the given rectangle.

Parameters

Returns

the normalized height of the rectangle

Since: 1.0


graphene_rect_union ()

void
graphene_rect_union (const graphene_rect_t *a,
                     const graphene_rect_t *b,
                     graphene_rect_t *res);

Computes the union of the two given rectangles.

Parameters

a

a graphene_rect_t

 

b

a graphene_rect_t

 

res

return location for a graphene_rect_t.

[out caller-allocates]

Since: 1.0


graphene_rect_intersection ()

bool
graphene_rect_intersection (const graphene_rect_t *a,
                            const graphene_rect_t *b,
                            graphene_rect_t *res);

Computes the intersection of the two given rectangles.

If the two rectangles do not intersect, res will contain a degenerate rectangle with origin in (0, 0) and a size of 0.

Parameters

a

a graphene_rect_t

 

b

a graphene_rect_t

 

res

return location for a graphene_rect_t.

[out caller-allocates][optional]

Returns

true if the two rectangles intersect

Since: 1.0


graphene_rect_contains_point ()

bool
graphene_rect_contains_point (const graphene_rect_t *r,
                              const graphene_point_t *p);

Checks whether a graphene_rect_t contains the given coordinates.

Parameters

Returns

true if the rectangle contains the point

Since: 1.0


graphene_rect_contains_rect ()

bool
graphene_rect_contains_rect (const graphene_rect_t *a,
                             const graphene_rect_t *b);

Checks whether a graphene_rect_t fully contains the given rectangle.

Parameters

Returns

true if the rectangle a fully contains b

Since: 1.0


graphene_rect_offset ()

graphene_rect_t *
graphene_rect_offset (graphene_rect_t *r,
                      float d_x,
                      float d_y);

Offsets the origin by d_x and d_y .

The size of the rectangle is unchanged.

Parameters

r

a graphene_rect_t

 

d_x

the horizontal offset

 

d_y

the vertical offset

 

Returns

the offset rectangle.

[transfer none]

Since: 1.0


graphene_rect_inset ()

graphene_rect_t *
graphene_rect_inset (graphene_rect_t *r,
                     float d_x,
                     float d_y);

Changes the given rectangle to be smaller, or larger depending on the given inset parameters.

To create an inset rectangle, use positive d_x or d_y values; to create a larger, encompassing rectangle, use negative d_x or d_y values.

The origin of the rectangle is offset by d_x and d_y , while the size is adjusted by (2 * d_x , 2 * d_y ). If d_x and d_y are positive values, the size of the rectangle is decreased; if d_x and d_y are negative values, the size of the rectangle is increased.

If the size of the resulting inset rectangle has a negative width or height then the size will be set to zero.

Parameters

r

a graphene_rect_t

 

d_x

the horizontal inset

 

d_y

the vertical inset

 

Returns

the inset rectangle.

[transfer none]

Since: 1.0


graphene_rect_round_to_pixel ()

graphene_rect_t *
graphene_rect_round_to_pixel (graphene_rect_t *r);

Rounds the origin and the size of the given rectangle to their nearest integer values; the rounding is guaranteed to be large enough to contain the original rectangle.

Parameters

Returns

the pixel-aligned rectangle.

[transfer none]

Since: 1.0


graphene_rect_interpolate ()

void
graphene_rect_interpolate (const graphene_rect_t *a,
                           const graphene_rect_t *b,
                           double factor,
                           graphene_rect_t *res);

Linearly interpolates the origin and size of the two given rectangles.

Parameters

a

a graphene_rect_t

 

b

a graphene_rect_t

 

factor

the linear interpolation factor

 

res

return location for the interpolated rectangle.

[out caller-allocates]

Since: 1.0

Types and Values

graphene_rect_t

typedef struct {
  graphene_point_t origin;
  graphene_size_t size;
} graphene_rect_t;

The location and size of a rectangle region.

The width and height of a graphene_rect_t can be negative; for instance, a graphene_rect_t with an origin of [ 0, 0 ] and a size of [ 10, 10 ] is equivalent to a graphene_rect_t with an origin of [ 10, 10 ] and a size of [ -10, -10 ].

Application code can normalize rectangles using graphene_rect_normalize(); this function will ensure that the width and height of a rectangle are positive values. All functions taking a graphene_rect_t as an argument will internally operate on a normalized copy; all functions returning a graphene_rect_t will always return a normalized rectangle.

Members

graphene_point_t origin;

the coordinates of the origin of the rectangle

 

graphene_size_t size;

the size of the rectangle

 

Since: 1.0