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.

Transform2D

代表 2D 变换的 2×3 矩阵。

描述

The Transform2D built-in Variant type is a 2×3 matrix representing a transformation in 2D space. It contains three Vector2 values: x, y, and origin. Together, they can represent translation, rotation, scale, and skew.

The x and y axes form a 2×2 matrix, known as the transform's basis. The length of each axis (Vector2.length) influences the transform's scale, while the direction of all axes influence the rotation. Usually, both axes are perpendicular to one another. However, when you rotate one axis individually, the transform becomes skewed. Applying a skewed transform to a 2D sprite will make the sprite appear distorted.

For a general introduction, see the Matrices and transforms tutorial.

Note: Unlike Transform3D, there is no 2D equivalent to the Basis type. All mentions of "basis" refer to the x and y components of Transform2D.

备注

通过 C# 使用该 API 时会有显著不同,详见 C# API 与 GDScript 的差异

教程

属性

Vector2

origin

Vector2(0, 0)

Vector2

x

Vector2(1, 0)

Vector2

y

Vector2(0, 1)

构造函数

Transform2D

Transform2D()

Transform2D

Transform2D(from: Transform2D)

Transform2D

Transform2D(rotation: float, position: Vector2)

Transform2D

Transform2D(rotation: float, scale: Vector2, skew: float, position: Vector2)

Transform2D

Transform2D(x_axis: Vector2, y_axis: Vector2, origin: Vector2)

方法

Transform2D

affine_inverse() const

Vector2

basis_xform(v: Vector2) const

Vector2

basis_xform_inv(v: Vector2) const

float

determinant() const

Vector2

get_origin() const

float

get_rotation() const

Vector2

get_scale() const

float

get_skew() const

Transform2D

interpolate_with(xform: Transform2D, weight: float) const

Transform2D

inverse() const

bool

is_conformal() const

bool

is_equal_approx(xform: Transform2D) const

bool

is_finite() const

Transform2D

looking_at(target: Vector2 = Vector2(0, 0)) const

Transform2D

orthonormalized() const

Transform2D

rotated(angle: float) const

Transform2D

rotated_local(angle: float) const

Transform2D

scaled(scale: Vector2) const

Transform2D

scaled_local(scale: Vector2) const

Transform2D

translated(offset: Vector2) const

Transform2D

translated_local(offset: Vector2) const

运算符

bool

operator !=(right: Transform2D)

PackedVector2Array

operator *(right: PackedVector2Array)

Rect2

operator *(right: Rect2)

Transform2D

operator *(right: Transform2D)

Vector2

operator *(right: Vector2)

Transform2D

operator *(right: float)

Transform2D

operator *(right: int)

Transform2D

operator /(right: float)

Transform2D

operator /(right: int)

bool

operator ==(right: Transform2D)

Vector2

operator [](index: int)


常量

IDENTITY = Transform2D(1, 0, 0, 1, 0, 0) 🔗

The identity Transform2D. A transform with no translation, no rotation, and its scale being 1. When multiplied by another Variant such as Rect2 or another Transform2D, no transformation occurs. This means that:

var transform = Transform2D.IDENTITY
print("| X | Y | Origin")
print("| %s | %s | %s" % [transform.x.x, transform.y.x, transform.origin.x])
print("| %s | %s | %s" % [transform.x.y, transform.y.y, transform.origin.y])
# Prints:
# | X | Y | Origin
# | 1 | 0 | 0
# | 0 | 1 | 0

This is identical to creating Transform2D without any parameters. This constant can be used to make your code clearer, and for consistency with C#.

FLIP_X = Transform2D(-1, 0, 0, 1, 0, 0) 🔗

When any transform is multiplied by FLIP_X, it negates all components of the x axis (the X column).

When FLIP_X is multiplied by any basis, it negates the Vector2.x component of all axes (the X row).

FLIP_Y = Transform2D(1, 0, 0, -1, 0, 0) 🔗

When any transform is multiplied by FLIP_Y, it negates all components of the y axis (the Y column).

When FLIP_Y is multiplied by any basis, it negates the Vector2.y component of all axes (the Y row).


属性说明

Vector2 origin = Vector2(0, 0) 🔗

The translation offset of this transform, and the column 2 of the matrix. In 2D space, this can be seen as the position.


Vector2 x = Vector2(1, 0) 🔗

The transform basis's X axis, and the column 0 of the matrix. Combined with y, this represents the transform's rotation, scale, and skew.

On the identity transform, this vector points right (Vector2.RIGHT).


Vector2 y = Vector2(0, 1) 🔗

The transform basis's Y axis, and the column 1 of the matrix. Combined with x, this represents the transform's rotation, scale, and skew.

On the identity transform, this vector points up (Vector2.UP).


构造函数说明

Transform2D Transform2D() 🔗

Constructs a Transform2D identical to IDENTITY.


Transform2D Transform2D(from: Transform2D)

构造给定 Transform2D 的副本。


Transform2D Transform2D(rotation: float, position: Vector2)

Constructs a Transform2D from a given angle (in radians) and position.


Transform2D Transform2D(rotation: float, scale: Vector2, skew: float, position: Vector2)

Constructs a Transform2D from a given angle (in radians), scale, skew (in radians), and position.


Transform2D Transform2D(x_axis: Vector2, y_axis: Vector2, origin: Vector2)

