Struct Basis

Namespace

Godot

Assembly

GodotSharp.dll

3×3 matrix used for 3D rotation and scale. Almost always used as an orthogonal basis for a Transform.

Contains 3 vector fields X, Y and Z as its columns, which are typically interpreted as the local basis vectors of a 3D transformation. For such use, it is composed of a scaling and a rotation matrix, in that order (M = R.S).

Can also be accessed as array of 3D vectors. These vectors are normally orthogonal to each other, but are not necessarily normalized (due to scaling).

For more information, read this documentation article: https://docs.godotengine.org/en/latest/tutorials/math/matrices_and_transforms.html

public struct Basis : IEquatable<Basis>

Implements

IEquatable<Basis>

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Constructors

Basis(Quaternion)

Constructs a pure rotation basis matrix from the given quaternion.

public Basis(Quaternion quaternion)

Parameters

quaternion Quaternion

The quaternion to create the basis from.

Basis(Vector3, Vector3, Vector3)

Constructs a basis matrix from 3 axis vectors (matrix columns).

public Basis(Vector3 column0, Vector3 column1, Vector3 column2)

Parameters

column0 Vector3

The X vector, or Column0.

column1 Vector3

The Y vector, or Column1.

column2 Vector3

The Z vector, or Column2.

Basis(Vector3, float)

Constructs a pure rotation basis matrix, rotated around the given axis by angle (in radians). The axis must be a normalized vector.

public Basis(Vector3 axis, float angle)

Parameters

axis Vector3

The axis to rotate around. Must be normalized.

angle float

The angle to rotate, in radians.

Basis(float, float, float, float, float, float, float, float, float)

Constructs a transformation matrix from the given components. Arguments are named such that xy is equal to calling X.Y.

public Basis(float xx, float yx, float zx, float xy, float yy, float zy, float xz, float yz, float zz)

Parameters

xx float

The X component of the X column vector, accessed via b.X.X or [0][0].

yx float

The X component of the Y column vector, accessed via b.Y.X or [1][0].

zx float

The X component of the Z column vector, accessed via b.Z.X or [2][0].

xy float

The Y component of the X column vector, accessed via b.X.Y or [0][1].

yy float

The Y component of the Y column vector, accessed via b.Y.Y or [1][1].

zy float

The Y component of the Z column vector, accessed via b.Y.Y or [2][1].

xz float

The Z component of the X column vector, accessed via b.X.Y or [0][2].

yz float

The Z component of the Y column vector, accessed via b.Y.Y or [1][2].

zz float

The Z component of the Z column vector, accessed via b.Y.Y or [2][2].

Fields

Row0

Row 0 of the basis matrix. Shows which vectors contribute to the X direction. Rows are not very useful for user code, but are more efficient for some internal calculations.

public Vector3 Row0

Field Value

Vector3

Row1

Row 1 of the basis matrix. Shows which vectors contribute to the Y direction. Rows are not very useful for user code, but are more efficient for some internal calculations.

public Vector3 Row1

Field Value

Vector3

Row2

Row 2 of the basis matrix. Shows which vectors contribute to the Z direction. Rows are not very useful for user code, but are more efficient for some internal calculations.

public Vector3 Row2

Field Value

Vector3

Properties

Column0

Column 0 of the basis matrix (the X vector).

public Vector3 Column0 { readonly get; set; }

Property Value

Vector3

Equivalent to X and array index [0].

Column1

Column 1 of the basis matrix (the Y vector).

public Vector3 Column1 { readonly get; set; }

Property Value

Vector3

Equivalent to Y and array index [1].

Column2

Column 2 of the basis matrix (the Z vector).

public Vector3 Column2 { readonly get; set; }

Property Value

Vector3

Equivalent to Z and array index [2].

FlipX

The basis that will flip something along the X axis when used in a transformation.

public static Basis FlipX { get; }

Property Value

Basis

Equivalent to new Basis(Vector3.Left, Vector3.Up, Vector3.Back).

FlipY

The basis that will flip something along the Y axis when used in a transformation.

public static Basis FlipY { get; }

Property Value

Basis

Equivalent to new Basis(Vector3.Right, Vector3.Down, Vector3.Back).

FlipZ

The basis that will flip something along the Z axis when used in a transformation.

public static Basis FlipZ { get; }

Property Value

Basis

Equivalent to new Basis(Vector3.Right, Vector3.Up, Vector3.Forward).

Identity

The identity basis, with no rotation or scaling applied. This is used as a replacement for Basis() in GDScript. Do not use new Basis() with no arguments in C#, because it sets all values to zero.

public static Basis Identity { get; }

