Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Overhaul Rect2 & Rect2i Documentation #69816

Merged
merged 1 commit into from
Aug 2, 2023
Merged

Overhaul Rect2 & Rect2i Documentation #69816

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 73 additions & 40 deletions doc/classes/Rect2.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
A 2D axis-aligned bounding box using floating-point coordinates.
</brief_description>
<description>
[Rect2] consists of a position, a size, and several utility functions. It is typically used for fast overlap tests.
It uses floating-point coordinates. If you need integer coordinates, use [Rect2i] instead.
The 3D counterpart to [Rect2] is [AABB].
Negative values for [member size] are not supported and will not work for most methods. Use [method abs] to get a Rect2 with a positive size.
The [Rect2] built-in [Variant] type represents an axis-aligned rectangle in a 2D space. It is defined by its [member position] and [member size], which are [Vector2]. It is frequently used for fast overlap tests (see [method intersects]). Although [Rect2] itself is axis-aligned, it can be combined with [Transform2D] to represent a rotated or skewed rectangle.
For integer coordinates, use [Rect2i]. The 3D equivalent to [Rect2] is [AABB].
[b]Note:[/b] Negative values for [member size] are not supported. With negative size, most [Rect2] methods do not work correctly. Use [method abs] to get an equivalent [Rect2] with a non-negative size.
[b]Note:[/b] In a boolean context, a [Rect2] evaluates to [code]false[/code] if both [member position] and [member size] are zero (equal to [constant Vector2.ZERO]). Otherwise, it always evaluates to [code]true[/code].
</description>
<tutorials>
<link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link>
Expand All @@ -18,7 +18,7 @@
<constructor name="Rect2">
<return type="Rect2" />
<description>
Constructs a default-initialized [Rect2] with default (zero) values of [member position] and [member size].
Constructs a [Rect2] with its [member position] and [member size] set to [constant Vector2.ZERO].
</description>
</constructor>
<constructor name="Rect2">
Expand All @@ -40,7 +40,7 @@
<param index="0" name="position" type="Vector2" />
<param index="1" name="size" type="Vector2" />
<description>
Constructs a [Rect2] by position and size.
Constructs a [Rect2] by [param position] and [param size].
</description>
</constructor>
<constructor name="Rect2">
Expand All @@ -50,63 +50,83 @@
<param index="2" name="width" type="float" />
<param index="3" name="height" type="float" />
<description>
Constructs a [Rect2] by x, y, width, and height.
Constructs a [Rect2] by setting its [member position] to ([param x], [param y]), and its [member size] to ([param width], [param height]).
</description>
</constructor>
</constructors>
<methods>
<method name="abs" qualifiers="const">
<return type="Rect2" />
<description>
Returns a [Rect2] with equivalent position and area, modified so that the top-left corner is the origin and [code]width[/code] and [code]height[/code] are positive.
Returns a [Rect2] equivalent to this rectangle, with its width and height modified to be non-negative values, and with its [member position] being the top-left corner of the rectangle.
[codeblocks]
[gdscript]
var rect = Rect2(25, 25, -100, -50)
var absolute = rect.abs() # absolute is Rect2(-75, -25, 100, 50)
[/gdscript]
[csharp]
var rect = new Rect2(25, 25, -100, -50);
var absolute = rect.Abs(); // absolute is Rect2(-75, -25, 100, 50)
[/csharp]
[/codeblocks]
[b]Note:[/b] It's recommended to use this method when [member size] is negative, as most other methods in Godot assume that the [member position] is the top-left corner, and the [member end] is the bottom-right corner.
</description>
</method>
<method name="encloses" qualifiers="const">
<return type="bool" />
<param index="0" name="b" type="Rect2" />
<description>
Returns [code]true[/code] if this [Rect2] completely encloses another one.
Returns [code]true[/code] if this rectangle [i]completely[/i] encloses the [param b] rectangle.
</description>
</method>
<method name="expand" qualifiers="const">
<return type="Rect2" />
<param index="0" name="to" type="Vector2" />
<description>
Returns a copy of this [Rect2] expanded to include a given point.
[b]Example:[/b]
Returns a copy of this rectangle expanded to include the given [param to] point, if necessary.
[codeblocks]
[gdscript]
# position (-3, 2), size (1, 1)
var rect = Rect2(Vector2(-3, 2), Vector2(1, 1))
# position (-3, -1), size (3, 4), so we fit both rect and Vector2(0, -1)
var rect2 = rect.expand(Vector2(0, -1))
var rect = Rect2(0, 0, 5, 2)

