Graphene.Rect¶

Fields¶

Name	Type	Access	Description
origin	`Graphene.Point`	r/w	the coordinates of the origin of the rectangle
size	`Graphene.Size`	r/w	the size of the rectangle

Methods¶

class	`alloc` ()
class	`zero` ()
	`contains_point` (p)
	`contains_rect` (b)
	`equal` (b)
	`expand` (p)
	`free` ()
	`get_area` ()
	`get_bottom_left` ()
	`get_bottom_right` ()
	`get_center` ()
	`get_height` ()
	`get_top_left` ()
	`get_top_right` ()
	`get_vertices` ()
	`get_width` ()
	`get_x` ()
	`get_y` ()
	`init` (x, y, width, height)
	`init_from_rect` (src)
	`inset` (d_x, d_y)
	`inset_r` (d_x, d_y)
	`interpolate` (b, factor)
	`intersection` (b)
	`normalize` ()
	`normalize_r` ()
	`offset` (d_x, d_y)
	`offset_r` (d_x, d_y)
	`round` ()
	`round_extents` ()
	`round_to_pixel` ()
	`scale` (s_h, s_v)
	`union` (b)

Details¶

class Graphene.Rect¶

The location and size of a rectangle region.

The width and height of a Graphene.Rect can be negative; for instance, a Graphene.Rect with an origin of [ 0, 0 ] and a size of [ 10, 10 ] is equivalent to a Graphene.Rect 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 as an argument will internally operate on a normalized copy; all functions returning a Graphene.Rect will always return a normalized rectangle.

New in version 1.0.

classmethod alloc()¶

Returns:: the newly allocated rectangle
Return type:: Graphene.Rect

Allocates a new Graphene.Rect.

The contents of the returned rectangle are undefined.

New in version 1.0.

classmethod zero()¶

Returns:: a fixed rectangle
Return type:: Graphene.Rect

Returns a degenerate rectangle with origin fixed at (0, 0) and a size of 0, 0.

New in version 1.4.

contains_point(p)¶

Parameters:: p (Graphene.Point) – a Graphene.Point
Returns:: true if the rectangle contains the point
Return type:: bool

Checks whether a Graphene.Rect contains the given coordinates.

New in version 1.0.

contains_rect(b)¶

Parameters:: b (Graphene.Rect) – a Graphene.Rect
Returns:: true if the rectangle self fully contains b
Return type:: bool

Checks whether a Graphene.Rect fully contains the given rectangle.

New in version 1.0.

equal(b)¶

Parameters:: b (Graphene.Rect) – a Graphene.Rect
Returns:: true if the rectangles are equal
Return type:: bool

Checks whether the two given rectangle are equal.

New in version 1.0.

expand(p)¶

Parameters:: p (Graphene.Point) – a Graphene.Point
Returns:: return location for the expanded rectangle
Return type:: res: Graphene.Rect

Expands a Graphene.Rect to contain the given Graphene.Point.

New in version 1.4.

free()¶: Frees the resources allocated by Graphene.Rect.alloc().

New in version 1.0.

get_area()¶

Returns:: the area of the normalized rectangle
Return type:: float

Compute the area of given normalized rectangle.

New in version 1.10.

get_bottom_left()¶

Returns:: return location for a Graphene.Point
Return type:: p: Graphene.Point

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

New in version 1.0.

get_bottom_right()¶

Returns:: return location for a Graphene.Point
Return type:: p: Graphene.Point

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

New in version 1.0.

get_center()¶

Returns:: return location for a Graphene.Point
Return type:: p: Graphene.Point

Retrieves the coordinates of the center of the given rectangle.

New in version 1.0.

get_height()¶

Returns:: the normalized height of the rectangle
Return type:: float

Retrieves the normalized height of the given rectangle.

New in version 1.0.

get_top_left()¶

Returns:: return location for a Graphene.Point
Return type:: p: Graphene.Point

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

New in version 1.0.

get_top_right()¶

Returns:: return location for a Graphene.Point
Return type:: p: Graphene.Point

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

New in version 1.0.

get_vertices()¶

Returns:: return location for an array of 4 Graphene.Vec2
Return type:: vertices: [Graphene.Vec2]

Computes the four vertices of a Graphene.Rect.

New in version 1.4.

get_width()¶

Returns:: the normalized width of the rectangle
Return type:: float

Retrieves the normalized width of the given rectangle.

New in version 1.0.

get_x()¶

Returns:: the normalized X coordinate of the rectangle
Return type:: float

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

New in version 1.0.

get_y()¶

Returns:: the normalized Y coordinate of the rectangle
Return type:: float

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

New in version 1.0.

init(x, y, width, height)¶

Parameters:

x (float) – the X coordinate of the graphene_rect_t.origin
y (float) – the Y coordinate of the graphene_rect_t.origin
width (float) – the width of the graphene_rect_t.size
height (float) – the height of the graphene_rect_t.size

