Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Quaternion
Единичный кватернион, используемый для представления трехмерных вращений.
Описание
The Quaternion built-in Variant type is a 4D data structure that represents rotation in the form of a Hamilton convention quaternion. Compared to the Basis type which can store both rotation and scale, quaternions can only store rotation.
A Quaternion is composed by 4 floating-point components: w, x, y, and z. These components are very compact in memory, and because of this some operations are more efficient and less likely to cause floating-point errors. Methods such as get_angle(), get_axis(), and slerp() are faster than their Basis counterparts.
For a great introduction to quaternions, see this video by 3Blue1Brown. You do not need to know the math behind quaternions, as Godot provides several helper methods that handle it for you. These include slerp() and spherical_cubic_interpolate(), as well as the * operator.
Note: Quaternions must be normalized before being used for rotation (see normalized()).
Note: Similarly to Vector2 and Vector3, the components of a quaternion use 32-bit precision by default, unlike float which is always 64-bit. If double precision is needed, compile the engine with the option precision=double.
Note: In a boolean context, a quaternion will evaluate to false if it's equal to IDENTITY. Otherwise, a quaternion will always evaluate to true.
Примечание
Существуют заметные различия при использовании данного API с C#. Подробнее см. API различия C# и GDScript.
Обучающие материалы
Свойства
|
||
|
||
|
||
|
Конструкторы
Quaternion(from: Quaternion) |
|
Quaternion(arc_from: Vector3, arc_to: Vector3) |
|
Quaternion(axis: Vector3, angle: float) |
|
Quaternion(from: Basis) |
|
Quaternion(x: float, y: float, z: float, w: float) |
Методы
angle_to(to: Quaternion) const |
|
dot(with: Quaternion) const |
|
exp() const |
|
from_euler(euler: Vector3) static |
|
get_angle() const |
|
get_axis() const |
|
inverse() const |
|
is_equal_approx(to: Quaternion) const |
|
is_finite() const |
|
is_normalized() const |
|
length() const |
|
length_squared() const |
|
log() const |
|
normalized() const |
|
slerp(to: Quaternion, weight: float) const |
|
slerpni(to: Quaternion, weight: float) const |
|
spherical_cubic_interpolate(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float) const |
|
spherical_cubic_interpolate_in_time(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float, b_t: float, pre_a_t: float, post_b_t: float) const |
Операторы
operator !=(right: Quaternion) |
|
operator *(right: Quaternion) |
|
operator *(right: Vector3) |
|
operator *(right: float) |
|
operator *(right: int) |
|
operator +(right: Quaternion) |
|
operator -(right: Quaternion) |
|
operator /(right: float) |
|
operator /(right: int) |
|
operator ==(right: Quaternion) |
|
operator [](index: int) |
|
Константы
IDENTITY = Quaternion(0, 0, 0, 1) 🔗
Кватернион идентичности, представляющий отсутствие вращения. Имеет такое же вращение, как и Basis.IDENTITY.
Если Vector3 вращается (умножается) на этот кватернион, он не изменяется.
Примечание: В GDScript эта константа эквивалентна созданию Quaternion без каких-либо аргументов. Ее можно использовать для того, чтобы сделать ваш код более понятным и для согласованности с C#.
Описания свойств
Компонент W кватерниона. Это «реальная» часть.
Примечание: Компоненты кватерниона обычно не следует изменять напрямую.
X-компонента кватерниона. Это значение вдоль «мнимой» оси i.
Примечание: Компоненты кватерниона обычно не следует изменять напрямую.
Компонент Y кватерниона. Это значение вдоль «мнимой» оси j.
Примечание: Компоненты кватерниона обычно не следует изменять напрямую.
Z-компонента кватерниона. Это значение вдоль «мнимой» оси k.
Примечание: Компоненты кватерниона обычно не следует изменять напрямую.
Описания конструктора
Quaternion Quaternion() 🔗
Создает Quaternion, идентичный IDENTITY.
Примечание: В C# это создает Quaternion, все компоненты которого установлены в 0.0.
Quaternion Quaternion(from: Quaternion)
Создает Quaternion как копию заданного Quaternion.
Quaternion Quaternion(arc_from: Vector3, arc_to: Vector3)
Создает Quaternion, представляющий кратчайшую дугу между arc_from и arc_to. Их можно представить как две точки, пересекающие поверхность сферы, с радиусом 1.0.
Quaternion Quaternion(axis: Vector3, angle: float)
Создает Quaternion, представляющий вращение вокруг axis на заданный angle в радианах. Ось должна быть нормализованным вектором.
Quaternion Quaternion(from: Basis)
Создает Quaternion из заданного вращения Basis.
Этот конструктор быстрее, чем Basis.get_rotation_quaternion(), но заданный базис должен быть ортонормализован (см. Basis.orthonormalized()). В противном случае конструктор завершается неудачей и возвращает IDENTITY.
Quaternion Quaternion(x: float, y: float, z: float, w: float)
Создает Quaternion, определенный заданными значениями.
Примечание: Только нормализованные кватернионы представляют вращение; если эти значения не нормализованы, новый Quaternion не будет допустимым для вращения.
Описания метода
float angle_to(to: Quaternion) const 🔗
Возвращает угол между этим кватернионом и to. Это величина угла, на который вам нужно повернуть, чтобы перейти от одного к другому.
Примечание: Величина ошибки с плавающей точкой для этого метода аномально высока, поэтому такие методы, как is_zero_approx, не будут работать надежно.
float dot(with: Quaternion) const 🔗
Возвращает скалярное произведение между этим кватернионом и with.
Это эквивалентно (quat.x * with.x) + (quat.y * with.y) + (quat.z * with.z) + (quat.w * with.w).
Quaternion exp() const 🔗
Возвращает экспоненту этого кватерниона. Ось вращения результата — нормализованная ось вращения этого кватерниона, угол результата — длина векторной части этого кватерниона.
Quaternion from_euler(euler: Vector3) static 🔗
Constructs a new Quaternion from the given Vector3 of Euler angles, in radians. In Godot, Euler angles always use intrinsic order. This method always uses the intrinsic YXZ convention (@GlobalScope.EULER_ORDER_YXZ).
Возвращает угол поворота, представленный этим кватернионом.
Примечание: Кватернион должен быть нормализован.
Возвращает ось вращения, представленную этим кватернионом.
Vector3 get_euler(order: int = 2) const 🔗
Returns this quaternion's rotation as a Vector3 of Euler angles, in radians.
The order of each consecutive rotation can be changed with order (see EulerOrder constants). In Godot, Euler angles always use intrinsic order. By default, the intrinsic YXZ convention is used (@GlobalScope.EULER_ORDER_YXZ): since we are decomposing, local Z (roll) is calculated first, then local X (pitch), and lastly local Y (yaw). When using the opposite method from_euler() to compose a rotation, this order is reversed.
Quaternion inverse() const 🔗
Возвращает обратную версию этого кватерниона, инвертируя знак каждого компонента, кроме w.
bool is_equal_approx(to: Quaternion) const 🔗
Возвращает true, если этот кватернион и to приблизительно равны, вызывая @GlobalScope.is_equal_approx() для каждого компонента.
Возвращает true, если этот кватернион конечен, вызывая @GlobalScope.is_finite() для каждого компонента.
Возвращает true, если этот кватернион нормализован. См. также normalized().
Возвращает длину этого кватерниона, также называемую величиной.
float length_squared() const 🔗
Возвращает длину этого кватерниона, возведенную в квадрат.
Примечание: Этот метод быстрее, чем length(), поэтому предпочитайте его, если вам нужно только сравнить длины кватернионов.
Quaternion log() const 🔗
Возвращает логарифм этого кватерниона. Умножает ось вращения этого кватерниона на его угол вращения и сохраняет результат в векторной части возвращаемого кватерниона (x, y и z). Действительная часть возвращаемого кватерниона (w) всегда равна 0.0.
Quaternion normalized() const 🔗
Возвращает копию этого кватерниона, нормализованную так, что ее длина равна 1.0. См. также is_normalized().
Quaternion slerp(to: Quaternion, weight: float) const 🔗
Выполняет сферически-линейную интерполяцию с кватернионом to, заданным weight и возвращает результат. И этот кватернион, и to должны быть нормализованы.
Quaternion slerpni(to: Quaternion, weight: float) const 🔗
Выполняет сферически-линейную интерполяцию с кватернионом to, заданным weight и возвращает результат. В отличие от slerp(), этот метод не проверяет, является ли путь вращения меньше 90 градусов. И этот кватернион, и to должны быть нормализованы.
Quaternion spherical_cubic_interpolate(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float) const 🔗
Выполняет сферическую кубическую интерполяцию между кватернионами pre_a, данным вектором, b и post_b на заданную величину weight.
Quaternion spherical_cubic_interpolate_in_time(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float, b_t: float, pre_a_t: float, post_b_t: float) const 🔗
Выполняет сферическую кубическую интерполяцию между кватернионами pre_a, этим вектором, b и post_b на заданную величину weight.
Он может выполнять более плавную интерполяцию, чем methodspheric_cubic_interpolate по значениям времени.
Описания оператора
bool operator !=(right: Quaternion) 🔗
Возвращает true, если компоненты обоих кватернионов не совсем равны.
Примечание: Из-за ошибок точности с плавающей точкой рассмотрите возможность использования is_equal_approx() вместо этого, что более надежно.
Quaternion operator *(right: Quaternion) 🔗
Составляет (умножает) два кватерниона. Это вращает кватернион right (потомок) этим кватернионом (родитель).
Vector3 operator *(right: Vector3) 🔗
Поворачивает (умножает) вектор right на этот кватернион, возвращая Vector3.
Quaternion operator *(right: float) 🔗
Умножает каждый компонент Quaternion на правильное значение float.
Эта операция сама по себе не имеет смысла, но ее можно использовать как часть большего выражения.
Quaternion operator *(right: int) 🔗
Умножает каждый компонент Quaternion на правильное значение int.
Эта операция сама по себе не имеет смысла, но ее можно использовать как часть более крупного выражения.
Quaternion operator +(right: Quaternion) 🔗
Добавляет каждый компонент левого Quaternion к правому Quaternion.
Эта операция сама по себе не имеет смысла, но ее можно использовать как часть большего выражения, например, аппроксимации промежуточного поворота между двумя соседними поворотами.
Quaternion operator -(right: Quaternion) 🔗
Вычитает каждый компонент левого Quaternion из правого Quaternion.
Эта операция сама по себе не имеет смысла, но ее можно использовать как часть большего выражения.
Quaternion operator /(right: float) 🔗
Делит каждый компонент Quaternion на правое значение float.
Эта операция сама по себе не имеет смысла, но ее можно использовать как часть более крупного выражения.
Quaternion operator /(right: int) 🔗
Делит каждый компонент Quaternion на правое значение int.
Эта операция сама по себе не имеет смысла, но ее можно использовать как часть более крупного выражения.
bool operator ==(right: Quaternion) 🔗
Возвращает true, если компоненты обоих кватернионов в точности равны.
Примечание: Из-за ошибок точности с плавающей точкой рассмотрите возможность использования is_equal_approx() вместо этого, что более надежно.
float operator [](index: int) 🔗
Доступ к каждому компоненту этого кватерниона по их индексу.
Индекс 0 такой же, как x, индекс 1 такой же, как y, индекс 2 такой же, как z, а индекс 3 такой же, как w.
Quaternion operator unary+() 🔗
Возвращает то же значение, как если бы + не было. Унарный + ничего не делает, но иногда он может сделать ваш код более читаемым.
Quaternion operator unary-() 🔗
Возвращает отрицательное значение Quaternion. Это то же самое, что умножить все компоненты на -1. Эта операция приводит к кватерниону, который представляет то же вращение.