Constructs a Transform2D from 3 Vector2 values representing x, y, and the origin (the three matrix columns).


方法说明

Transform2D affine_inverse() const 🔗

Returns the inverted version of this transform. Unlike inverse, this method works with almost any basis, including non-uniform ones, but is slower. See also inverse.

Note: For this method to return correctly, the transform's basis needs to have a determinant that is not exactly 0 (see determinant).


Vector2 basis_xform(v: Vector2) const 🔗

Returns a copy of the v vector, transformed (multiplied) by the transform basis's matrix. Unlike the multiplication operator (*), this method ignores the origin.


Vector2 basis_xform_inv(v: Vector2) const 🔗

Returns a copy of the v vector, transformed (multiplied) by the inverse transform basis's matrix (see inverse). This method ignores the origin.

Note: This method assumes that this transform's basis is orthonormal (see orthonormalized). If the basis is not orthonormal, transform.affine_inverse().basis_xform(vector) should be used instead (see affine_inverse).


float determinant() const 🔗

Returns the determinant of this transform basis's matrix. For advanced math, this number can be used to determine a few attributes:

  • If the determinant is exactly 0, the basis is not invertible (see inverse).

  • If the determinant is a negative number, the basis represents a negative scale.

Note: If the basis's scale is the same for every axis, its determinant is always that scale by the power of 2.


Vector2 get_origin() const 🔗

Returns this transform's translation. Equivalent to origin.


float get_rotation() const 🔗

Returns this transform's rotation (in radians). This is equivalent to x's angle (see Vector2.angle).


Vector2 get_scale() const 🔗

Returns the length of both x and y, as a Vector2. If this transform's basis is not skewed, this value is the scaling factor. It is not affected by rotation.

var my_transform = Transform2D(
    Vector2(2, 0),
    Vector2(0, 4),
    Vector2(0, 0)
)
# Rotating the Transform2D in any way preserves its scale.
my_transform = my_transform.rotated(TAU / 2)

print(my_transform.get_scale()) # Prints (2, 4).

Note: If the value returned by determinant is negative, the scale is also negative.


float get_skew() const 🔗

Returns this transform's skew (in radians).


Transform2D interpolate_with(xform: Transform2D, weight: float) const 🔗

返回将该变换和 xform 按照给定的权重 weight 进行线性插值结果。

weight 应该在 0.01.0(闭区间)的范围内。允许使用超出这个范围的值,表示进行外插


Transform2D inverse() const 🔗

Returns the inverted version of this transform.

Note: For this method to return correctly, the transform's basis needs to be orthonormal (see orthonormalized). That means, the basis should only represent a rotation. If it does not, use affine_inverse instead.


bool is_conformal() const 🔗

Returns true if this transform's basis is conformal. A conformal basis is both orthogonal (the axes are perpendicular to each other) and uniform (the axes share the same length). This method can be especially useful during physics calculations.


bool is_equal_approx(xform: Transform2D) const 🔗

如果通过在每个分量上运行 @GlobalScope.is_equal_approx,该变换和 xform 近似相等,则返回 true


bool is_finite() const 🔗

如果该变换是有限的,则返回 true,判断方法是在每个分量上调用 @GlobalScope.is_finite


Transform2D looking_at(target: Vector2 = Vector2(0, 0)) const 🔗

Returns a copy of the transform rotated such that the rotated X-axis points towards the target position, in global space.


Transform2D orthonormalized() const 🔗

Returns a copy of this transform with its basis orthonormalized. An orthonormal basis is both orthogonal (the axes are perpendicular to each other) and normalized (the axes have a length of 1), which also means it can only represent rotation.


Transform2D rotated(angle: float) const 🔗

返回该变换的副本,该副本进行了夹角为 angle 的旋转操作(单位为弧度)。

这个方法的结果和让 X 变换与相应的旋转变换 R 从左侧相乘一致,即 R * X,但进行了优化。

可以视作在全局/父级坐标系中的变换。


Transform2D rotated_local(angle: float) const 🔗

返回该变换的副本,该副本进行了夹角为 angle 的旋转操作(单位为弧度)。

这个方法的结果和让 X 变换与相应的旋转变换 R 从右侧相乘一致,即 X * R,但进行了优化。

可以视作在局部坐标系中的变换。


Transform2D scaled(scale: Vector2) const 🔗

返回该变换的副本,该副本进行了系数为 scale 的缩放操作。

这个方法的结果和让 X 变换与相应的缩放变换 S 从左侧相乘一致,即 S * X,但进行了优化。

可以视作在全局/父级坐标系中的变换。


Transform2D scaled_local(scale: Vector2) const 🔗

返回该变换的副本,该副本进行了系数为 scale 的缩放操作。

这个方法的结果和让 X 变换与相应的缩放变换 S 从右侧相乘一致,即 X * S,但进行了优化。

可以视作在局部坐标系中的变换。


Transform2D translated(offset: Vector2) const 🔗

返回该变换的副本,该副本进行了偏移量为 offset 的平移操作。

这个方法的结果和让 X 变换与相应的平移变换 T 从左侧相乘一致,即 T * X,但进行了优化。

可以视作在全局/父级坐标系中的变换。


Transform2D translated_local(offset: Vector2) const 🔗

返回该变换的副本,该副本进行了偏移量为 offset 的平移操作。

这个方法的结果和让