Returns:

the initialized rectangle

Return type:

Graphene.Rect

Initializes the given Graphene.Rect with the given values.

This function will implicitly normalize the Graphene.Rect before returning.

New in version 1.0.

init_from_rect(src)¶

Parameters:: src (Graphene.Rect) – a Graphene.Rect
Returns:: the initialized rectangle
Return type:: Graphene.Rect

Initializes self using the given src rectangle.

This function will implicitly normalize the Graphene.Rect before returning.

New in version 1.0.

inset(d_x, d_y)¶

Parameters:

d_x (float) – the horizontal inset
d_y (float) – the vertical inset

Returns:

the inset rectangle

Return type:

Graphene.Rect

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.

New in version 1.0.

inset_r(d_x, d_y)¶

Parameters:

d_x (float) – the horizontal inset
d_y (float) – the vertical inset

Returns:

return location for the inset rectangle

Return type:

res: Graphene.Rect

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.

New in version 1.4.

interpolate(b, factor)¶

Parameters:

b (Graphene.Rect) – a Graphene.Rect
factor (float) – the linear interpolation factor

Returns:

return location for the interpolated rectangle

Return type:

res: Graphene.Rect

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

New in version 1.0.

intersection(b)¶

Parameters:

b (Graphene.Rect) – a Graphene.Rect

Returns:

true if the two rectangles intersect

res:: return location for a Graphene.Rect

Return type:

(bool, res: Graphene.Rect)

Computes the intersection of the two given rectangles.

The intersection in the image above is the blue outline.

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

New in version 1.0.

normalize()¶

Returns:: the normalized rectangle
Return type:: Graphene.Rect

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.

New in version 1.0.

normalize_r()¶

Returns:: the return location for the normalized rectangle
Return type:: res: Graphene.Rect

Normalizes the passed rectangle.

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

New in version 1.4.

offset(d_x, d_y)¶

Parameters:

d_x (float) – the horizontal offset
d_y (float) – the vertical offset

Returns:

the offset rectangle

Return type:

Graphene.Rect

Offsets the origin by d_x and d_y.

The size of the rectangle is unchanged.

New in version 1.0.

offset_r(d_x, d_y)¶

Parameters:

d_x (float) – the horizontal offset
d_y (float) – the vertical offset

Returns:

return location for the offset rectangle

Return type:

res: Graphene.Rect

Offsets the origin of the given rectangle by d_x and d_y.

The size of the rectangle is left unchanged.

New in version 1.4.

round()¶

Returns:: return location for the rounded rectangle
Return type:: res: Graphene.Rect

Rounds the origin and size of the given rectangle to their nearest integer values; the rounding is guaranteed to be large enough to have an area bigger or equal to the original rectangle, but might not fully contain its extents. Use Graphene.Rect.round_extents() in case you need to round to a rectangle that covers fully the original one.

This function is the equivalent of calling floor on the coordinates of the origin, and ceil on the size.

New in version 1.4.

Deprecated since version 1.10: Use Graphene.Rect.round_extents() instead

round_extents()¶

Returns:: return location for the rectangle with rounded extents
Return type:: res: Graphene.Rect

Rounds the origin of the given rectangle to its nearest integer value and and recompute the size so that the rectangle is large enough to contain all the conrners of the original rectangle.

This function is the equivalent of calling floor on the coordinates of the origin, and recomputing the size calling ceil on the bottom-right coordinates.

If you want to be sure that the rounded rectangle completely covers the area that was covered by the original rectangle — i.e. you want to cover the area including all its corners — this function will make sure that the size is recomputed taking into account the ceiling of the coordinates of the bottom-right corner. If the difference between the original coordinates and the coordinates of the rounded rectangle is greater than the difference between the original size and and the rounded size, then the move of the origin would not be compensated by a move in the anti-origin, leaving the corners of the original rectangle outside the rounded one.

New in version 1.10.

round_to_pixel()¶

Returns:: the pixel-aligned rectangle.
Return type:: Graphene.Rect

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.

New in version 1.0.

Deprecated since version 1.4: Use Graphene.Rect.round() instead

scale(s_h, s_v)¶

Parameters:

s_h (float) – horizontal scale factor
s_v (float) – vertical scale factor

Returns:

return location for the scaled rectangle

Return type:

res: Graphene.Rect

Scales the size and origin of a rectangle horizontaly by s_h, and vertically by s_v. The result res is normalized.

New in version 1.10.

union(b)¶

Parameters:: b (Graphene.Rect) – a Graphene.Rect
Returns:: return location for a Graphene.Rect
Return type:: res: Graphene.Rect

Computes the union of the two given rectangles.

The union in the image above is the blue outline.

New in version 1.0.