265 lines
13 KiB
C++
265 lines
13 KiB
C++
#pragma once
|
|
|
|
#include <J3ML/LinearAlgebra/Forward.hpp>
|
|
#include <J3ML/Algorithm/RNG.hpp>
|
|
#include <cmath>
|
|
|
|
namespace J3ML::LinearAlgebra {
|
|
class Quaternion;
|
|
}
|
|
|
|
class J3ML::LinearAlgebra::Quaternion {
|
|
public:
|
|
float x;
|
|
float y;
|
|
float z;
|
|
float w;
|
|
public:
|
|
/// The identity quaternion performs no rotation when applied to a vector.
|
|
static const Quaternion Identity;
|
|
/// A compile-time constant Quaternion with the value (NAN, NAN, NAN, NAN).
|
|
/// For this constant, each element has the value of quiet NAN, or Not-A-Number.
|
|
/// @note Never compare a Quaternion to this value! Due to how IEEE floats work, "nan == nan" returns false!
|
|
/// That is, nothing is equal to NaN, not even NaN itself!
|
|
static const Quaternion NaN;
|
|
public:
|
|
/// The default constructor does not initialize any member values.
|
|
Quaternion() = default;
|
|
|
|
/// Copy constructor
|
|
Quaternion(const Quaternion &rhs);
|
|
|
|
/// Quaternion from Matrix3x3
|
|
explicit Quaternion(const Matrix3x3 &ro_mat);
|
|
|
|
/// Quaternion from Matrix4x4 RotatePart.
|
|
explicit Quaternion(const Matrix4x4 &ro_mat);
|
|
|
|
|
|
/// Quaternion from AxisAngle.
|
|
explicit Quaternion(const AxisAngle &angle);
|
|
|
|
/// Quaternion from Vector4 (no conversion).
|
|
explicit Quaternion(const Vector4 &vector4);
|
|
|
|
/// @param x The factor of i.
|
|
/// @param y The factor of j.
|
|
/// @param z The factor of k.
|
|
/// @param w The scalar factor (or 'w').
|
|
/// @note The input data is not normalized after construction, this has to be done manually.
|
|
Quaternion(float X, float Y, float Z, float W);
|
|
|
|
/// Creates a LookAt quaternion.
|
|
/** A LookAt quaternion is a quaternion that orients an object to face towards a specified target direction.
|
|
@param localForward Specifies the forward direction in the local space of the object. This is the direction
|
|
the model is facing at in its own local/object space, often +X(1,0,0), +Y(0,1,0), or +Z(0,0,1).
|
|
The vector to pass in here depends on the conventions you or your modeling software is using, and it is best
|
|
to pick one convention for all your objects, and be consistent.
|
|
This input parameter must be a normalized vector.
|
|
@param targetDirection Specifies the desired world space direction the object should look at. This function
|
|
will compute a quaternion which will rotate the localForward vector to orient towards this targetDirection
|
|
vector. This input parameter must be a normalized vector.
|
|
@param localUp Specifies the up direction in the local space of the object. This is the up direction the model
|
|
was authored in, often +Y (0,1,0) or +Z (0,0,1). The vector to pass in here depends on the conventions you
|
|
or your modeling software is using, and it is best to pick one convention for all your objects, and be
|
|
consistent. This input parameter must be a normalized vector. This vector must be perpendicular to the
|
|
vector localForward, i.e. localForward.Dot(localUp) == 0.
|
|
@param worldUp Specifies the global up direction of the scene in world space. Simply rotating one vector to
|
|
coincide with another (localForward->targetDirection) would cause the up direction of the resulting
|
|
orientation to drift (e.g. the model could be looking at its target its head slanted sideways). To keep
|
|
the up direction straight, this function orients the localUp direction of the model to point towards
|
|
the specified worldUp direction (as closely as possible). The worldUp and targetDirection vectors cannot be
|
|
collinear, but they do not need to be perpendicular either.
|
|
@return A quaternion that maps the given local space forward direction vector to point towards the given target
|
|
direction, and the given local up direction towards the given target world up direction. For the returned
|
|
quaternion Q it holds that M * localForward = targetDirection, and M * localUp lies in the plane spanned
|
|
by the vectors targetDirection and worldUp.
|
|
@see RotateFromTo() */
|
|
static Quaternion LookAt(const Vector3 &localForward, const Vector3 &targetDirection, const Vector3 &localUp, const Vector3 &worldUp);
|
|
|
|
/// Creates a new quaternion that rotates about the positive X axis by the given rotation.
|
|
static Quaternion RotateX(float rad);
|
|
|
|
/// Creates a new quaternion that rotates about the positive Y axis by the given rotation.
|
|
static Quaternion RotateY(float rad);
|
|
|
|
/// Creates a new quaternion that rotates about the positive Z axis by the given rotation.
|
|
static Quaternion RotateZ(float rad);
|
|
|
|
/// Creates a new quaternion that rotates sourceDirection vector (in world space) to coincide with the
|
|
/// targetDirection vector (in world space).
|
|
/// Rotation is performed about the origin.
|
|
/// The vectors sourceDirection and targetDirection are assumed to be normalized.
|
|
/// @note There are multiple such rotations - this function returns the rotation that has the shortest angle
|
|
/// (when decomposed to axis-angle notation).
|
|
static Quaternion RotateFromTo(const Vector3 &sourceDirection, const Vector3 &targetDirection);
|
|
|
|
static Quaternion RotateFromTo(const Vector4 &sourceDirection, const Vector4 &targetDirection);
|
|
|
|
/// Creates a new quaternion that
|
|
/// 1. rotates sourceDirection vector to coincide with the targetDirection vector, and then
|
|
/// 2. rotates sourceDirection2 (which was transformed by 1.) to targetDirection2, but keeping the constraint that
|
|
/// sourceDirection must look at targetDirection
|
|
static Quaternion
|
|
RotateFromTo(const Vector3 &sourceDirection, const Vector3 &targetDirection, const Vector3 &sourceDirection2,
|
|
const Vector3 &targetDirection2);
|
|
|
|
|
|
/// Returns a uniformly random unitary quaternion.
|
|
static Quaternion RandomRotation(RNG &rng);
|
|
|
|
public:
|
|
/// Inverses this quaternion in-place.
|
|
/// @note For optimization purposes, this function assumes that the quaternion is unitary, in which
|
|
/// case the inverse of the quaternion is simply just the same as its conjugate.
|
|
/// This function does not detect whether the operation succeeded or failed.
|
|
void Inverse();
|
|
|
|
/// Returns an inverted copy of this quaternion.
|
|
[[nodiscard]] Quaternion Inverted() const;
|
|
|
|
/// Computes the conjugate of this quaternion in-place.
|
|
void Conjugate();
|
|
|
|
/// Returns a conjugated copy of this quaternion.
|
|
[[nodiscard]] Quaternion Conjugated() const;
|
|
|
|
/// Inverses this quaternion in-place.
|
|
/// Call this function when the quaternion is not known beforehand to be normalized.
|
|
/// This function computes the inverse proper, and normalizes the result.
|
|
/// @note Because of the normalization, it does not necessarily hold that q * q.InverseAndNormalize() == id.
|
|
/// @return Returns the old length of this quaternion (not the old length of the inverse quaternion).
|
|
float InverseAndNormalize();
|
|
|
|
/// Returns the local +X axis in the post-transformed coordinate space. This is the same as transforming the vector (1,0,0) by this quaternion.
|
|
[[nodiscard]] Vector3 WorldX() const;
|
|
|
|
/// Returns the local +Y axis in the post-transformed coordinate space. This is the same as transforming the vector (0,1,0) by this quaternion.
|
|
[[nodiscard]] Vector3 WorldY() const;
|
|
|
|
/// Returns the local +Z axis in the post-transformed coordinate space. This is the same as transforming the vector (0,0,1) by this quaternion.
|
|
[[nodiscard]] Vector3 WorldZ() const;
|
|
|
|
/// Returns the axis of rotation for this quaternion.
|
|
[[nodiscard]] Vector3 Axis() const;
|
|
|
|
/// Returns the angle of rotation for this quaternion, in radians.
|
|
[[nodiscard]] float Angle() const;
|
|
|
|
[[nodiscard]] float LengthSquared() const;
|
|
|
|
[[nodiscard]] float Length() const;
|
|
|
|
[[nodiscard]] Matrix3x3 ToMatrix3x3() const;
|
|
|
|
[[nodiscard]] Matrix4x4 ToMatrix4x4() const;
|
|
|
|
[[nodiscard]] Matrix4x4 ToMatrix4x4(const Vector3 &translation) const;
|
|
|
|
[[nodiscard]] Vector3 Transform(const Vector3 &vec) const;
|
|
|
|
[[nodiscard]] Vector3 Transform(float X, float Y, float Z) const;
|
|
|
|
// Note: We only transform the x,y,z components of 4D vectors, w is left untouched
|
|
[[nodiscard]] Vector4 Transform(const Vector4 &vec) const;
|
|
|
|
[[nodiscard]] Vector4 Transform(float X, float Y, float Z, float W) const;
|
|
|
|
[[nodiscard]] Quaternion Lerp(const Quaternion &b, float t) const;
|
|
|
|
static Quaternion Lerp(const Quaternion &source, const Quaternion &target, float t);
|
|
|
|
[[nodiscard]] Quaternion Slerp(const Quaternion &q2, float t) const;
|
|
|
|
static Quaternion Slerp(const Quaternion &source, const Quaternion &target, float t);
|
|
|
|
/// Returns the 'from' vector rotated towards the 'to' vector by the given normalized time parameter.
|
|
/** This function slerps the given 'form' vector toward the 'to' vector.
|
|
@param from A normalized direction vector specifying the direction of rotation at t=0
|
|
@param to A normalized direction vector specifying the direction of rotation at t=1
|
|
@param t The interpolation time parameter, in the range [0, 1]. Input values outside this range are
|
|
silently clamped to the [0, 1] interval.
|
|
@return A spherical linear interpolation of the vector 'from' towards the vector 'to'. */
|
|
static Vector3 SlerpVector(const Vector3 &from, const Vector3 &to, float t);
|
|
|
|
/// Returns the 'from' vector rotated towards the 'to' vector by the given absolute angle, in radians.
|
|
/** This function slerps the given 'from' vector towards the 'to' vector.
|
|
@param from A normalized direction vector specifying the direction of rotation at angleRadians=0.
|
|
@param to A normalized direction vector specifying the target direction to rotate towards.
|
|
@param angleRadians The maximum angle to rotate the 'from' vector by, in the range [0, pi]. If the
|
|
angle between 'from' and 'to' is smaller than this angle, then the vector 'to' is returned.
|
|
Input values outside this range are silently clamped to the [0, pi] interval.
|
|
@return A spherical linear interpolation of the vector 'from' towards the vector 'to'. */
|
|
static Vector3 SlerpVectorAbs(const Vector3 &from, const Vector3 &to, float angleRadians);
|
|
|
|
/// Normalizes this quaternion in-place.
|
|
/// @returns false if failure, true if success.
|
|
[[nodiscard]] bool Normalize();
|
|
|
|
/// Returns a normalized copy of this quaternion.
|
|
[[nodiscard]] Quaternion Normalized() const;
|
|
|
|
/// Returns true if the length of this quaternion is one.
|
|
[[nodiscard]] bool IsNormalized(float epsilon = 1e-5f) const;
|
|
|
|
[[nodiscard]] bool IsInvertible(float epsilon = 1e-3f) const;
|
|
|
|
/// Returns true if the entries of this quaternion are all finite.
|
|
[[nodiscard]] bool IsFinite() const;
|
|
|
|
/// Returns true if this quaternion equals rhs, up to the given epsilon.
|
|
[[nodiscard]] bool Equals(const Quaternion &rhs, float epsilon = 1e-3f) const;
|
|
|
|
/// Compares whether this Quaternion and the given Quaternion are identical bit-by-bit in the underlying representation.
|
|
/// @note Prefer using this over e.g. memcmp, since there can be SSE-related padding in the structures.
|
|
bool BitEquals(const Quaternion& rhs) const;
|
|
|
|
/// @return A pointer to the first element (x). The data is contiguous in memory.
|
|
/// ptr[0] gives x, ptr[1] gives y, ptr[2] gives z, ptr[3] gives w.
|
|
inline float *ptr() { return &x; }
|
|
[[nodiscard]] inline const float *ptr() const { return &x; }
|
|
|
|
|
|
// Multiplies two quaternions together.
|
|
// The product q1 * q2 returns a quaternion that concatenates the two orientation rotations.
|
|
// The rotation q2 is applied first before q1.
|
|
Quaternion operator * (const Quaternion& rhs) const;
|
|
|
|
// Unsafe
|
|
Quaternion operator * (float scalar) const;
|
|
|
|
// Unsafe
|
|
Quaternion operator / (float scalar) const;
|
|
|
|
// Transforms the given vector by this Quaternion.
|
|
Vector3 operator * (const Vector3& rhs) const;
|
|
|
|
Vector4 operator * (const Vector4& rhs) const;
|
|
|
|
// Divides a quaternion by another. Divison "a / b" results in a quaternion that rotates the orientation b to coincide with orientation of
|
|
Quaternion operator / (const Quaternion& rhs) const;
|
|
Quaternion operator + (const Quaternion& rhs) const;
|
|
|
|
|
|
|
|
Quaternion operator + () const;
|
|
Quaternion operator - () const;
|
|
|
|
/// Computes the dot product of this and the given quaternion.
|
|
/// Dot product is commutative.
|
|
[[nodiscard]] float Dot(const Quaternion &quaternion) const;
|
|
|
|
/// Returns the angle between this and the target orientation (the shortest route) in radians.
|
|
[[nodiscard]] float AngleBetween(const Quaternion& target) const;
|
|
/// Returns the axis of rotation to get from this orientation to target orientation (the shortest route).
|
|
[[nodiscard]] Vector3 AxisFromTo(const Quaternion& target) const;
|
|
|
|
|
|
/// Sets this quaternion to represent the same rotation as the given matrix.
|
|
void Set(const Matrix3x3& matrix);
|
|
void Set(const Matrix4x4& matrix);
|
|
void Set(float x, float y, float z, float w);
|
|
void Set(const Quaternion& q);
|
|
void Set(const Vector4& v);
|
|
|
|
}; |