mirror of
https://github.com/godotengine/godot
synced 2024-09-15 22:58:00 +00:00
435 lines
18 KiB
XML
435 lines
18 KiB
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="Basis" />
|
||
<param index="0" name="right" type="float" />
|
||
<description>
|
||
This operator divides all components of the [Basis], which inversely scales it uniformly.
|
||
</description>
|
||
</operator>
|
||
<operator name="operator /">
|
||
<return type="Basis" />
|
||
<param index="0" name="right" type="int" />
|
||
<description>
|
||
This operator divides all components of the [Basis], which inversely 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>
|