rect = rect.expand(Vector2(10, 0)) # rect is Rect2(0, 0, 10, 2)
rect = rect.expand(Vector2(-5, 5)) # rect is Rect2(-5, 0, 10, 5)
[/gdscript]
[csharp]
// position (-3, 2), size (1, 1)
var rect = new Rect2(new Vector2(-3, 2), new Vector2(1, 1));
// position (-3, -1), size (3, 4), so we fit both rect and Vector2(0, -1)
var rect2 = rect.Expand(new Vector2(0, -1));
var rect = new Rect2(0, 0, 5, 2);

rect = rect.Expand(new Vector2(10, 0)); // rect is Rect2(0, 0, 10, 2)
rect = rect.Expand(new Vector2(-5, 5)); // rect is Rect2(-5, 0, 10, 5)
[/csharp]
[/codeblocks]
</description>
</method>
<method name="get_area" qualifiers="const">
<return type="float" />
<description>
Returns the area of the [Rect2]. See also [method has_area].
Returns the rectangle's area. This is equivalent to [code]size.x * size.y[/code]. See also [method has_area].
</description>
</method>
<method name="get_center" qualifiers="const">
<return type="Vector2" />
<description>
Returns the center of the [Rect2], which is equal to [member position] + ([member size] / 2).
Returns the center point of the rectangle. This is the same as [code]position + (size / 2.0)[/code].
</description>
</method>
<method name="grow" qualifiers="const">
<return type="Rect2" />
<param index="0" name="amount" type="float" />
<description>
Returns a copy of the [Rect2] grown by the specified [param amount] on all sides.
Returns a copy of this rectangle extended on all sides by the given [param amount]. A negative [param amount] shrinks the rectangle instead. See also [method grow_individual] and [method grow_side].
[codeblocks]
[gdscript]
var a = Rect2(4, 4, 8, 8).grow(4) # a is Rect2(0, 0, 16, 16)
var b = Rect2(0, 0, 8, 4).grow(2) # b is Rect2(-2, -2, 12, 8)
[/gdscript]
[csharp]
var a = new Rect2(4, 4, 8, 8).Grow(4); // a is Rect2(0, 0, 16, 16)
var b = new Rect2(0, 0, 8, 4).Grow(2); // b is Rect2(-2, -2, 12, 8)
[/csharp]
[/codeblocks]
</description>
</method>
<method name="grow_individual" qualifiers="const">
Expand All @@ -116,87 +136,100 @@
<param index="2" name="right" type="float" />
<param index="3" name="bottom" type="float" />
<description>
Returns a copy of the [Rect2] grown by the specified amount on each side individually.
Returns a copy of this rectangle with its [param left], [param top], [param right], and [param bottom] sides extended by the given amounts. Negative values shrink the sides, instead. See also [method grow] and [method grow_side].
</description>
</method>
<method name="grow_side" qualifiers="const">
<return type="Rect2" />
<param index="0" name="side" type="int" />
<param index="1" name="amount" type="float" />
<description>
Returns a copy of the [Rect2] grown by the specified [param amount] on the specified [enum Side].
Returns a copy of this rectangle with its [param side] extended by the given [param amount] (see [enum Side] constants). A negative [param amount] shrinks the rectangle, instead. See also [method grow] and [method grow_individual].
</description>
</method>
<method name="has_area" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the [Rect2] has area, and [code]false[/code] if the [Rect2] is linear, empty, or has a negative [member size]. See also [method get_area].
Returns [code]true[/code] if this rectangle has positive width and height. See also [method get_area].
</description>
</method>
<method name="has_point" qualifiers="const">
<return type="bool" />
<param index="0" name="point" type="Vector2" />
<description>
Returns [code]true[/code] if the [Rect2] contains a point. By convention, the right and bottom edges of the [Rect2] are considered exclusive, so points on these edges are [b]not[/b] included.
[b]Note:[/b] This method is not reliable for [Rect2] with a [i]negative size[/i]. Use [method abs] to get a positive sized equivalent rectangle to check for contained points.
Returns [code]true[/code] if the rectangle contains the given [param point]. By convention, points on the right and bottom edges are [b]not[/b] included.
[b]Note:[/b] This method is not reliable for [Rect2] with a [i]negative[/i] [member size]. Use [method abs] first to get a valid rectangle.
</description>
</method>
<method name="intersection" qualifiers="const">
<return type="Rect2" />
<param index="0" name="b" type="Rect2" />
<description>
Returns the intersection of this [Rect2] and [param b].
If the rectangles do not intersect, an empty [Rect2] is returned.
Returns the intersection between this rectangle and [param b]. If the rectangles do not intersect, returns an empty [Rect2].
[codeblocks]
[gdscript]
var rect1 = Rect2(0, 0, 5, 10)
var rect2 = Rect2(2, 0, 8, 4)

