Rect

Added in version 1.0.

class Rect(*args, **kwargs)

The location and size of a rectangle region.

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

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

Methods

class Rect

classmethod alloc() → Rect

Allocates a new Rect.

The contents of the returned rectangle are undefined.

Added in version 1.0.

contains_point(p: Point) → bool

Checks whether a Rect contains the given coordinates.

Added in version 1.0.

Parameters:

p – a Point

contains_rect(b: Rect) → bool

Checks whether a Rect fully contains the given rectangle.

Added in version 1.0.

Parameters:

b – a Rect

equal(b: Rect) → bool

Checks whether the two given rectangle are equal.

Added in version 1.0.

Parameters:

b – a Rect

expand(p: Point) → Rect

Expands a Rect to contain the given Point.

Added in version 1.4.

Parameters:

p – a Point

free() → None

Frees the resources allocated by alloc().

Added in version 1.0.

get_area() → float

Compute the area of given normalized rectangle.

Added in version 1.10.

get_bottom_left() → Point

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

Added in version 1.0.

get_bottom_right() → Point

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

Added in version 1.0.

get_center() → Point

Retrieves the coordinates of the center of the given rectangle.

Added in version 1.0.

get_height() → float

Retrieves the normalized height of the given rectangle.

Added in version 1.0.

get_top_left() → Point

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

Added in version 1.0.

get_top_right() → Point

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

Added in version 1.0.

get_vertices() → list[Vec2]

Computes the four vertices of a Rect.

Added in version 1.4.

get_width() → float

Retrieves the normalized width of the given rectangle.

Added in version 1.0.

get_x() → float

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

Added in version 1.0.

get_y() → float

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

Added in version 1.0.

init(x: float, y: float, width: float, height: float) → Rect

Initializes the given Rect with the given values.

This function will implicitly normalize the Rect before returning.

Added in version 1.0.

Parameters:

• 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

init_from_rect(src: Rect) → Rect

Initializes r using the given src rectangle.

This function will implicitly normalize the Rect before returning.

Added in version 1.0.

Parameters:

src – a Rect

inset(d_x: float, d_y: float) → 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.

Added in version 1.0.

Parameters:

• d_x – the horizontal inset

• d_y – the vertical inset

inset_r(d_x: float, d_y: float) → 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.

Added in version 1.4.

Parameters:

• d_x – the horizontal inset

• d_y – the vertical inset

interpolate(b: Rect, factor: float) → Rect

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

Added in version 1.0.

Parameters:

• b – a Rect

• factor – the linear interpolation factor

intersection(b: Rect) → tuple[bool, 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.

Added in version 1.0.

Parameters:

b – a Rect

normalize() → 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.

Added in version 1.0.

normalize_r() → 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.

Added in version 1.4.

offset(d_x: float, d_y: float) → Rect

Offsets the origin by d_x and d_y.

The size of the rectangle is unchanged.

Added in version 1.0.

Parameters:

• d_x – the horizontal offset

• d_y – the vertical offset

offset_r(d_x: float, d_y: float) → Rect

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

The size of the rectangle is left unchanged.

Added in version 1.4.

Parameters:

• d_x – the horizontal offset

• d_y – the vertical offset

round() → 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 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.

Added in version 1.4.

Deprecated since version 1.10: Use round_extents() instead

round_extents() → 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.

Added in version 1.10.

round_to_pixel() → 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.

Added in version 1.0.

Deprecated since version 1.4: Use round() instead

scale(s_h: float, s_v: float) → Rect

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

Added in version 1.10.

Parameters:

• s_h – horizontal scale factor

• s_v – vertical scale factor

union(b: Rect) → Rect

Computes the union of the two given rectangles.

The union in the image above is the blue outline.

Added in version 1.0.

Parameters:

b – a Rect

classmethod zero() → Rect

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

Added in version 1.4.

Fields

class Rect

origin

The coordinates of the origin of the rectangle

size

The size of the rectangle