Class Transform2D

A 2×3 matrix representing a 2D transformation.

Transform2D

Remarks

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 (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.

Constructors

Transform2D

Constructs a Transform2D identical to IDENTITY.

Note: In C#, this constructs a Transform2D with all of its components set to ZERO.

Transform2D Transform2D

Transform2D(Transform2D)

Constructs a Transform2D as a copy of the given Transform2D.

Transform2D Transform2D(Transform2D from)

Parameters

from Transform2D

Transform2D(float, Vector2)

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

Transform2D Transform2D(float rotation, Vector2 position)

Parameters

rotation float
position Vector2

Transform2D(float, Vector2, float, Vector2)

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

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

Parameters

rotation float
scale Vector2
skew float
position Vector2

Transform2D(Vector2, Vector2, Vector2)

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

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

Parameters

x_axis Vector2
y_axis Vector2
origin Vector2

Fields

IDENTITY

The identity Transform2D. This is a transform with no translation, no rotation, and a scale of ONE. This also means that:

The x points right (RIGHT);
The y points down (DOWN).

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

If a Vector2, a Rect2, a PackedVector2Array, or another Transform2D is transformed (multiplied) by this constant, no transformation occurs.

Note: In GDScript, this constant is equivalent to creating a Transform2D without any arguments. It can be used to make your code clearer, and for consistency with C#.

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

FLIP_X

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 transform, it negates the x component of all axes (the X row).

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

FLIP_Y

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 transform, it negates the y component of all axes (the Y row).

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

Properties

origin

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

var origin : Vector2 = Vector2(0, 0)

Property Value

Vector2

x

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 (RIGHT).

var x : Vector2 = Vector2(1, 0)

Property Value

Vector2

y

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 down (DOWN).

var y : Vector2 = Vector2(0, 1)

Property Value

Vector2

Methods

affine_inverse

Qualifiers: const

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

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

Transform2D affine_inverse

basis_xform(Vector2)

Qualifiers: 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(Vector2 v)

Parameters

v Vector2

basis_xform_inv(Vector2)

Qualifiers: 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).

Vector2 basis_xform_inv(Vector2 v)

Parameters

v Vector2

determinant

Qualifiers: 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.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.

float determinant

get_origin

Qualifiers: const

Returns this transform's translation. Equivalent to origin.

Vector2 get_origin

get_rotation

Qualifiers: const

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

float get_rotation

get_scale

Qualifiers: 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.

gdscript
C#

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.0, 4.0)

var myTransform = new Transform2D(
    Vector3(2.0f, 0.0f),
    Vector3(0.0f, 4.0f),
    Vector3(0.0f, 0.0f)
);
// Rotating the Transform2D in any way preserves its scale.
myTransform = myTransform.Rotated(Mathf.Tau / 2.0f);

GD.Print(myTransform.GetScale()); // Prints (2, 4)

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

Vector2 get_scale

get_skew

Qualifiers: const

Returns this transform's skew (in radians).

float get_skew

interpolate_with(Transform2D, float)

Qualifiers: const

Returns the result of the linear interpolation between this transform and xform by the given weight.

The weight should be between 0.0 and 1.0 (inclusive). Values outside this range are allowed and can be used to perform extrapolation instead.

Transform2D interpolate_with(Transform2D xform, float weight)

Parameters

xform Transform2D
weight float

inverse

Qualifiers: 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.

Transform2D inverse

is_conformal

Qualifiers: 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_conformal

is_equal_approx(Transform2D)

Qualifiers: const

Returns true if this transform and xform are approximately equal, by running @GlobalScope.is_equal_approx on each component.

bool is_equal_approx(Transform2D xform)

Parameters

xform Transform2D

is_finite

Qualifiers: const

Returns true if this transform is finite, by calling @GlobalScope.is_finite on each component.

bool is_finite

looking_at(Vector2)

Qualifiers: const

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

Transform2D looking_at(Vector2 target)

Parameters

target Vector2

orthonormalized

Qualifiers: 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.0), which also means it can only represent a rotation.

Transform2D orthonormalized

rotated(float)

Qualifiers: const

Returns a copy of this transform rotated by the given angle (in radians).

If angle is positive, the transform is rotated clockwise.

This method is an optimized version of multiplying the given transform X with a corresponding rotation transform R from the left, i.e., R * X.

This can be seen as transforming with respect to the global/parent frame.

Transform2D rotated(float angle)

Parameters

angle float

rotated_local(float)

Qualifiers: const

Returns a copy of the transform rotated by the given angle (in radians).

This method is an optimized version of multiplying the given transform X with a corresponding rotation transform R from the right, i.e., X * R.

This can be seen as transforming with respect to the local frame.

Transform2D rotated_local(float angle)

Parameters

angle float

scaled(Vector2)

Qualifiers: const

Returns a copy of the transform scaled by the given scale factor.

This method is an optimized version of multiplying the given transform X with a corresponding scaling transform S from the left, i.e., S * X.

