Transform3D

Documentation

Overview

Package Transform3D a 3×4 matrix representing a 3D transformation.

Index

• Variables
• func IsApproximatelyEqual(a, b BasisOrigin) bool
• func IsFinite(t BasisOrigin) bool
• func Transform(v Vector3.XYZ, t BasisOrigin) Vector3.XYZ
• type BasisOrigin
  • func AffineInverse(t BasisOrigin) BasisOrigin
  • func Inverse(t BasisOrigin) BasisOrigin
  • func Lerp[X Float.Any](t BasisOrigin, other BasisOrigin, weight X) BasisOrigin
  • func LookingAt(t BasisOrigin, target, up Vector3.XYZ) BasisOrigin
  • func Mul(a, b BasisOrigin) BasisOrigin
  • func New() BasisOrigin
  • func Orthonormalized(t BasisOrigin) BasisOrigin
  • func Rotated(t BasisOrigin, axis Vector3.XYZ, phi Angle.Radians) BasisOrigin
  • func RotatedLocal(t BasisOrigin, axis Vector3.XYZ, phi Angle.Radians) BasisOrigin
  • func Scaled(t BasisOrigin, scale Vector3.XYZ) BasisOrigin
  • func ScaledLocal(t BasisOrigin, scale Vector3.XYZ) BasisOrigin
  • func Translated(t BasisOrigin, offset Vector3.XYZ) BasisOrigin
  • func TranslatedLocal(t BasisOrigin, offset Vector3.XYZ) BasisOrigin

Variables

var (
	// Identity is a transform with no translation, no rotation, and its scale
	// being 1. Its basis is equal to [Basis.Identity].
	//
	// When multiplied by another Variant such as AABB or another BasisOrigin,
	// no transformation occurs.
	Identity = BasisOrigin{
		Basis: Basis.Identity,
	}

	// BasisOrigin with mirroring applied perpendicular to the YZ plane. Its basis
	// is equal to [Basis.FlipX].
	FlipX = BasisOrigin{
		Basis: Basis.FlipX,
	}

	// BasisOrigin with mirroring applied perpendicular to the XZ plane. Its basis
	// is equal to [Basis.FlipY].
	FlipY = BasisOrigin{
		Basis: Basis.FlipY,
	}

	// BasisOrigin with mirroring applied perpendicular to the XY plane. Its basis
	// is equal to [Basis.FlipZ].
	FlipZ = BasisOrigin{
		Basis: Basis.FlipZ,
	}
)

Functions

func IsApproximatelyEqual

func IsApproximatelyEqual(a, b BasisOrigin) bool

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

func IsFinite

func IsFinite(t BasisOrigin) bool

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

func Transform

func Transform(v Vector3.XYZ, t BasisOrigin) Vector3.XYZ

Types

type BasisOrigin

type BasisOrigin = struct {

	// Basis of this transform. It is composed by 3 axes (Basis.x, Basis.y,
	// and Basis.z). Together, these represent the transform's rotation,
	// scale, and shear.
	Basis Basis.XYZ

	// The translation offset of this transform. In 3D space, this can be
	// seen as the position.
	Origin Vector3.XYZ
}

The BasisOrigin built-in Variant type is a 3×4 matrix representing a transformation in 3D space. It contains a Basis, which on its own can represent rotation, scale, and shear. Additionally, combined with its own origin, the transform can also represent a translation.

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

Note: GD uses a right-handed coordinate system, which is a common standard. For directions, the convention for built-in types like Camera3D is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the 3D asset direction conventions tutorial.

func AffineInverse

func AffineInverse(t BasisOrigin) BasisOrigin

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

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](t BasisOrigin, other BasisOrigin, weight X) BasisOrigin

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(t BasisOrigin, target, up Vector3.XYZ) BasisOrigin

LookingAt returns a copy of the transform rotated such that the forward axis (-Z) points towards the target position.

The up axis (+Y) points as close to the up vector as possible while staying perpendicular to the forward axis. The resulting transform is orthonormalized. The existing rotation, scale, and skew information from the original transform is discarded. The target and up vectors cannot be zero, cannot be parallel to each other, and are defined in global/parent space.

If use_model_front is true, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the target position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right).

func Mul

func Mul(a, b BasisOrigin) BasisOrigin

func New

func New() BasisOrigin

New constructs a BasisOrigin identical to the Identity.

func Orthonormalized

func Orthonormalized(t BasisOrigin) BasisOrigin

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

func Rotated

func Rotated(t BasisOrigin, axis Vector3.XYZ, phi Angle.Radians) BasisOrigin

Rotated returns a copy of the transform rotated around the given axis by the given angle (in radians).

The axis must be a normalized vector.

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 BasisOrigin, axis Vector3.XYZ, phi Angle.Radians) BasisOrigin

RotatedLocal returns a copy of the transform rotated around the given axis by the given angle (in radians).

The axis must be a normalized vector.

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 Scaled

func Scaled(t BasisOrigin, scale Vector3.XYZ) BasisOrigin

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 BasisOrigin, scale Vector3.XYZ) BasisOrigin

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 BasisOrigin, offset Vector3.XYZ) BasisOrigin

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 BasisOrigin, offset Vector3.XYZ) BasisOrigin

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.