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

A 2×3 matrix representing a 2D transformation.

Description

A 2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of three Vector2 values: x, y, and the origin.

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

Note

There are notable differences when using this API with C#. See C# API differences to GDScript for more information.

Tutorials

Properties

Vector2

origin

Vector2(0, 0)

Vector2

x

Vector2(1, 0)

Vector2

y

Vector2(0, 1)

Constructors

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)

Methods

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

Operators

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)


Constants

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

The identity Transform2D with no translation, rotation or scaling applied. When applied to other data structures, IDENTITY performs no transformation.

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

The Transform2D that will flip something along the X axis.

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

The Transform2D that will flip something along the Y axis.


Property Descriptions

Vector2 origin = Vector2(0, 0)

The origin vector (column 2, the third column). Equivalent to array index 2. The origin vector represents translation.


Vector2 x = Vector2(1, 0)

The basis matrix's X vector (column 0). Equivalent to array index 0.


Vector2 y = Vector2(0, 1)

The basis matrix's Y vector (column 1). Equivalent to array index 1.


Constructor Descriptions

Transform2D Transform2D()

Constructs a default-initialized Transform2D set to IDENTITY.


Transform2D Transform2D(from: Transform2D)

Constructs a Transform2D as a copy of the given Transform2D.


Transform2D Transform2D(rotation: float, position: Vector2)

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


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

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


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

Constructs the transform from 3 Vector2 values representing x, y, and the origin (the three column vectors).


Method Descriptions

Transform2D affine_inverse() const

Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant).


Vector2 basis_xform(v: Vector2) const

Returns a vector transformed (multiplied) by the basis matrix.

This method does not account for translation (the origin vector).


Vector2 basis_xform_inv(v: Vector2) const

Returns a vector transformed (multiplied) by the inverse basis matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).

This method does not account for translation (the origin vector).

transform.basis_xform_inv(vector) is equivalent to transform.inverse().basis_xform(vector). See inverse.

For non-orthonormal transforms (e.g. with scaling) transform.affine_inverse().basis_xform(vector) can be used instead. See affine_inverse.


float determinant() const

Returns the determinant of the basis matrix. If the basis is uniformly scaled, then its determinant equals the square of the scale factor.

A negative determinant means the basis was flipped, so one part of the scale is negative. A zero determinant means the basis isn't invertible, and is usually considered invalid.


Vector2 get_origin() const

Returns the transform's origin (translation).


float get_rotation() const

Returns the transform's rotation (in radians).


Vector2 get_scale() const

Returns the scale.


float get_skew() const

Returns the transform's skew (in radians).


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

Returns a transform interpolated between this transform and another by a given weight (on the range of 0.0 to 1.0).


Transform2D inverse() const

Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use affine_inverse for non-orthonormal transforms (e.g. with scaling).


bool is_conformal() const

Returns true if the transform's basis is conformal, meaning it preserves angles and distance ratios, and may only be composed of rotation and uniform scale. Returns false if the transform's basis has non-uniform scale or shear/skew. This can be used to validate if the transform is non-distorted, which is important for physics and other use cases.


bool is_equal_approx(xform: Transform2D) const

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


bool is_finite() const

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


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.

Operations take place in global space.


Transform2D orthonormalized() const

Returns the transform with the basis orthogonal (90 degrees), and normalized axis vectors (scale of 1 or -1).


Transform2D rotated(angle: float) 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 left, i.e., R * X.

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


Transform2D rotated_local(angle: float) 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 scaled(scale: Vector2) 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_local(scale: Vector2) 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 translated(offset: Vector2) 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_local(offset: Vector2) 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.


Operator Descriptions

bool operator !=(right: Transform2D)

Returns true if the transforms are not equal.

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


PackedVector2Array operator *(right: PackedVector2Array)

Transforms (multiplies) each element of the Vector2 array by the given Transform2D matrix.


Rect2 operator *(right: Rect2)

Transforms (multiplies) the Rect2 by the given Transform2D matrix.


Transform2D operator *(right: Transform2D)

Composes these two transformation matrices by multiplying them together. This has the effect of transforming the second transform (the child) by the first transform (the parent).


Vector2 operator *(right: Vector2)

Transforms (multiplies) the Vector2 by the given Transform2D matrix.


Transform2D operator *(right: float)

This operator multiplies all components of the Transform2D, including the origin vector, which scales it uniformly.


Transform2D operator *(right: int)

This operator multiplies all components of the Transform2D, including the origin vector, which scales it uniformly.


Transform2D operator /(right: float)

This operator divides all components of the Transform2D, including the origin vector, which inversely scales it uniformly.


Transform2D operator /(right: int)

This operator divides all components of the Transform2D, including the origin vector, which inversely scales it uniformly.


bool operator ==(right: Transform2D)

Returns true if the transforms are exactly equal.

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


Vector2 operator [](index: int)

Access transform components using their index. t[0] is equivalent to t.x, t[1] is equivalent to t.y, and t[2] is equivalent to t.origin.


User-contributed notes

Please read the User-contributed notes policy before submitting a comment.