Transform2D

Documentation

Overview

Package Transform2D provides a 2×3 matrix representing a 2D transformation.

Index

• Variables
• func BasisTransform(t OriginXY, v Vector2.XY) Vector2.XY
• func Determinant(t OriginXY) Float.X
• func InverseBasisTransform(t OriginXY, v Vector2.XY) Vector2.XY
• func IsApproximatelyEqual(a, b OriginXY) bool
• func IsConformal(t OriginXY) bool
• func IsFinite(t OriginXY) bool
• func Origin(t OriginXY) Vector2.XY
• func Rotation(t OriginXY) Angle.Radians
• func Scale(t OriginXY) Vector2.XY
• func Skew(t OriginXY) Angle.Radians
• func Vector(v Vector2.XY, t OriginXY) Vector2.XY
• type OriginXY
  • func AffineInverse(t OriginXY) OriginXY
  • func Inverse(t OriginXY) OriginXY
  • func Lerp[X Float.Any](a, b OriginXY, weight X) OriginXY
  • func LookingAt(target Vector2.XY, t OriginXY) OriginXY
  • func Mul(a, b OriginXY) OriginXY
  • func New() OriginXY
  • func Orthonormalized(t OriginXY) OriginXY
  • func Rotated(t OriginXY, angle Angle.Radians) OriginXY
  • func RotatedLocal(t OriginXY, angle Angle.Radians) OriginXY
  • func RotationScaleSkewPosition(rotation Angle.Radians, scale Vector2.XY, skew Angle.Radians, ...) OriginXY
  • func Scaled(t OriginXY, scale Vector2.XY) OriginXY
  • func ScaledLocal(t OriginXY, scale Vector2.XY) OriginXY
  • func Translated(t OriginXY, offset Vector2.XY) OriginXY
  • func TranslatedLocal(t OriginXY, offset Vector2.XY) OriginXY

Variables

var (
	// Identity Transform2D. A transform with no translation, no rotation, and its scale being 1.
	// When multiplied by another value such as Rect2 or another Transform2D, no transformation
	// occurs. This means that:
	//
	//  - The x points right [Vector2.Right]
	//  - The y points up [Vector2.Up]
	//
	Identity = OriginXY{
		X: Vector2.Right,
		Y: Vector2.XY{0, 1},
	}

	// When any transform is multiplied by FlipX, it negates all components of the x axis (the X column).
	// When FlipX is multiplied by any basis, it negates the Vector2.X component of all axes (the X row).
	FlipX = OriginXY{
		X: Vector2.New(-1, 0),
		Y: Vector2.New(0, 1),
	}

	// When any transform is multiplied by FlipY, it negates all components of the y axis (the Y column).
	//
	// When FlipY is multiplied by any basis, it negates the Vector2.Y component of all axes (the Y row).
	FlipY = OriginXY{
		X: Vector2.New(1, 0),
		Y: Vector2.New(0, -1),
	}
)

Functions

func BasisTransform

func BasisTransform(t OriginXY, v Vector2.XY) Vector2.XY

BasisTransform returns a vector transformed (multiplied) by the basis matrix.

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

func Determinant

func Determinant(t OriginXY) Float.X

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

func InverseBasisTransform

func InverseBasisTransform(t OriginXY, v Vector2.XY) Vector2.XY

InverseBasisTransform 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.InverseBasisTransform(vector) is equivalent to transform.Inverse().BasisTransform(vector). See [Transform2D.Inverse].

For non-orthonormal transforms (e.g. with scaling) transform.AffineInverse().BasisTransform(vector) can be used instead. See [Transform2D.AffineInverse].

func IsApproximatelyEqual

func IsApproximatelyEqual(a, b OriginXY) bool

IsApproximatelyEqual returns true if this transform and xform are approximately equal, by running [Vector2.IsApproximatelyEqual] on each component.

func IsConformal

func IsConformal(t OriginXY) bool

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

func IsFinite

func IsFinite(t OriginXY) bool

IsFinite returns true if this transform is finite, by calling [Vector2.IsFinite] on each component.

func Origin

func Origin(t OriginXY) Vector2.XY

Origin returns the transform's origin (translation).

func Rotation

func Rotation(t OriginXY) Angle.Radians

Rotation returns the transform's rotation.

func Scale

func Scale(t OriginXY) Vector2.XY

Scale returns the transform's scale.

func Skew

func Skew(t OriginXY) Angle.Radians

Skew returns the transform's skew (in radians)

func Vector

func Vector(v Vector2.XY, t OriginXY) Vector2.XY

Types

type OriginXY

type OriginXY = struct {
	// 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].
	X Vector2.XY

	// 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).
	Y Vector2.XY

	// Origin of this transform, and the column 2 of the matrix. In 2D space, this can be seen
	// as the position.
	Origin Vector2.XY
}

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

func AffineInverse

func AffineInverse(t OriginXY) OriginXY

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

func Inverse

func Inverse(t OriginXY) OriginXY

Inverse 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).

func Lerp

func Lerp[X Float.Any](a, b OriginXY, weight X) OriginXY

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

func LookingAt

func LookingAt(target Vector2.XY, t OriginXY) OriginXY

LookingAt returns a copy of the transform rotated such that the rotated X-axis points towards the target position.

Operations take place in global space.

func Mul

func Mul(a, b OriginXY) OriginXY

func New

func New() OriginXY

New returns the identity transform.

func Orthonormalized

func Orthonormalized(t OriginXY) OriginXY

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

func Rotated

func Rotated(t OriginXY, angle Angle.Radians) OriginXY

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

func RotatedLocal

func RotatedLocal(t OriginXY, angle Angle.Radians) OriginXY

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

func RotationScaleSkewPosition

func RotationScaleSkewPosition(rotation Angle.Radians, scale Vector2.XY, skew Angle.Radians, position Vector2.XY) OriginXY

RotationScaleSkewPosition constructs a new Transform2D from the given rotation and position.

func Scaled

func Scaled(t OriginXY, scale Vector2.XY) OriginXY

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

func ScaledLocal

func ScaledLocal(t OriginXY, scale Vector2.XY) OriginXY

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

func Translated

func Translated(t OriginXY, offset Vector2.XY) OriginXY

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

func TranslatedLocal

func TranslatedLocal(t OriginXY, offset Vector2.XY) OriginXY

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