Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
Quaternion¶
代表 3D 旋转的单位四元数。
描述¶
四元数与 Basis 类似，实现的是旋转的矩阵表示。但 Basis 存储了旋转、缩放、切变，四元数只存储旋转。
四元数的参数可以使用轴角对来指定，也可以通过欧拉角来指定。由于四元数的紧凑性以及在内存中的存储方式，部分运算（尤其是获取轴角和执行 SLERP）在防止浮点数误差方面更加高效稳健。
注意：四元数需要先归一化，才能用于旋转。
备注
通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异。
教程¶
属性¶
|
||
|
||
|
||
|
构造函数¶
Quaternion ( ) |
|
Quaternion ( Quaternion from ) |
|
Quaternion ( Vector3 arc_from, Vector3 arc_to ) |
|
Quaternion ( Vector3 axis, float angle ) |
|
Quaternion ( Basis from ) |
|
Quaternion ( float x, float y, float z, float w ) |
方法¶
angle_to ( Quaternion to ) const |
|
dot ( Quaternion with ) const |
|
exp ( ) const |
|
from_euler ( Vector3 euler ) static |
|
get_angle ( ) const |
|
get_axis ( ) const |
|
inverse ( ) const |
|
is_equal_approx ( Quaternion to ) const |
|
is_finite ( ) const |
|
is_normalized ( ) const |
|
length ( ) const |
|
length_squared ( ) const |
|
log ( ) const |
|
normalized ( ) const |
|
slerp ( Quaternion to, float weight ) const |
|
slerpni ( Quaternion to, float weight ) const |
|
spherical_cubic_interpolate ( Quaternion b, Quaternion pre_a, Quaternion post_b, float weight ) const |
|
spherical_cubic_interpolate_in_time ( Quaternion b, Quaternion pre_a, Quaternion post_b, float weight, float b_t, float pre_a_t, float post_b_t ) const |
操作符¶
operator != ( Quaternion right ) |
|
operator * ( Quaternion right ) |
|
operator * ( Vector3 right ) |
|
operator * ( float right ) |
|
operator * ( int right ) |
|
operator + ( Quaternion right ) |
|
operator - ( Quaternion right ) |
|
operator / ( float right ) |
|
operator / ( int right ) |
|
operator == ( Quaternion right ) |
|
operator [] ( int index ) |
|
operator unary+ ( ) |
|
operator unary- ( ) |
常量¶
IDENTITY = Quaternion(0, 0, 0, 1)
单位四元数，代表无旋转。相当于单位 Basis 矩阵。如果一个向量被一个单位四元数变换，它不会改变。
属性说明¶
float w = 1.0
四元数的W分量（实数部分）。
四元数分量通常不应该被直接操作。
float x = 0.0
四元数的X分量（虚轴i部分）。
四元数分量通常不应直接操作。
float y = 0.0
四元数的Y分量（虚轴j部分）。
四元数分量通常不应直接操作。
float z = 0.0
四元数的Z分量（虚轴k部分）。
四元数分量通常不应该被直接操作。
构造函数说明¶
Quaternion Quaternion ( )
构造默认初始化的四元数，所有分量都被设置为 0。
Quaternion Quaternion ( Quaternion from )
构造给定 Quaternion 的副本。
Quaternion Quaternion ( Vector3 arc_from, Vector3 arc_to )
构造一个四元数，代表半径为 1.0 的球面上两个点之间最短的弧。
Quaternion Quaternion ( Vector3 axis, float angle )
构造一个四元数，它将围绕给定的轴旋转指定的角度。轴必须是一个归一化的向量。
Quaternion Quaternion ( Basis from )
从给定的 Basis 构造一个四元数。
Quaternion Quaternion ( float x, float y, float z, float w )
构建一个由给定值定义的四元数。
方法说明¶
float angle_to ( Quaternion to ) const
返回这个四元数与 to 之间的角度。这是从一个旋转到另一个旋转所需的角度大小。
注意：该方法的浮点数误差异常地高，因此 is_zero_approx 等方法的结果不可靠。
float dot ( Quaternion with ) const
返回两个四元数的点积。
Quaternion exp ( ) const
返回该四元数的指数。该结果的旋转轴是该四元数的归一化旋转轴，该结果的角度是该四元数的向量部分的长度。
Quaternion from_euler ( Vector3 euler ) static
按 YXZ 旋转顺序从欧拉角构造一个四元数。
float get_angle ( ) const
返回该四元数表示的旋转角度。
注意：该四元数必须被归一化。
Vector3 get_axis ( ) const
返回该四元数表示的旋转的旋转轴。
Vector3 get_euler ( int order=2 ) const
以欧拉角的形式返回该四元数的旋转。欧拉顺序取决于 order 参数，例如使用 YXZ 顺序：这个方法按照 Z、X、Y 的顺序分解。可能的取值见 EulerOrder 枚举。返回向量的格式为 (X 角, Y 角, Z 角)。
Quaternion inverse ( ) const
返回四元数的取逆。
bool is_equal_approx ( Quaternion to ) const
如果该四元数和 to 近似相等，则返回 true，判断方法是通过在每个分量上运行 @GlobalScope.is_equal_approx。
bool is_finite ( ) const
如果该四元数是有限的，则返回 true，判断方法是在每个分量上调用 @GlobalScope.is_finite。
bool is_normalized ( ) const
返回四元数是否被归一化。
float length ( ) const
返回四元数的长度。
float length_squared ( ) const
返回四元数的长度的平方。
Quaternion log ( ) const
返回该四元数的对数。该结果的向量部分是该四元数的旋转轴乘以其旋转角度，该结果的实部为零。
Quaternion normalized ( ) const
返回四元数的副本，归一化为单位长度。
Quaternion slerp ( Quaternion to, float weight ) const
返回该四元数与 to 之间的球面线性插值 weight 的结果。
注意：两个四元数都必须被归一化。
Quaternion slerpni ( Quaternion to, float weight ) const
返回在这个四元数和 to 之间按照 weight 进行球面线性插值的结果，不会检查旋转路径是否大于 90 度。
Quaternion spherical_cubic_interpolate ( Quaternion b, Quaternion pre_a, Quaternion post_b, float weight ) const
在四元数 pre_a、这个向量、b 以及 post_b 之间按照给定的 weight 进行球面三次插值。
Quaternion spherical_cubic_interpolate_in_time ( Quaternion b, Quaternion pre_a, Quaternion post_b, float weight, float b_t, float pre_a_t, float post_b_t ) const
在四元数 pre_a、该向量、b 和 post_b 之间，按给定量 weight 执行三次球面插值。
它可以根据时间值执行比 spherical_cubic_interpolate 更平滑的插值。
操作符说明¶
bool operator != ( Quaternion right )
如果四元数不相等，则返回 true。
注意：由于浮点数精度误差，请考虑改用 is_equal_approx，会更可靠。
Quaternion operator * ( Quaternion right )
通过将这两个四元数相乘，来合成这两个四元数。效果是将第二个四元数（子）按照第一个四元数（父）进行旋转。
Vector3 operator * ( Vector3 right )
使用给定的 Quaternion 旋转 Vector3（相乘）。
Quaternion operator * ( float right )
将该 Quaternion 的每个分量乘以给定的值。此操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator * ( int right )
将该 Quaternion 的每个分量乘以给定的值。此操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator + ( Quaternion right )
将左侧 Quaternion 的每个分量与右侧的 Quaternion 相加。这个运算本身没有意义，但可以用作更大表达式的一部分，例如求两个相近旋转的中间近似值。
Quaternion operator - ( Quaternion right )
将左侧 Quaternion 的每个分量与右侧的 Quaternion 相减。这个运算本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator / ( float right )
将该 Quaternion 的每个分量除以给定的值。此操作本身没有意义，但可以用作更大表达式的一部分。
Quaternion operator / ( int right )
将该 Quaternion 的每个分量除以给定的值。此操作本身没有意义，但可以用作更大表达式的一部分。
bool operator == ( Quaternion right )
如果四元数完全相等，则返回 true。
注意：由于浮点数精度误差，请考虑改用 is_equal_approx，会更可靠。
float operator [] ( int index )
使用索引访问四元数的分量。q[0] 等价于 q.x、q[1] 等价于 q.y、q[2] 等价于 q.z、q[3] 等价于q.w。
Quaternion operator unary+ ( )
返回与 + 不存在时相同的值。单目 + 没有作用，但有时可以使你的代码更具可读性。
Quaternion operator unary- ( )
返回该 Quaternion 的负值。和写 Quaternion(-q.x, -q.y, -q.z, -q.w) 相同。这个操作得到的是代表相同旋转的四元数。