var a = rect1.intersection(rect2) # a is Rect2(2, 0, 3, 4)
[/gdscript]
[csharp]
var rect1 = new Rect2(0, 0, 5, 10);
var rect2 = new Rect2(2, 0, 8, 4);

var a = rect1.Intersection(rect2); // a is Rect2(2, 0, 3, 4)
[/csharp]
[/codeblocks]
[b]Note:[/b] If you only need to know whether two rectangles are overlapping, use [method intersects], instead.
</description>
</method>
<method name="intersects" qualifiers="const">
<return type="bool" />
<param index="0" name="b" type="Rect2" />
<param index="1" name="include_borders" type="bool" default="false" />
<description>
Returns [code]true[/code] if the [Rect2] overlaps with [param b] (i.e. they have at least one point in common).
If [param include_borders] is [code]true[/code], they will also be considered overlapping if their borders touch, even without intersection.
Returns [code]true[/code] if this rectangle overlaps with the [param b] rectangle. The edges of both rectangles are excluded, unless [param include_borders] is [code]true[/code].
</description>
</method>
<method name="is_equal_approx" qualifiers="const">
<return type="bool" />
<param index="0" name="rect" type="Rect2" />
<description>
Returns [code]true[/code] if this [Rect2] and [param rect] are approximately equal, by calling [code]is_equal_approx[/code] on each component.
Returns [code]true[/code] if this rectangle and [param rect] are approximately equal, by calling [method Vector2.is_equal_approx] on the [member position] and the [member size].
</description>
</method>
<method name="is_finite" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this [Rect2] is finite, by calling [method @GlobalScope.is_finite] on each component.
Returns [code]true[/code] if this rectangle's values are finite, by calling [method Vector2.is_finite] on the [member position] and the [member size].
</description>
</method>
<method name="merge" qualifiers="const">
<return type="Rect2" />
<param index="0" name="b" type="Rect2" />
<description>
Returns a larger [Rect2] that contains this [Rect2] and [param b].
Returns a [Rect2] that encloses both this rectangle and [param b] around the edges. See also [method encloses].
</description>
</method>
</methods>
<members>
<member name="end" type="Vector2" setter="" getter="" default="Vector2(0, 0)">
Ending corner. This is calculated as [code]position + size[/code]. Setting this value will change the size.
The ending point. This is usually the bottom-right corner of the rectangle, and is equivalent to [code]position + size[/code]. Setting this point affects the [member size].
</member>
<member name="position" type="Vector2" setter="" getter="" default="Vector2(0, 0)">
Beginning corner. Typically has values lower than [member end].
The origin point. This is usually the top-left corner of the rectangle.
</member>
<member name="size" type="Vector2" setter="" getter="" default="Vector2(0, 0)">
Size from [member position] to [member end]. Typically, all components are positive.
If the size is negative, you can use [method abs] to fix it.
The rectangle's width and height, starting from [member position]. Setting this value also affects the [member end] point.
[b]Note:[/b] It's recommended setting the width and height to non-negative values, as most methods in Godot assume that the [member position] is the top-left corner, and the [member end] is the bottom-right corner. To get an equivalent rectangle with non-negative size, use [method abs].
</member>
</members>
<operators>
<operator name="operator !=">
<return type="bool" />
<param index="0" name="right" type="Rect2" />
<description>
Returns [code]true[/code] if the rectangles are not equal.
Returns [code]true[/code] if the [member position] or [member size] of both rectangles are not equal.
[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
</description>
</operator>
Expand All @@ -211,7 +244,7 @@
<return type="bool" />
<param index="0" name="right" type="Rect2" />
<description>
Returns [code]true[/code] if the rectangles are exactly equal.
Returns [code]true[/code] if both [member position] and [member size] of the rectangles are exactly equal, respectively.
[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
</description>
</operator>
Expand Down
Loading