Description

TheTransform2D built-inVariant type is a 2×3matrix representing a transformation in 2D space. It contains threeVector2 values:x,y, andorigin. Together, they can represent translation, rotation, scale, and skew.

Thex andy axes form a 2×2 matrix, known as the transform'sbasis. 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 theMatrices and transforms tutorial.

Note: UnlikeTransform3D, there is no 2D equivalent to theBasis type. All mentions of "basis" refer to thex andy components ofTransform2D.

Tutorials

• Math documentation index

• Matrices and transforms

• Matrix Transform Demo

• 2.5D Game Demo

Properties

Constructors

Methods

Operators

Constants

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

The identityTransform2D. This is a transform with no translation, no rotation, and a scale ofVector2.ONE. This also means that:

• Thex points right (Vector2.RIGHT);

• They points down (Vector2.DOWN).

vartransform=Transform2D.IDENTITYprint("| 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 aVector2, aRect2, aPackedVector2Array, or anotherTransform2D is transformed (multiplied) by this constant, no transformation occurs.

Note: In GDScript, this constant is equivalent to creating aTransform2D without any arguments. It 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 byFLIP_X, it negates all components of thex axis (the X column).

WhenFLIP_X is multiplied by any transform, it negates theVector2.x component of all axes (the X row).

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

When any transform is multiplied byFLIP_Y, it negates all components of they axis (the Y column).

WhenFLIP_Y is multiplied by any transform, it negates theVector2.y component of all axes (the Y row).

Property Descriptions

Vector2origin =Vector2(0,0)🔗

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

Vector2x =Vector2(1,0)🔗

The transform basis's X axis, and the column0 of the matrix. Combined withy, this represents the transform's rotation, scale, and skew.

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

Vector2y =Vector2(0,1)🔗

The transform basis's Y axis, and the column1 of the matrix. Combined withx, this represents the transform's rotation, scale, and skew.

On the identity transform, this vector points down (Vector2.DOWN).

Constructor Descriptions

Transform2DTransform2D()🔗

Constructs aTransform2D identical toIDENTITY.

Note: In C#, this constructs aTransform2D with all of its components set toVector2.ZERO.

Transform2DTransform2D(from:Transform2D)

Constructs aTransform2D as a copy of the givenTransform2D.

Transform2DTransform2D(rotation:float, position:Vector2)

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

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

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

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

Constructs aTransform2D from 3Vector2 values representingx,y, and theorigin (the three matrix columns).

Method Descriptions

Transform2Daffine_inverse()const🔗

Returns the inverted version of this transform. Unlikeinverse(), 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 exactly0.0 (seedeterminant()).

Vector2basis_xform(v:Vector2)const🔗

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

Vector2basis_xform_inv(v:Vector2)const🔗

Returns a copy of thev vector, transformed (multiplied) by the inverse transform basis's matrix (seeinverse()). This method ignores theorigin.

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

floatdeterminant()const🔗

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

• If the determinant is exactly0.0, the basis is not invertible (seeinverse()).

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

Vector2get_origin()const🔗

Returns this transform's translation. Equivalent toorigin.

floatget_rotation()const🔗

Returns this transform's rotation (in radians). This is equivalent tox's angle (seeVector2.angle()).

Vector2get_scale()const🔗

Returns the length of bothx andy, as aVector2. If this transform's basis is not skewed, this value is the scaling factor. It is not affected by rotation.

varmy_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)

varmyTransform=newTransform2D(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 bydeterminant() is negative, the scale is also negative.

floatget_skew()const🔗

Returns this transform's skew (in radians).

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

Returns the result of the linear interpolation between this transform andxform by the givenweight.

Theweight should be between0.0 and1.0 (inclusive). Values outside this range are allowed and can be used to performextrapolation instead.

Transform2Dinverse()const🔗

Returns theinverted version of this transform.

Note: For this method to return correctly, the transform's basis needs to beorthonormal (seeorthonormalized()). That means the basis should only represent a rotation. If it does not, useaffine_inverse() instead.

boolis_conformal()const🔗

Returnstrue if this transform's basis is conformal. A conformal basis is bothorthogonal (the axes are perpendicular to each other) anduniform (the axes share the same length). This method can be especially useful during physics calculations.

boolis_equal_approx(xform:Transform2D)const🔗

Returnstrue if this transform andxform are approximately equal, by running@GlobalScope.is_equal_approx() on each component.

boolis_finite()const🔗

Returnstrue if this transform is finite, by calling@GlobalScope.is_finite() on each component.

Transform2Dlooking_at(target:Vector2 = Vector2(0, 0))const🔗

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

Transform2Dorthonormalized()const🔗

Returns a copy of this transform with its basis orthonormalized. An orthonormal basis is bothorthogonal (the axes are perpendicular to each other) andnormalized (the axes have a length of1.0), which also means it can only represent a rotation.

Transform2Drotated(angle:float)const🔗

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

Ifangle is positive, the transform is rotated clockwise.

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

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

Transform2Drotated_local(angle:float)const🔗

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

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

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

Transform2Dscaled(scale:Vector2)const🔗

Returns a copy of the transform scaled by the givenscale factor.

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

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

Transform2Dscaled_local(scale:Vector2)const🔗

Returns a copy of the transform scaled by the givenscale factor.

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

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

Transform2Dtranslated(offset:Vector2)const🔗

Returns a copy of the transform translated by the givenoffset.

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

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

Transform2Dtranslated_local(offset:Vector2)const🔗

Returns a copy of the transform translated by the givenoffset.

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

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

Operator Descriptions

booloperator !=(right:Transform2D)🔗

Returnstrue if the components of both transforms are not equal.

Note: Due to floating-point precision errors, consider usingis_equal_approx() instead, which is more reliable.

PackedVector2Arrayoperator *(right:PackedVector2Array)🔗

Transforms (multiplies) everyVector2 element of the givenPackedVector2Array by this transformation matrix.

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

Rect2operator *(right:Rect2)🔗

Transforms (multiplies) theRect2 by this transformation matrix.

Transform2Doperator *(right:Transform2D)🔗

Transforms (multiplies) this transform by theright transform.

This is the operation performed between parent and childCanvasItem nodes.

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

• For translation, seetranslated() ortranslated_local().

• For rotation, seerotated() orrotated_local().

• For scale, seescaled() orscaled_local().

Vector2operator *(right:Vector2)🔗

Transforms (multiplies) theVector2 by this transformation matrix.

Transform2Doperator *(right:float)🔗

Multiplies all components of theTransform2D by the givenfloat, including theorigin. This affects the transform's scale uniformly.

Transform2Doperator *(right:int)🔗

Multiplies all components of theTransform2D by the givenint, including theorigin. This affects the transform's scale uniformly.

Transform2Doperator /(right:float)🔗

Divides all components of theTransform2D by the givenfloat, including theorigin. This affects the transform's scale uniformly.

Transform2Doperator /(right:int)🔗

Divides all components of theTransform2D by the givenint, including theorigin. This affects the transform's scale uniformly.

booloperator ==(right:Transform2D)🔗

Returnstrue if the components of both transforms are exactly equal.

Note: Due to floating-point precision errors, consider usingis_equal_approx() instead, which is more reliable.

Vector2operator [](index:int)🔗

Accesses each axis (column) of this transform by their index. Index0 is the same asx, index1 is the same asy, and index2 is the same asorigin.