Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
AABB¶
3D 轴对齐边界框。
描述¶
AABB 内置 Variant 类型表示 3D 空间中的轴对齐边界框。它由其 position 和 size 定义,皆为 Vector3 类型。它经常被用于快速重叠测试(参见 intersects)。虽然 AABB 本身是轴对齐的,但它可以与 Transform3D 组合来表示旋转或倾斜的边界框。
它使用浮点坐标。AABB 的 2D 等效体是 Rect2。没有使用整数坐标的 AABB 版本。
注意:不支持负的 size。对于负大小,大多数 AABB 方法都无法正常工作。使用 abs 获取具有非负大小的等效 AABB。
注意:在布尔上下文中,如果 position 和 size 均为零(等于 Vector3.ZERO),则 AABB 的计算结果为 false
。否则,它的计算结果始终为 true
。
备注
通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异。
教程¶
属性¶
|
||
|
||
|
构造函数¶
AABB ( ) |
|
方法¶
abs ( ) const |
|
get_center ( ) const |
|
get_endpoint ( int idx ) const |
|
get_longest_axis ( ) const |
|
get_longest_axis_index ( ) const |
|
get_longest_axis_size ( ) const |
|
get_shortest_axis ( ) const |
|
get_shortest_axis_index ( ) const |
|
get_shortest_axis_size ( ) const |
|
get_support ( Vector3 dir ) const |
|
get_volume ( ) const |
|
has_surface ( ) const |
|
has_volume ( ) const |
|
intersection ( AABB with ) const |
|
intersects ( AABB with ) const |
|
intersects_plane ( Plane plane ) const |
|
intersects_ray ( Vector3 from, Vector3 dir ) const |
|
intersects_segment ( Vector3 from, Vector3 to ) const |
|
is_equal_approx ( AABB aabb ) const |
|
is_finite ( ) const |
|
操作符¶
operator != ( AABB right ) |
|
operator * ( Transform3D right ) |
|
operator == ( AABB right ) |
属性说明¶
Vector3 end = Vector3(0, 0, 0)
终点。通常是边界框的前方右上角,等价于 position + size
。设置该点会影响 size。
Vector3 position = Vector3(0, 0, 0)
原点。通常是边界框的背面左下角。
Vector3 size = Vector3(0, 0, 0)
边界框的宽度、高度、深度,相对于 position。设置该值会影响终点 end。
注意:建议将宽度、高度、深度设置为非负数,因为 Godot 中的大多数方法假设 position 为背面的左下角、end 为正面的右上角。要获取等价且大小非负的边界框,请使用 abs。
构造函数说明¶
AABB AABB ( )
构造 AABB,并将 position 和 size 设置为 Vector3.ZERO。
构造给定 AABB 的副本。
AABB AABB ( Vector3 position, Vector3 size )
使用指定的 position
和 size
构造 AABB。
方法说明¶
AABB abs ( ) const
返回一个与该边界框等效的 AABB,其宽度、高度和深度被修改为非负值。
var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5))
var absolute = box.abs()
print(absolute.position) # 打印 (-15, -10, 0)
print(absolute.size) # 打印 (20, 10, 5)
var box = new Aabb(new Vector3(5, 0, 5), new Vector3(-20, -10, -5));
var absolute = box.Abs();
GD.Print(absolute.Position); // 打印 (-15, -10, 0)
GD.Print(absolute.Size); // 打印 (20, 10, 5)
注意:当 size 为负时,建议使用该方法,因为 Godot 中的大多数其他方法都假设 size 的分量大于 0
。
bool encloses ( AABB with ) const
如果该边界框完全包围 with
框,则返回 true
。两个框的边都包括在内。
var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4))
var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3))
var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8))
print(a.encloses(a)) # 打印 true
print(a.encloses(b)) # 打印 true
print(a.encloses(c)) # 打印 false
var a = new Aabb(new Vector3(0, 0, 0), new Vector3(4, 4, 4));
var b = new Aabb(new Vector3(1, 1, 1), new Vector3(3, 3, 3));
var c = new Aabb(new Vector3(2, 2, 2), new Vector3(8, 8, 8));
GD.Print(a.Encloses(a)); // 打印 True
GD.Print(a.Encloses(b)); // 打印 True
GD.Print(a.Encloses(c)); // 打印 False
AABB expand ( Vector3 to_point ) const
返回该边界框的副本,如有必要,该边界框被扩展为将边与给定的 to_point
对齐。
var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5))
box = box.expand(Vector3(10, 0, 0))
print(box.position) # 打印 (0, 0, 0)
print(box.size) # 打印 (10, 2, 5)
box = box.expand(Vector3(-5, 0, 5))
print(box.position) # 打印 (-5, 0, 0)
print(box.size) # 打印 (15, 2, 5)
var box = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 5));
box = box.Expand(new Vector3(10, 0, 0));
GD.Print(box.Position); // 打印 (0, 0, 0)
GD.Print(box.Size); // 打印 (10, 2, 5)
box = box.Expand(new Vector3(-5, 0, 5));
GD.Print(box.Position); // 打印 (-5, 0, 0)
GD.Print(box.Size); // 打印 (15, 2, 5)
Vector3 get_center ( ) const
返回该边界框的中心点。这与 position + (size / 2.0)
相同。
Vector3 get_endpoint ( int idx ) const
返回组成该边界框的 8 个顶点之一的位置。当 idx
为 0
时,这与 position 相同;idx
为 7
时,与 end 相同。
Vector3 get_longest_axis ( ) const
返回该边界框的 size 的最长归一化轴,作为 Vector3(Vector3.RIGHT、Vector3.UP 或 Vector3.BACK)。
var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
print(box.get_longest_axis()) # 打印 (0, 0, 1)
print(box.get_longest_axis_index()) # 打印 2
print(box.get_longest_axis_size()) # 打印 8
var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8));
GD.Print(box.GetLongestAxis()); // 打印 (0, 0, 1)
GD.Print(box.GetLongestAxisIndex()); // 打印 2
GD.Print(box.GetLongestAxisSize()); // 打印 8
另见 get_longest_axis_index 和 get_longest_axis_size。
int get_longest_axis_index ( ) const
返回该边界框的 size 的最长轴的索引(请参阅 Vector3.AXIS_X、Vector3.AXIS_Y、和 Vector3.AXIS_Z)。
有关示例,请参阅 get_longest_axis。
float get_longest_axis_size ( ) const
返回该边界框的 size 的最长尺度。
有关示例,请参阅 get_longest_axis。
Vector3 get_shortest_axis ( ) const
返回该边界框的 size 的最短归一化轴,作为 Vector3(Vector3.RIGHT、Vector3.UP、或 Vector3.BACK)。
var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
print(box.get_shortest_axis()) # 打印 (1, 0, 0)
print(box.get_shortest_axis_index()) # 打印 0
print(box.get_shortest_axis_size()) # 打印 2
var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8));
GD.Print(box.GetShortestAxis()); // 打印 (1, 0, 0)
GD.Print(box.GetShortestAxisIndex()); // 打印 0
GD.Print(box.GetShortestAxisSize()); // 打印 2
另见 get_shortest_axis_index 和 get_shortest_axis_size。
int get_shortest_axis_index ( ) const
返回该边界框的 size 的最短轴的索引(请参阅 Vector3.AXIS_X、Vector3.AXIS_Y、和 Vector3.AXIS_Z)。
有关示例,请参阅 get_shortest_axis。
float get_shortest_axis_size ( ) const
返回该边界框的 size 的最短尺度。
有关示例,请参阅 get_shortest_axis。
Vector3 get_support ( Vector3 dir ) const
返回给定方向上最远的边界框的顶点位置。该点在碰撞检测算法中通常被称为支撑点。
float get_volume ( ) const
返回该边界框的体积。这相当于 size.x * size.y * size.z
。另请参阅 has_volume。
返回该边界框的副本,该边界框在所有边上扩展给定量 by
。负数会缩小该框。
var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4)
print(a.position) # 打印 (0, 0, 0)
print(a.size) # 打印 (16, 16, 16)
var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2)
print(b.position) # 打印 (-2, -2, -2)
print(b.size) # 打印 (12, 8, 6)
var a = new Aabb(new Vector3(4, 4, 4), new Vector3(8, 8, 8)).Grow(4);
GD.Print(a.Position); // 打印 (0, 0, 0)
GD.Print(a.Size); // 打印 (16, 16, 16)
var b = new Aabb(new Vector3(0, 0, 0), new Vector3(8, 4, 2)).Grow(2);
GD.Print(b.Position); // 打印 (-2, -2, -2)
GD.Print(b.Size); // 打印 (12, 8, 6)
bool has_point ( Vector3 point ) const
如果该边界框包含给定的 point
,则返回 true
。依照惯例,不包括正好位于右侧、顶部和前侧的点。
注意:对于具有负 size 的 AABB,该方法并不可靠。请首先使用 abs 获取一个有效的边界框。
bool has_surface ( ) const
如果该边界框具有表面或长度,即 size 的至少一个分量大于 0
,则返回 true
。否则,返回 false
。
bool has_volume ( ) const
如果该边界框的宽度、高度和深度均为正值,则返回 true
。另见 get_volume。
AABB intersection ( AABB with ) const
返回该边界框与 with
之间的交集。如果框不相交,则返回空的 AABB。如果框在边相交,则返回没有体积的平 AABB(请参阅 has_surface 和 has_volume)。
var box1 = AABB(Vector3(0, 0, 0), Vector3(5, 2, 8))
var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4))
var intersection = box1.intersection(box2)
print(intersection.position) # 打印 (2, 0, 2)
print(intersection.size) # 打印 (3, 2, 4)
var box1 = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 8));
var box2 = new Aabb(new Vector3(2, 0, 2), new Vector3(8, 4, 4));
var intersection = box1.Intersection(box2);
GD.Print(intersection.Position); // 打印 (2, 0, 2)
GD.Print(intersection.Size); // 打印 (3, 2, 4)
注意:如果你只需要知道两个边界框是否相交,请改用 intersects。
bool intersects ( AABB with ) const
如果该边界框与框 with
重叠,则返回 true
。两个框的边总是被排除。
bool intersects_plane ( Plane plane ) const
如果该边界框位于给定 plane
的两侧,则返回 true
。
Variant intersects_ray ( Vector3 from, Vector3 dir ) const
返回该边界框与给定射线相交的第一个点,作为 Vector3。如果没有交集存在,则返回 null
。
射线从 from
开始,面向 dir
并向无穷远延伸。
Variant intersects_segment ( Vector3 from, Vector3 to ) const
返回该边界框与给定线段相交的第一个点,作为 Vector3。如果没有交集存在,则返回 null
。
该线段从 from
开始,到 to
结束。
bool is_equal_approx ( AABB aabb ) const
如果该边界框和 aabb
近似相等,则返回 true
,判断方法是通过在 position 和 size 上调用 Vector3.is_equal_approx。
bool is_finite ( ) const
如果该边界框的值是有限的,则返回 true
,判断方法是通过在 position 和 size 上调用 Vector3.is_finite。
AABB merge ( AABB with ) const
返回边界包围该边界框和 with
的 AABB。另见 encloses。
操作符说明¶
bool operator != ( AABB right )
如果两个边界框的 position 不相等或 size 不相等,则返回 true
。
注意:由于浮点数精度误差,请考虑改用 is_equal_approx,会更可靠。
AABB operator * ( Transform3D right )
假设该变换的基是正交的(即旋转/反射可以,缩放/倾斜则不行),将 AABB 逆向变换(乘以)给定的 Transform3D 变换矩阵。
aabb * transform
相当于 transform.inverse() * aabb
。见 Transform3D.inverse。
对于通过仿射变换的逆进行的变换(例如,缩放),可以使用 transform.affine_inverse() * aabb
代替。见 Transform3D.affine_inverse。
bool operator == ( AABB right )
如果两个边界框的 position 完全相等且 size 完全相等,则返回 true
。
注意:由于浮点数精度误差,请考虑改用 is_equal_approx,会更可靠。