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
Un quaternion unitaire utilisé pour représenter des rotations 3D.
Description
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.
Note
Il y a des différences notables dans l'utilisation de cette API en C#. Voir Différences de l'API C# par rapport à GDScript pour plus d'informations.
Tutoriels
Propriétés
|
||
|
||
|
||
|
Constructeurs
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) |
Méthodes
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 |
Opérateurs
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) |
|
Constantes
IDENTITY = Quaternion(0, 0, 0, 1) 🔗
La quaternion d'identité, représentant une rotation nulle. Il s'agit de la même rotation que Basis.IDENTITY.
Si un Vector3 est pivoté (multiplié) par ce quaternion, il ne changera pas.
Note : En GDScript, cette constante est équivalente à créer un Quaternion sans aucun argument. Cela peut être utilisé pour rendre votre code plus clair, et pour être consistant avec le C#.
Descriptions des propriétés
La composante W du quaternion. Il s'agit de la partie "réelle".
Note : Les composantes des quaternions ne devraient habituellement pas être modifiées directement.
La composante X du quaternion. Il s'agit de la valeur le long de l'axe "imaginaire" i.
Note : Les composantes des quaternions ne devraient habituellement pas être modifiées directement.
La composante Y du quaternion. Il s'agit de la valeur le long de l'axe "imaginaire" j.
Note : Les composantes des quaternions ne devraient habituellement pas être modifiées directement.
La composante Z du quaternion. Il s'agit de la valeur le long de l'axe "imaginaire" k.
Note : Les composantes des quaternions ne devraient habituellement pas être modifiées directement.
Descriptions des constructeurs
Quaternion Quaternion() 🔗
Construit un Quaternion identique à IDENTITY.
Note : En C#, cela construit un Quaternion avec toutes ses composantes définies à 0.0.
Quaternion Quaternion(from: Quaternion)
Construit un Quaternion comme copie du Quaternion donné.
Quaternion Quaternion(arc_from: Vector3, arc_to: Vector3)
Construit un Quaternion représentant l'arc le plus court entre arc_from et arc_to. Cela peut être imaginé comme deux points intersectant la surface d'une sphère de rayon 1.0.
Quaternion Quaternion(axis: Vector3, angle: float)
Construit un Quaternion représentant la rotation autour de l'axe axis de l'angle donné, en radians. L'axe doit être un vecteur normalisé.
Quaternion Quaternion(from: Basis)
Construit un Quaternion depuis la rotation Basis donnée.
Ce constructeur est plus rapide que Basis.get_rotation_quaternion(), mais la base donnée doit être orthonormalisée (voir Basis.orthonormalized()). Sinon, le constructeur échoue et renvoie IDENTITY.
Quaternion Quaternion(x: float, y: float, z: float, w: float)
Construit un Quaternion défini par les valeurs données.
Note : Seuls les quaternions normalisés représentent une rotation, si ces valeurs ne sont pas normalisées, le nouveau Quaternion ne sera pas une rotation valide.
Descriptions des méthodes
float angle_to(to: Quaternion) const 🔗
Renvoie l'angle entre ce quaternion et to. Il s'agit de la magnitude de l'angle dont vous auriez besoin de pivoter pour aller de l'un à l'autre.
Note : La magnitude de l'erreur de flottant pour cette méthode est anormalement élevée, donc les méthodes telles que is_zero_approx ne fonctionneront pas de manière fiable.
float dot(with: Quaternion) const 🔗
Renvoie le produit scalaire entre ce quaternion et with.
C'est équivalent à (quat.x * with.x) + (quat.y * with.y) + (quat.z * with.z) + (quat.w * with.w).
Quaternion exp() const 🔗
Renvoie l'exponentielle de ce quaternion. L'axe de rotation du résultat est l'axe de rotation normalisé de ce quaternion, l'angle est le résultat de la longueur de la partie vectorielle de ce quaternion.
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).
Renvoie l'angle de la rotation représentée par ce quaternion.
Note: Le quaternion doit être normalisé.
Renvoie l'axe de rotation de la rotation représentée par ce quaternion.
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 🔗
Renvoie la version inverse de ce quaternion, inversant le signe de chaque composante excepté w.
bool is_equal_approx(to: Quaternion) const 🔗
Renvoie true si ce quaternion et to sont approximativement égaux, en appelant @GlobalScope.is_equal_approx() sur chaque composante.
Renvoie true si ce quaternion est fini, en appelant @GlobalScope.is_finite() sur chaque composante.
Renvoie true si ce quaternion est normalisé. Voir aussi normalized().
Renvoie la longueur de ce quaternion, aussi appelée magnitude.
float length_squared() const 🔗
Renvoie la longueur au carré de ce quaternion.
Note : Cette méthode est plus rapide que length() donc préférez-la si vous avez seulement besoin de comparer des longueurs de quaternion.
Quaternion log() const 🔗
Renvoie le logarithme de ce quaternion. Multiple l'axe de rotation de ce quaternion par son angle de rotation, et stocke le résultat dans la partie vectorielle du quaternion renvoyé (x, y et z). La partie réelle du quaternion renvoyé (w) vaut toujours 0.0.
Quaternion normalized() const 🔗
Renvoie une copie de ce quaternion, normalisé de sorte à ce que sa longueur soit 1.0. Voir aussi is_normalized().
Quaternion slerp(to: Quaternion, weight: float) const 🔗
Effectue une interpolation linéaire sphérique avec le quaternion to et un poids weight donnés, et renvoie le résultat. Les deux quaternions doivent être normalisés.
Quaternion slerpni(to: Quaternion, weight: float) const 🔗
Effectue une interpolation linéaire sphérique avec le quaternion to et un poids weight donnés, et renvoie le résultat. Contrairement à slerp(), cette méthode ne vérifie pas si le chemin de rotation est inférieur à 90 degrés. Les deux quaternions doivent être normalisés.
Quaternion spherical_cubic_interpolate(b: Quaternion, pre_a: Quaternion, post_b: Quaternion, weight: float) const 🔗
Effectue une interpolation sphérique cubique entre les quaternions pre_a, ce vecteur, b, et post_b, par la quantité weight donnée.
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 🔗
Effectue une interpolation sphérique cubique entre les quaternions pre_a, ce vecteur, b, et post_b, par la quantité weight donnée.
Elle peut effectuer une interpolation plus lisse que spherical_cubic_interpolate() pour les valeurs temporelles.
Descriptions des opérateurs
bool operator !=(right: Quaternion) 🔗
Renvoie true si les composantes des deux quaternions ne sont pas exactement égales.
Note : À cause des erreurs de précision des flottants, envisagez d'utiliser is_equal_approx() à la place, qui est plus fiable.
Quaternion operator *(right: Quaternion) 🔗
Compose (multiplie) deux quaternions. Cela tourne le quaternion right (l'enfant) par ce quaternion (le parent).
Vector3 operator *(right: Vector3) 🔗
Fait tourner (multiplie) le vecteur right par ce quaternion, renvoyant un Vector3.
Quaternion operator *(right: float) 🔗
Multiplie chaque composante du Quaternion par le flottant float de droite.
Cette opération ne veut rien dire seule, mais peut-être utilisée comme partie d'une plus grande expression.
Quaternion operator *(right: int) 🔗
Multiplie chaque composante du Quaternion par l'entier int de droite.
Cette opération ne veut rien dire seule, mais peut-être utilisée comme partie d'une plus grande expression.
Quaternion operator +(right: Quaternion) 🔗
Ajoute chaque composante du Quaternion de gauche à celles du Quaternion de droite.
Cette opération ne veut rien dire seule, mais peut être utilisée comme partie d'une plus grande expression, comme l'approximation d'une rotation intermédiaire entre deux rotations proches.
Quaternion operator -(right: Quaternion) 🔗
Soustrait chaque composante du Quaternion de gauche par celles du Quaternion de droite.
Cette opération ne veut rien dire seule, mais peut être utilisée comme partie d'une plus grande expression.
Quaternion operator /(right: float) 🔗
Multiple chaque composante du Quaternion de gauche par celles du Quaternion de droite.
Cette opération ne veut rien dire seule, mais peut être utilisée comme partie d'une plus grande expression.
Quaternion operator /(right: int) 🔗
Divise chaque composante du Quaternion de gauche par celles du Quaternion de droite.
Cette opération ne veut rien dire seule, mais peut être utilisée comme partie d'une plus grande expression.
bool operator ==(right: Quaternion) 🔗
Renvoie true si les composantes des deux quaternions sont exactement égales.
Note : À cause des erreurs de précision des flottants, envisagez d'utiliser is_equal_approx() à la place, qui est plus fiable.
float operator [](index: int) 🔗
Accède à chaque composante de ce quaternion par leur index.
L'index 0 est le même que x, l'index 1 est le même que y, l'index 2 est le même que z, et l'index 3 est le même que w.
Quaternion operator unary+() 🔗
Renvoie la même valeur comme si + n'était pas là. Le + unaire ne fait rien, mais peut parfois rendre votre code plus lisible.
Quaternion operator unary-() 🔗
Renvoie la valeur négative du Quaternion. C'est la même que de multiplier toutes les composantes par -1. Cette opération résulte en un quaternion qui représente la même rotation.