virtualx-engine/doc/classes/Basis.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="Basis" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
	<brief_description>
		A 3×3 matrix for representing 3D rotation and scale.
	</brief_description>
	<description>
		A 3×3 matrix used for representing 3D rotation and scale. Usually used as an orthogonal basis for a [Transform3D].
		Contains 3 vector fields X, Y and Z as its columns, which are typically interpreted as the local basis vectors of a transformation. For such use, it is composed of a scaling and a rotation matrix, in that order (M = R.S).
		Basis can also be accessed as an array of 3D vectors. These vectors are usually orthogonal to each other, but are not necessarily normalized (due to scaling).
		For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial.
	</description>
	<tutorials>
		<link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link>
		<link title="Matrices and transforms">$DOCS_URL/tutorials/math/matrices_and_transforms.html</link>
		<link title="Using 3D transforms">$DOCS_URL/tutorials/3d/using_transforms.html</link>
		<link title="Matrix Transform Demo">https://godotengine.org/asset-library/asset/584</link>
		<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/125</link>
		<link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/676</link>
		<link title="2.5D Demo">https://godotengine.org/asset-library/asset/583</link>
	</tutorials>
	<constructors>
		<constructor name="Basis">
			<return type="Basis" />
			<description>
				Constructs a default-initialized [Basis] set to [constant IDENTITY].
			</description>
		</constructor>
		<constructor name="Basis">
			<return type="Basis" />
			<param index="0" name="from" type="Basis" />
			<description>
				Constructs a [Basis] as a copy of the given [Basis].
			</description>
		</constructor>
		<constructor name="Basis">
			<return type="Basis" />
			<param index="0" name="axis" type="Vector3" />
			<param index="1" name="angle" type="float" />
			<description>
				Constructs a pure rotation basis matrix, rotated around the given [param axis] by [param angle] (in radians). The axis must be a normalized vector.
			</description>
		</constructor>
		<constructor name="Basis">
			<return type="Basis" />
			<param index="0" name="from" type="Quaternion" />
			<description>
				Constructs a pure rotation basis matrix from the given quaternion.
			</description>
		</constructor>
		<constructor name="Basis">
			<return type="Basis" />
			<param index="0" name="x_axis" type="Vector3" />
			<param index="1" name="y_axis" type="Vector3" />
			<param index="2" name="z_axis" type="Vector3" />
			<description>
				Constructs a basis matrix from 3 axis vectors (matrix columns).
			</description>
		</constructor>
	</constructors>
	<methods>
		<method name="determinant" qualifiers="const">
			<return type="float" />
			<description>
				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.
			</description>
		</method>
		<method name="from_euler" qualifiers="static">
			<return type="Basis" />
			<param index="0" name="euler" type="Vector3" />
			<param index="1" name="order" type="int" default="2" />
			<description>
				Constructs a pure rotation Basis matrix from Euler angles in the specified Euler rotation order. By default, use YXZ order (most common). See the [enum EulerOrder] enum for possible values.
				[codeblocks]
				[gdscript]
				# Creates a Basis whose z axis points down.
				var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0))

				print(my_basis.z) # Prints (0, -1, 0).
				[/gdscript]
				[csharp]
				// Creates a Basis whose z axis points down.
				var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f));

				GD.Print(myBasis.Z); // Prints (0, -1, 0).
				[/csharp]
				[/codeblocks]
			</description>
		</method>
		<method name="from_scale" qualifiers="static">
			<return type="Basis" />
			<param index="0" name="scale" type="Vector3" />
			<description>
				Constructs a pure scale basis matrix with no rotation or shearing. The scale values are set as the diagonal of the matrix, and the other parts of the matrix are zero.
				[codeblocks]
				[gdscript]
				var my_basis = Basis.from_scale(Vector3(2, 4, 8))

				print(my_basis.x) # Prints (2, 0, 0).
				print(my_basis.y) # Prints (0, 4, 0).
				print(my_basis.z) # Prints (0, 0, 8).
				[/gdscript]
				[csharp]
				var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f));

				GD.Print(myBasis.X); // Prints (2, 0, 0).
				GD.Print(myBasis.Y); // Prints (0, 4, 0).
				GD.Print(myBasis.Z); // Prints (0, 0, 8).
				[/csharp]
				[/codeblocks]
			</description>
		</method>
		<method name="get_euler" qualifiers="const">
			<return type="Vector3" />
			<param index="0" name="order" type="int" default="2" />
			<description>
				Returns the basis's rotation in the form of Euler angles. The Euler order depends on the [param 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 [method get_rotation_quaternion] method instead, which returns a [Quaternion] quaternion instead of Euler angles.
			</description>
		</method>
		<method name="get_rotation_quaternion" qualifiers="const">
			<return type="Quaternion" />
			<description>
				Returns the basis's rotation in the form of a quaternion. See [method get_euler] if you need Euler angles, but keep in mind quaternions should generally be preferred to Euler angles.
			</description>
		</method>
		<method name="get_scale" qualifiers="const">
			<return type="Vector3" />
			<description>
				Assuming that the matrix is the combination of a rotation and scaling, return the absolute value of scaling factors along each axis.
				[codeblocks]
				[gdscript]
				var my_basis = Basis(
				    Vector3(2, 0, 0),
				    Vector3(0, 4, 0),
				    Vector3(0, 0, 8)
				)
				# Rotating the Basis in any way preserves its scale.
				my_basis = my_basis.rotated(Vector3.UP, TAU / 2)
				my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4)

				print(my_basis.get_scale()) # Prints (2, 4, 8).
				[/gdscript]
				[csharp]
				var myBasis = new Basis(
				    Vector3(2.0f, 0.0f, 0.0f),
				    Vector3(0.0f, 4.0f, 0.0f),
				    Vector3(0.0f, 0.0f, 8.0f)
				);
				// Rotating the Basis in any way preserves its scale.
				myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f);
				myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f);

				GD.Print(myBasis.Scale); // Prints (2, 4, 8).
				[/csharp]
				[/codeblocks]
			</description>
		</method>
		<method name="inverse" qualifiers="const">
			<return type="Basis" />
			<description>
				Returns the inverse of the matrix.
			</description>
		</method>
		<method name="is_conformal" qualifiers="const">
			<return type="bool" />
			<description>
				Returns [code]true[/code] if the basis is conformal, meaning it preserves angles and distance ratios, and may only be composed of rotation and uniform scale. Returns [code]false[/code] if the basis has non-uniform scale or shear/skew. This can be used to validate if the basis is non-distorted, which is important for physics and other use cases.
			</description>
		</method>
		<method name="is_equal_approx" qualifiers="const">
			<return type="bool" />
			<param index="0" name="b" type="Basis" />
			<description>
				Returns [code]true[/code] if this basis and [param b] are approximately equal, by calling [method @GlobalScope.is_equal_approx] on all vector components.
			</description>
		</method>
		<method name="is_finite" qualifiers="const">
			<return type="bool" />
			<description>
				Returns [code]true[/code] if this basis is finite, by calling [method @GlobalScope.is_finite] on all vector components.
			</description>
		</method>
		<method name="looking_at" qualifiers="static">
			<return type="Basis" />
			<param index="0" name="target" type="Vector3" />
			<param index="1" name="up" type="Vector3" default="Vector3(0, 1, 0)" />
			<param index="2" name="use_model_front" type="bool" default="false" />
			<description>
				Creates a Basis with a rotation such that the forward axis (-Z) points towards the [param target] position.
				The up axis (+Y) points as close to the [param up] vector as possible while staying perpendicular to the forward axis. The resulting Basis is orthonormalized. The [param target] and [param up] vectors cannot be zero, and cannot be parallel to each other.
				If [param use_model_front] is [code]true[/code], the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the [param target] position. By default, the -Z axis (camera forward) is treated as forward (implies +X is right).
			</description>
		</method>
		<method name="orthonormalized" qualifiers="const">
			<return type="Basis" />
			<description>
				Returns the orthonormalized version of the matrix (useful to call from time to time to avoid rounding error for orthogonal matrices). This performs a Gram-Schmidt orthonormalization on the basis of the matrix.
				[codeblocks]
				[gdscript]
				# Rotate this Node3D every frame.
				func _process(delta):
				    basis = basis.rotated(Vector3.UP, TAU * delta)
				    basis = basis.rotated(Vector3.RIGHT, TAU * delta)

				    basis = basis.orthonormalized()
				[/gdscript]
				[csharp]
				// Rotate this Node3D every frame.
				public override void _Process(double delta)
				{
				    Basis = Basis.Rotated(Vector3.Up, Mathf.Tau * (float)delta)
				                 .Rotated(Vector3.Right, Mathf.Tau * (float)delta)
				                 .Orthonormalized();
				}
				[/csharp]
				[/codeblocks]
			</description>
		</method>
		<method name="rotated" qualifiers="const">
			<return type="Basis" />
			<param index="0" name="axis" type="Vector3" />
			<param index="1" name="angle" type="float" />
			<description>
				Introduce an additional rotation around the given axis by [param angle] (in radians). The axis must be a normalized vector.
				[codeblocks]
				[gdscript]
				var my_basis = Basis.IDENTITY
				var angle = TAU / 2

				my_basis = my_basis.rotated(Vector3.UP, angle)    # Rotate around the up axis (yaw).
				my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Rotate around the right axis (pitch).
				my_basis = my_basis.rotated(Vector3.BACK, angle)  # Rotate around the back axis (roll).
				[/gdscript]
				[csharp]
				var myBasis = Basis.Identity;
				var angle = Mathf.Tau / 2.0f;

				myBasis = myBasis.Rotated(Vector3.Up, angle);    // Rotate around the up axis (yaw).
				myBasis = myBasis.Rotated(Vector3.Right, angle); // Rotate around the right axis (pitch).
				myBasis = myBasis.Rotated(Vector3.Back, angle);  // Rotate around the back axis (roll).
				[/csharp]
				[/codeblocks]
			</description>
		</method>
		<method name="scaled" qualifiers="const">
			<return type="Basis" />
			<param index="0" name="scale" type="Vector3" />
			<description>
				Introduce an additional scaling specified by the given 3D scaling factor.
				[codeblocks]
				[gdscript]
				var my_basis = Basis(
				    Vector3(1, 1, 1),
				    Vector3(2, 2, 2),
				    Vector3(3, 3, 3)
				)
				my_basis = my_basis.scaled(Vector3(0, 2, -2))

				print(my_basis.x) # Prints (0, 2, -2).
				print(my_basis.y) # Prints (0, 4, -4).
				print(my_basis.z) # Prints (0, 6, -6).
				[/gdscript]
				[csharp]
				var myBasis = new Basis(
				    new Vector3(1.0f, 1.0f, 1.0f),
				    new Vector3(2.0f, 2.0f, 2.0f),
				    new Vector3(3.0f, 3.0f, 3.0f)
				);
				myBasis = myBasis.Scaled(new Vector3(0.0f, 2.0f, -2.0f));

				GD.Print(myBasis.X); // Prints (0, 2, -2).
				GD.Print(myBasis.Y); // Prints (0, 4, -4).
				GD.Print(myBasis.Z); // Prints (0, 6, -6).
				[/csharp]
				[/codeblocks]
			</description>
		</method>
		<method name="slerp" qualifiers="const">
			<return type="Basis" />
			<param index="0" name="to" type="Basis" />
			<param index="1" name="weight" type="float" />
			<description>
				Assuming that the matrix is a proper rotation matrix, slerp performs a spherical-linear interpolation with another rotation matrix.
			</description>
		</method>
		<method name="tdotx" qualifiers="const">
			<return type="float" />
			<param index="0" name="with" type="Vector3" />
			<description>
				Transposed dot product with the X axis of the matrix.
			</description>
		</method>
		<method name="tdoty" qualifiers="const">
			<return type="float" />
			<param index="0" name="with" type="Vector3" />
			<description>
				Transposed dot product with the Y axis of the matrix.
			</description>
		</method>
		<method name="tdotz" qualifiers="const">
			<return type="float" />
			<param index="0" name="with" type="Vector3" />
			<description>
				Transposed dot product with the Z axis of the matrix.
			</description>
		</method>
		<method name="transposed" qualifiers="const">
			<return type="Basis" />
			<description>
				Returns the transposed version of the matrix.
				[codeblocks]
				[gdscript]
				var my_basis = Basis(
				    Vector3(1, 2, 3),
				    Vector3(4, 5, 6),
				    Vector3(7, 8, 9)
				)
				my_basis = my_basis.transposed()

				print(my_basis.x) # Prints (1, 4, 7).
				print(my_basis.y) # Prints (2, 5, 8).
				print(my_basis.z) # Prints (3, 6, 9).
				[/gdscript]
				[csharp]
				var myBasis = new Basis(
				    new Vector3(1.0f, 2.0f, 3.0f),
				    new Vector3(4.0f, 5.0f, 6.0f),
				    new Vector3(7.0f, 8.0f, 9.0f)
				);
				myBasis = myBasis.Transposed();

				GD.Print(myBasis.X); // Prints (1, 4, 7).
				GD.Print(myBasis.Y); // Prints (2, 5, 8).
				GD.Print(myBasis.Z); // Prints (3, 6, 9).
				[/csharp]
				[/codeblocks]
			</description>
		</method>
	</methods>
	<members>
		<member name="x" type="Vector3" setter="" getter="" default="Vector3(1, 0, 0)">
			The basis matrix's X vector (column 0). Equivalent to array index [code]0[/code].
		</member>
		<member name="y" type="Vector3" setter="" getter="" default="Vector3(0, 1, 0)">
			The basis matrix's Y vector (column 1). Equivalent to array index [code]1[/code].
		</member>
		<member name="z" type="Vector3" setter="" getter="" default="Vector3(0, 0, 1)">
			The basis matrix's Z vector (column 2). Equivalent to array index [code]2[/code].
		</member>
	</members>
	<constants>
		<constant name="IDENTITY" value="Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)">
			The identity basis, with no rotation or scaling applied.
			This is identical to creating [constructor Basis] without any parameters. This constant can be used to make your code clearer, and for consistency with C#.
		</constant>
		<constant name="FLIP_X" value="Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1)">
			The basis that will flip something along the X axis when used in a transformation.
		</constant>
		<constant name="FLIP_Y" value="Basis(1, 0, 0, 0, -1, 0, 0, 0, 1)">
			The basis that will flip something along the Y axis when used in a transformation.
		</constant>
		<constant name="FLIP_Z" value="Basis(1, 0, 0, 0, 1, 0, 0, 0, -1)">
			The basis that will flip something along the Z axis when used in a transformation.
		</constant>
	</constants>
	<operators>
		<operator name="operator !=">
			<return type="bool" />
			<param index="0" name="right" type="Basis" />
			<description>
				Returns [code]true[/code] if the [Basis] matrices are not equal.
				[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
			</description>
		</operator>
		<operator name="operator *">
			<return type="Basis" />
			<param index="0" name="right" type="Basis" />
			<description>
				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).
			</description>
		</operator>
		<operator name="operator *">
			<return type="Vector3" />
			<param index="0" name="right" type="Vector3" />
			<description>
				Transforms (multiplies) the [Vector3] by the given [Basis] matrix.
			</description>
		</operator>
		<operator name="operator *">
			<return type="Basis" />
			<param index="0" name="right" type="float" />
			<description>
				This operator multiplies all components of the [Basis], which scales it uniformly.
			</description>
		</operator>
		<operator name="operator *">
			<return type="Basis" />
			<param index="0" name="right" type="int" />
			<description>
				This operator multiplies all components of the [Basis], which scales it uniformly.
			</description>
		</operator>
		<operator name="operator ==">
			<return type="bool" />
			<param index="0" name="right" type="Basis" />
			<description>
				Returns [code]true[/code] if the [Basis] matrices are exactly equal.
				[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
			</description>
		</operator>
		<operator name="operator []">
			<return type="Vector3" />
			<param index="0" name="index" type="int" />
			<description>
				Access basis components using their index. [code]b[0][/code] is equivalent to [code]b.x[/code], [code]b[1][/code] is equivalent to [code]b.y[/code], and [code]b[2][/code] is equivalent to [code]b.z[/code].
			</description>
		</operator>
	</operators>
</class>