Gnome::Graphene::N-Rect

Description

The location and size of a rectangle region.

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

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

Methods

contains-point

Checks whether a Gnome::Graphene::N-Rect contains the given coordinates.

method contains-point ( CArray[N-Point] $p --> gboolean )

• $p; a Gnome::Graphene::N-Point.

Return value; true if the rectangle contains the point.

contains-rect

Checks whether a Gnome::Graphene::N-Rect fully contains the given rectangle.

method contains-rect ( CArray[N-Rect] $b --> gboolean )

• $b; a Gnome::Graphene::N-Rect.

Return value; true if the rectangle $a fully contains $b.

equal

Checks whether the two given rectangle are equal.

method equal ( CArray[N-Rect] $b --> gboolean )

• $b; a Gnome::Graphene::N-Rect.

Return value; true if the rectangles are equal.

expand

Expands a Gnome::Graphene::N-Rect to contain the given Gnome::Graphene::N-Point.

method expand ( CArray[N-Point] $p, CArray[N-Rect] $res )

• $p; a Gnome::Graphene::N-Point.

• $res; return location for the expanded rectangle.

free

Frees the resources allocated by .alloc().

method free ( )

get-area

Compute the area of given normalized rectangle.

method get-area (--> Num )

Return value; the area of the normalized rectangle.

get-bottom-left

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

method get-bottom-left ( CArray[N-Point] $p )

• $p; return location for a Gnome::Graphene::N-Point.

get-bottom-right

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

method get-bottom-right ( CArray[N-Point] $p )

• $p; return location for a Gnome::Graphene::N-Point.

get-center

Retrieves the coordinates of the center of the given rectangle.

method get-center ( CArray[N-Point] $p )

• $p; return location for a Gnome::Graphene::N-Point.

get-height

Retrieves the normalized height of the given rectangle.

method get-height (--> Num )

Return value; the normalized height of the rectangle.

get-top-left

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

method get-top-left ( CArray[N-Point] $p )

• $p; return location for a Gnome::Graphene::N-Point.

get-top-right

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

method get-top-right ( CArray[N-Point] $p )

• $p; return location for a Gnome::Graphene::N-Point.

get-vertices

Computes the four vertices of a Gnome::Graphene::N-Rect.

method get-vertices ( CArray[N-Vec2] $vertices )

• $vertices; return location for an array of 4 graphene_vec2_t.

get-width

Retrieves the normalized width of the given rectangle.

method get-width (--> Num )

Return value; the normalized width of the rectangle.

get-x

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

method get-x (--> Num )

Return value; the normalized X coordinate of the rectangle.

get-y

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

method get-y (--> Num )

Return value; the normalized Y coordinate of the rectangle.

init

Initializes the given Gnome::Graphene::N-Rect with the given values.

This function will implicitly normalize the Gnome::Graphene::N-Rect before returning.

method init ( Num() $x, Num() $y, Num() $width, Num() $height --> CArray[N-Rect] )

• $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.

Return value; the initialized rectangle.

init-from-rect

Initializes $r using the given $src rectangle.

This function will implicitly normalize the Gnome::Graphene::N-Rect before returning.

method init-from-rect ( CArray[N-Rect] $src --> CArray[N-Rect] )

• $src; a Gnome::Graphene::N-Rect.

Return value; the initialized rectangle.

inset

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.

method inset ( Num() $d-x, Num() $d-y --> CArray[N-Rect] )

• $d-x; the horizontal inset.

• $d-y; the vertical inset.

Return value; the inset rectangle.

inset-r

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.

method inset-r ( Num() $d-x, Num() $d-y, CArray[N-Rect] $res )

• $d-x; the horizontal inset.

• $d-y; the vertical inset.

• $res; return location for the inset rectangle.

interpolate

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

method interpolate ( CArray[N-Rect] $b, Num() $factor, CArray[N-Rect] $res )

• $b; a Gnome::Graphene::N-Rect.

• $factor; the linear interpolation factor.

• $res; return location for the interpolated rectangle.

intersection

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.

method intersection ( CArray[N-Rect] $b, CArray[N-Rect] $res --> gboolean )

• $b; a Gnome::Graphene::N-Rect.

• $res; return location for a Gnome::Graphene::N-Rect.

Return value; true if the two rectangles intersect.

normalize

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.

method normalize (--> CArray[N-Rect] )

Return value; the normalized rectangle.

normalize-r

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.

method normalize-r ( CArray[N-Rect] $res )

• $res; the return location for the normalized rectangle.

offset

Offsets the origin by $d-x and $d-y.

The size of the rectangle is unchanged.

method offset ( Num() $d-x, Num() $d-y --> CArray[N-Rect] )

• $d-x; the horizontal offset.

• $d-y; the vertical offset.

Return value; the offset rectangle.

offset-r

Offsets the origin of the given rectangle by $d-x and $d-y.

The size of the rectangle is left unchanged.

method offset-r ( Num() $d-x, Num() $d-y, CArray[N-Rect] $res )

• $d-x; the horizontal offset.

• $d-y; the vertical offset.

• $res; return location for the offset rectangle.

round-extents

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.

method round-extents ( CArray[N-Rect] $res )

• $res; return location for the rectangle with rounded extents.

scale

Scales the size and origin of a rectangle horizontaly by $s-h, and vertically by $s-v. The result $res is normalized.

method scale ( Num() $s-h, Num() $s-v, CArray[N-Rect] $res )

• $s-h; horizontal scale factor.

• $s-v; vertical scale factor.

• $res; return location for the scaled rectangle.

union

Computes the union of the two given rectangles.


The union in the image above is the blue outline.

method union ( CArray[N-Rect] $b, CArray[N-Rect] $res )

• $b; a Gnome::Graphene::N-Rect.

• $res; return location for a Gnome::Graphene::N-Rect.

Functions

alloc

Allocates a new Gnome::Graphene::N-Rect.

The contents of the returned rectangle are undefined.

method alloc (--> CArray[N-Rect] )

Return value; the newly allocated rectangle.

zero

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

method zero (--> CArray[N-Rect] )

Return value; a fixed rectangle.