Property Value

Basis

Equivalent to new Basis(Vector3.Right, Vector3.Up, Vector3.Back).

this[int]

Access whole columns in the form of Vector3.

public Vector3 this[int column] { readonly get; set; }

Parameters

column int

Which column vector.

Property Value

Vector3

The basis column.

Exceptions

ArgumentOutOfRangeException

column is not 0, 1, 2 or 3.

this[int, int]

Access matrix elements in column-major order.

public float this[int column, int row] { readonly get; set; }

Parameters

column int

Which column, the matrix horizontal position.

row int

Which row, the matrix vertical position.

Property Value

float

The matrix element.

Scale

Assuming that the matrix is the combination of a rotation and scaling, return the absolute value of scaling factors along each axis.

public readonly Vector3 Scale { get; }

Property Value

Vector3

X

The basis matrix's X vector (column 0).

public Vector3 X { readonly get; set; }

Property Value

Vector3

Equivalent to Column0 and array index [0].

Y

The basis matrix's Y vector (column 1).

public Vector3 Y { readonly get; set; }

Property Value

Vector3

Equivalent to Column1 and array index [1].

Z

The basis matrix's Z vector (column 2).

public Vector3 Z { readonly get; set; }

Property Value

Vector3

Equivalent to Column2 and array index [2].

Methods

Determinant()

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

A negative determinant means the basis has a negative scale. A zero determinant means the basis isn't invertible, and is usually considered invalid.

public readonly float Determinant()

Returns

float

The determinant of the basis matrix.

Equals(Basis)

Returns true if the basis matrices are exactly equal. Note: Due to floating-point precision errors, consider using IsEqualApprox(Basis) instead, which is more reliable.

public readonly bool Equals(Basis other)

Parameters

other Basis

The other basis.

Returns

bool

Whether or not the basis matrices are exactly equal.

Equals(object)

Returns true if the Basis is exactly equal to the given object (obj). Note: Due to floating-point precision errors, consider using IsEqualApprox(Basis) instead, which is more reliable.

public override readonly bool Equals(object obj)

Parameters

obj object

The object to compare with.

Returns

bool

Whether or not the basis matrix and the object are exactly equal.

FromEuler(Vector3, EulerOrder)

Constructs a Basis matrix from Euler angles in the specified rotation order. By default, use YXZ order (most common).

public static Basis FromEuler(Vector3 euler, EulerOrder order = EulerOrder.Yxz)

Parameters

euler Vector3

The Euler angles to use.

order EulerOrder

The order to compose the Euler angles.

Returns

Basis

FromScale(Vector3)

Constructs a pure scale basis matrix with no rotation or shearing. The scale values are set as the main diagonal of the matrix, and all of the other parts of the matrix are zero.

public static Basis FromScale(Vector3 scale)

Parameters

scale Vector3

The scale Vector3.

Returns

Basis

A pure scale Basis matrix.

GetEuler(EulerOrder)

Returns the basis's rotation in the form of Euler angles. The Euler order depends on the order parameter, by default it uses the YXZ convention: when decomposing, first Z, then X, and Y last. The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle).

Consider using the GetRotationQuaternion() method instead, which returns a Quaternion quaternion instead of Euler angles.

public readonly Vector3 GetEuler(EulerOrder order = EulerOrder.Yxz)

Parameters

order EulerOrder

The Euler order to use. By default, use YXZ order (most common).

Returns

Vector3

A Vector3 representing the basis rotation in Euler angles.

GetHashCode()

Serves as the hash function for Basis.

public override readonly int GetHashCode()

Returns

int

A hash code for this basis.

GetRotationQuaternion()

Returns the Basis's rotation in the form of a Quaternion. See GetEuler(EulerOrder) if you need Euler angles, but keep in mind quaternions should generally be preferred to Euler angles.

public readonly Quaternion GetRotationQuaternion()

Returns

Quaternion

The basis rotation.

Inverse()

Returns the inverse of the matrix.

public readonly Basis Inverse()

Returns

Basis

The inverse matrix.

IsEqualApprox(Basis)

Returns true if this basis and other are approximately equal, by running IsEqualApprox(Vector3) on each component.

public readonly bool IsEqualApprox(Basis other)

Parameters

other Basis

The other basis to compare.

Returns

bool

Whether or not the bases are approximately equal.

IsFinite()

Returns true if this basis is finite, by calling IsFinite(float) on each component.

public readonly bool IsFinite()

Returns

bool

Whether this vector is finite or not.

LookingAt(Vector3, Vector3?, bool)