This can be seen as transforming with respect to the global/parent frame.

Transform2D scaled(Vector2 scale)

Parameters

scale Vector2

scaled_local(Vector2)

Qualifiers: const

Returns a copy of the transform scaled by the given scale factor.

This method is an optimized version of multiplying the given transform X with a corresponding scaling transform S from the right, i.e., X * S.

This can be seen as transforming with respect to the local frame.

Transform2D scaled_local(Vector2 scale)

Parameters

scale Vector2

translated(Vector2)

Qualifiers: const

Returns a copy of the transform translated by the given offset.

This method is an optimized version of multiplying the given transform X with a corresponding translation transform T from the left, i.e., T * X.

This can be seen as transforming with respect to the global/parent frame.

Transform2D translated(Vector2 offset)

Parameters

offset Vector2

translated_local(Vector2)

Qualifiers: const

Returns a copy of the transform translated by the given offset.

This method is an optimized version of multiplying the given transform X with a corresponding translation transform T from the right, i.e., X * T.

This can be seen as transforming with respect to the local frame.

Transform2D translated_local(Vector2 offset)

Parameters

offset Vector2

Operators

!= (Transform2D)

Returns true if the components of both transforms are not equal.

Note: Due to floating-point precision errors, consider using Transform2D.is_equal_approx instead, which is more reliable.

bool != (Transform2D right)

Parameters

right Transform2D

* (PackedVector2Array)

Transforms (multiplies) every Vector2 element of the given PackedVector2Array by this transformation matrix.

On larger arrays, this operation is much faster than transforming each Vector2 individually.

PackedVector2Array * (PackedVector2Array right)

Parameters

right PackedVector2Array

* (Rect2)

Transforms (multiplies) the Rect2 by this transformation matrix.

Rect2 * (Rect2 right)

Parameters

right Rect2

* (Transform2D)

Transforms (multiplies) this transform by the right transform.

This is the operation performed between parent and child CanvasItem nodes.

Note: If you need to only modify one attribute of this transform, consider using one of the following methods, instead:

For translation, see Transform2D.translated or Transform2D.translated_local.
For rotation, see Transform2D.rotated or Transform2D.rotated_local.
For scale, see Transform2D.scaled or Transform2D.scaled_local.

Transform2D * (Transform2D right)

Parameters

right Transform2D

* (Vector2)

Transforms (multiplies) the Vector2 by this transformation matrix.

Vector2 * (Vector2 right)

Parameters

right Vector2

* (float)

Multiplies all components of the Transform2D by the given float, including the origin. This affects the transform's scale uniformly.

Transform2D * (float right)

Parameters

right float

* (int)

Multiplies all components of the Transform2D by the given int, including the origin. This affects the transform's scale uniformly.

Transform2D * (int right)

Parameters

right int

/ (float)

Divides all components of the Transform2D by the given float, including the origin. This affects the transform's scale uniformly.

Transform2D / (float right)

Parameters

right float

/ (int)

Divides all components of the Transform2D by the given int, including the origin. This affects the transform's scale uniformly.

Transform2D / (int right)

Parameters

right int

== (Transform2D)

Returns true if the components of both transforms are exactly equal.

Note: Due to floating-point precision errors, consider using Transform2D.is_equal_approx instead, which is more reliable.

bool == (Transform2D right)

Parameters

right Transform2D

[] (int)

Accesses each axis (column) of this transform by their index. Index 0 is the same as x, index 1 is the same as y, and index 2 is the same as origin.

Vector2 [] (int index)

Parameters

index int

Table of Contents

Class Transform2D

Remarks

See Also

Constructors

Transform2D

Transform2D(Transform2D)

Parameters

Transform2D(float, Vector2)

Parameters

Transform2D(float, Vector2, float, Vector2)

Parameters

Transform2D(Vector2, Vector2, Vector2)

Parameters

Fields

IDENTITY

FLIP_X

FLIP_Y

Properties

origin

Property Value

x

Property Value

y

Property Value

Methods

affine_inverse

basis_xform(Vector2)

Parameters

basis_xform_inv(Vector2)

Parameters

determinant

get_origin

get_rotation

get_scale

get_skew

interpolate_with(Transform2D, float)

Parameters

inverse

is_conformal

is_equal_approx(Transform2D)

Parameters

is_finite

looking_at(Vector2)

Parameters

orthonormalized

rotated(float)

Parameters

rotated_local(float)

Parameters

scaled(Vector2)

Parameters

scaled_local(Vector2)

Parameters

translated(Vector2)

Parameters

translated_local(Vector2)

Parameters

Operators

!= (Transform2D)

Parameters

* (PackedVector2Array)

Parameters

* (Rect2)

Parameters

* (Transform2D)

Parameters

* (Vector2)

Parameters

* (float)

Parameters

* (int)

Parameters

/ (float)

Parameters

/ (int)

Parameters

== (Transform2D)

Parameters

[] (int)