Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Transform3D¶
代表 3D 变换的 3×4 矩阵。
描述¶
The Transform3D built-in Variant type is a 3×4 matrix representing a transformation in 3D space. It contains a Basis, which on its own can represent rotation, scale, and shear. Additionally, combined with its own origin, the transform can also represent a translation.
For a general introduction, see the Matrices and transforms tutorial.
Note: Godot uses a right-handed coordinate system, which is a common standard. For directions, the convention for built-in types like Camera3D is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the 3D asset direction conventions tutorial.
备注
通过 C# 使用该 API 时会有显著不同，详见 C# API 与 GDScript 的差异。
教程¶
属性¶
|
||
|
构造函数¶
Transform3D(from: Transform3D) |
|
Transform3D(basis: Basis, origin: Vector3) |
|
Transform3D(from: Projection) |
|
Transform3D(x_axis: Vector3, y_axis: Vector3, z_axis: Vector3, origin: Vector3) |
方法¶
affine_inverse() const |
|
interpolate_with(xform: Transform3D, weight: float) const |
|
inverse() const |
|
is_equal_approx(xform: Transform3D) const |
|
is_finite() const |
|
looking_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) const |
|
orthonormalized() const |
|
rotated_local(axis: Vector3, angle: float) const |
|
scaled_local(scale: Vector3) const |
|
translated(offset: Vector3) const |
|
translated_local(offset: Vector3) const |
运算符¶
operator !=(right: Transform3D) |
|
operator *(right: AABB) |
|
operator *(right: PackedVector3Array) |
|
operator *(right: Plane) |
|
operator *(right: Transform3D) |
|
operator *(right: Vector3) |
|
operator *(right: float) |
|
operator *(right: int) |
|
operator /(right: float) |
|
operator /(right: int) |
|
operator ==(right: Transform3D) |
常量¶
IDENTITY = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗
不含平移、旋转、缩放为 1 的变换。basis 等于 Basis.IDENTITY。
与 AABB、Transform3D 等其他 Variant 相乘时，不会进行任何变换。
FLIP_X = Transform3D(-1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗
应用了垂直于 YZ 平面镜像操作的 Transform3D。其 basis 相当于 Basis.FLIP_X。
FLIP_Y = Transform3D(1, 0, 0, 0, -1, 0, 0, 0, 1, 0, 0, 0) 🔗
应用了垂直于 XZ 平面镜像操作的 Transform3D。其 basis 相当于 Basis.FLIP_Y。
FLIP_Z = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, -1, 0, 0, 0) 🔗
应用了垂直于 XY 平面镜像操作的 Transform3D。其 basis 相当于 Basis.FLIP_Z。
属性说明¶
Basis basis = Basis(1, 0, 0, 0, 1, 0, 0, 0, 1) 🔗
该变换的 Basis。它由 3 个轴（Basis.x、Basis.y 和 Basis.z）组成。它们共同代表变换的旋转、缩放和错切。
Vector3 origin = Vector3(0, 0, 0) 🔗
该变换的平移偏移量。在 3D 空间中，这可以被看作是位置。
构造函数说明¶
Transform3D Transform3D() 🔗
构造与 IDENTITY 相同的 Transform3D。
Transform3D Transform3D(from: Transform3D)
构造给定 Transform3D 的副本 Transform3D。
Transform3D Transform3D(basis: Basis, origin: Vector3)
根据 Basis 和 Vector3 构造 Transform3D。
Transform3D Transform3D(from: Projection)
根据 Projection 构造 Transform3D。因为 Transform3D 是 3×4 的矩阵，而 Projection 是 4×4 的矩阵，所以这个操作会削去投影矩阵的最后一行（新的变换中不包含 from.x.w、from.y.w、from.z.w、from.w.w）。
Transform3D Transform3D(x_axis: Vector3, y_axis: Vector3, z_axis: Vector3, origin: Vector3)
根据四个 Vector3 值（也叫矩阵列）构造 Transform3D。
方法说明¶
Transform3D affine_inverse() const 🔗
返回该变换的逆版本。与 inverse 不同，则该方法几乎适用于任何 basis，包括非均匀的，但速度较慢。另见 Basis.inverse。
注意：为了使该方法正确返回，该变换的 basis 需要具有一个不完全是 0 的行列式（参见 Basis.determinant）。
Transform3D interpolate_with(xform: Transform3D, weight: float) const 🔗
返回将该变换和 xform 按照给定的权重 weight 进行线性插值结果。
weight 应该在 0.0 到 1.0（闭区间）的范围内。允许使用超出这个范围的值，表示进行外插。
Transform3D inverse() const 🔗
返回该变换的逆版本。另见 Basis.inverse。
注意：为了使该方法正确返回，该变换的 basis 需要是正交归一化的（请参阅 Basis.orthonormalized）。这意味着，该基应该只代表旋转。如果没有，请改用 affine_inverse。
bool is_equal_approx(xform: Transform3D) const 🔗
如果通过在每个分量上运行 @GlobalScope.is_equal_approx，该变换和 xform 近似相等，则返回 true。
如果该变换是有限的，则返回 true，判断方法是在每个分量上调用 @GlobalScope.is_finite。
Transform3D looking_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) const 🔗
返回该变换的旋转副本，以便向前轴（-Z）指向 target 的位置。
向上的轴（+Y）在保持与向前的轴垂直的前提下，尽可能接近 up 向量。最终的变换是标准正交变换。变换中原有的旋转、缩放、偏斜信息会被丢弃。target 和 up 向量不能为零，不能互相平行，使用全局/父级空间。
如果 use_model_front 为 true，则会将 +Z 轴（资产正面）作为向前的轴（此时 +X 为左），指向 target 的位置。默认情况下会将 -Z 轴（相机前方）作为向前的轴（此时 +X 为右）。
Transform3D orthonormalized() const 🔗
返回该变换的副本，其 basis 已正交归一化。正交归一化的基既是正交的（轴彼此垂直）又是归一化的（轴长度为 1），这也意味着它只能代表旋转。另见 Basis.orthonormalized。
Transform3D rotated(axis: Vector3, angle: float) const 🔗
返回该变换围绕给定 axis 旋转给定 angle（单位为弧度）的副本。
axis 必须为归一化的向量。
这个方法的结果和让 X 变换与相应的旋转变换 R 从左侧相乘一致，即 R * X，但进行了优化。
可以视作在全局/父级坐标系中的变换。
Transform3D rotated_local(axis: Vector3, angle: float) const 🔗
返回该变换围绕给定 axis 旋转给定 angle（单位为弧度）的副本。
axis 必须为归一化的向量。
这个方法的结果和让 X 变换与相应的旋转变换 R 从右侧相乘一致，即 R * X，但进行了优化。
可以视作在局部坐标系中的变换。
Transform3D scaled(scale: Vector3) const 🔗
返回该变换按给定的 scale 系数缩放的副本。
这个方法的结果和让 X 变换与相应的缩放变换 S 从左侧相乘一致，即 S * X，但进行了优化。
可以视作在全局/父级坐标系中的变换。
Transform3D scaled_local(scale: Vector3) const 🔗
返回该变换按给定的 scale 系数缩放的副本。
这个方法的结果和让 X 变换与相应的缩放变换 S 从右侧相乘一致，即 X * S，但进行了优化。
可以视作在局部坐标系中的变换。
Transform3D translated(offset: Vector3) const 🔗
返回该变换平移了给定 offset 的副本。
这个方法的结果和让 X 变换与相应的平移变换 T 从左侧相乘一致，即 T * X，但进行了优化。
可以视作在全局/父级坐标系中的变换。
Transform3D translated_local(offset: Vector3) const 🔗
返回该变化平移了给定 offset 的副本。
这个方法的结果和让 X 变换与相应的平移变换 T 从右侧相乘一致，即 X * T，但进行了优化。
可以视作在局部坐标系中的变换。
运算符说明¶
bool operator !=(right: Transform3D) 🔗
如果两个变换的分量不相等，则返回 true。
注意：由于浮点精度误差，请考虑改用 is_equal_approx，这样更可靠。
AABB operator *(right: AABB) 🔗
使用该变换矩阵对 AABB 进行变换（相乘）。
PackedVector3Array operator *(right: PackedVector3Array) 🔗
由该变换矩阵变换（乘以）给定 PackedVector3Array 的每个 Vector3 元素。
在较大的数组上，该操作比单独变换每个 Vector3 要快得多。
Plane operator *(right: Plane) 🔗
使用该变换矩阵对 Plane 进行变换（相乘）。
Transform3D operator *(right: Transform3D) 🔗
由 right 变换来变换（乘以）该变换。
这是父级和子级 Node3D 之间执行的操作。
注意：如果你只需要修改该变换的一个属性，请考虑改用以下方法之一：
对于平移，请参阅 translated 或 translated_local。
对于旋转，请参阅 rotated 或 rotated_local。
对于缩放，请参阅 scaled 或 scaled_local。
Vector3 operator *(right: Vector3) 🔗
使用该变换矩阵对 Vector3 进行变换（相乘）。
Transform3D operator *(right: float) 🔗
将 Transform3D 包括 origin 在内的所有分量乘以给定的 float。会均匀地影响该变换的缩放，对 basis 进行缩放。
Transform3D operator *(right: int) 🔗
将 Transform3D 包括 origin 在内的所有分量乘以给定的 int。会均匀地影响该变换的缩放，对 basis 进行缩放。
Transform3D operator /(right: float) 🔗
将 Transform3D 包括 origin 在内的所有分量除以给定的 float。会均匀地影响该变换的缩放，对 basis 进行缩放。
Transform3D operator /(right: int) 🔗
将 Transform3D 包括 origin 在内的所有分量除以给定的 int。会均匀地影响该变换的缩放，对 basis 进行缩放。
bool operator ==(right: Transform3D) 🔗
如果两个变换的分量完全相等，则返回 true。
注意：由于浮点精度误差，请考虑改用 is_equal_approx，这样更可靠。