Creates a Basis with a rotation 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 Basis is orthonormalized. The target and up vectors cannot be zero, and cannot be parallel to each other.

public static Basis LookingAt(Vector3 target, Vector3? up = null, bool useModelFront = false)

Parameters

target Vector3

The position to look at.

up Vector3?

The relative up direction.

useModelFront bool

If true, then the model is oriented in reverse, towards the model front axis (+Z, Vector3.ModelFront), which is more useful for orienting 3D models.

Returns

Basis

The resulting basis matrix.

Orthonormalized()

Returns the orthonormalized version of the basis matrix (useful to call occasionally to avoid rounding errors for orthogonal matrices). This performs a Gram-Schmidt orthonormalization on the basis of the matrix.

public readonly Basis Orthonormalized()

Returns

Basis

An orthonormalized basis matrix.

Rotated(Vector3, float)

Introduce an additional rotation around the given axis by angle (in radians). The axis must be a normalized vector.

public readonly Basis Rotated(Vector3 axis, float angle)

Parameters

axis Vector3

The axis to rotate around. Must be normalized.

angle float

The angle to rotate, in radians.

Returns

Basis

The rotated basis matrix.

Scaled(Vector3)

Introduce an additional scaling specified by the given 3D scaling factor.

public readonly Basis Scaled(Vector3 scale)

Parameters

scale Vector3

The scale to introduce.

Returns

Basis

The scaled basis matrix.

Slerp(Basis, float)

Assuming that the matrix is a proper rotation matrix, slerp performs a spherical-linear interpolation with another rotation matrix.

public readonly Basis Slerp(Basis target, float weight)

Parameters

target Basis

The destination basis for interpolation.

weight float

A value on the range of 0.0 to 1.0, representing the amount of interpolation.

Returns

Basis

The resulting basis matrix of the interpolation.

Tdotx(Vector3)

Transposed dot product with the X axis of the matrix.

public readonly float Tdotx(Vector3 with)

Parameters

with Vector3

A vector to calculate the dot product with.

Returns

float

The resulting dot product.

Tdoty(Vector3)

Transposed dot product with the Y axis of the matrix.

public readonly float Tdoty(Vector3 with)

Parameters

with Vector3

A vector to calculate the dot product with.

Returns

float

The resulting dot product.

Tdotz(Vector3)

Transposed dot product with the Z axis of the matrix.

public readonly float Tdotz(Vector3 with)

Parameters

with Vector3

A vector to calculate the dot product with.

Returns

float

The resulting dot product.

ToString()

Converts this Basis to a string.

public override readonly string ToString()

Returns

string

A string representation of this basis.

ToString(string)

Converts this Basis to a string with the given format.

public readonly string ToString(string format)

Parameters

format string

Returns

string

A string representation of this basis.

Transposed()

Returns the transposed version of the basis matrix.

public readonly Basis Transposed()

Returns

Basis

The transposed basis matrix.

Operators

operator ==(Basis, Basis)

Returns true if the basis matrices are exactly equal. Note: Due to floating-point precision errors, consider using IsEqualApprox(Basis) instead, which is more reliable.

public static bool operator ==(Basis left, Basis right)

Parameters

left Basis

The left basis.

right Basis

The right basis.

Returns

bool

Whether or not the basis matrices are exactly equal.

operator !=(Basis, Basis)

Returns true if the basis matrices are not equal. Note: Due to floating-point precision errors, consider using IsEqualApprox(Basis) instead, which is more reliable.

public static bool operator !=(Basis left, Basis right)

Parameters

left Basis

The left basis.

right Basis

The right basis.

Returns

bool

Whether or not the basis matrices are not equal.

operator *(Basis, Basis)

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

public static Basis operator *(Basis left, Basis right)

Parameters

left Basis

The parent basis.

right Basis

The child basis.

Returns

Basis

The composed basis.

operator *(Basis, Vector3)

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

public static Vector3 operator *(Basis basis, Vector3 vector)

Parameters

basis Basis

The basis matrix transformation to apply.

vector Vector3

A Vector3 to transform.

Returns

Vector3

The transformed Vector3.

operator *(Vector3, Basis)

Returns a Vector3 transformed (multiplied) by the inverse basis matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). vector * basis is equivalent to basis.Transposed() * vector. See Transposed(). For transforming by inverse of a non-orthonormal basis (e.g. with scaling) basis.Inverse() * vector can be used instead. See Inverse().

public static Vector3 operator *(Vector3 vector, Basis basis)

Parameters

vector Vector3

A Vector3 to inversely transform.

basis Basis

The basis matrix transformation to apply.

Returns

Vector3

The inversely transformed vector.