Struct Quaternion
Represents a unit quaternion used to encode a 3D rotation.
public struct Quaternion- Inherited Members
Remarks
A quaternion is stored as four floats (X, Y, Z, W) where (X, Y, Z) is the vector part and W is the scalar part. For a rotation of angle θ around a normalized axis n: X = n.X·sin(θ/2), Y = n.Y·sin(θ/2), Z = n.Z·sin(θ/2), W = cos(θ/2).
The 16-byte memory layout (four sequential floats) makes Quaternion compatible with SIMD registers and GPU constant buffers.
Constructors
Quaternion(float, float, float, float)
Initializes a new Quaternion with the specified components.
public Quaternion(float x, float y, float z, float w)Parameters
xfloatThe X component of the vector part.
yfloatThe Y component of the vector part.
zfloatThe Z component of the vector part.
wfloatThe scalar (real) part.
Fields
Identity
The identity quaternion representing no rotation.
public static readonly Quaternion IdentityField Value
W
The scalar (real) part of the quaternion.
public float WField Value
X
The X component of the vector part.
public float XField Value
Y
The Y component of the vector part.
public float YField Value
Z
The Z component of the vector part.
public float ZField Value
Properties
Conjugate
Returns the conjugate of the quaternion (negates the vector part). For a unit quaternion, the conjugate equals the inverse.
public Quaternion Conjugate { get; }Property Value
Inverse
Returns the inverse of the quaternion. For a unit quaternion, prefer Conjugate which is faster.
public Quaternion Inverse { get; }Property Value
Magnitude
Returns the magnitude (norm) of the quaternion.
public float Magnitude { get; }Property Value
MagnitudeSquared
Returns the squared magnitude of the quaternion, avoiding a square root.
public float MagnitudeSquared { get; }Property Value
Normalized
Returns a normalized (unit) copy of this quaternion. Returns Identity if the magnitude is zero.
public Quaternion Normalized { get; }Property Value
Methods
Dot(Quaternion, Quaternion)
Returns the dot product of two quaternions.
public static float Dot(Quaternion a, Quaternion b)Parameters
aQuaternionbQuaternion
Returns
Equals(object?)
Indicates whether this instance and a specified object are equal.
public override bool Equals(object? obj)Parameters
objobjectThe object to compare with the current instance.
Returns
- bool
true if
objand this instance are the same type and represent the same value; otherwise, false.
Equals(Quaternion)
Returns true if this quaternion equals another.
public bool Equals(Quaternion other)Parameters
otherQuaternion
Returns
FromAxisAngle(Vector3, float)
Creates a quaternion representing a rotation of angle radians
around the given axis.
public static Quaternion FromAxisAngle(Vector3 axis, float angle)Parameters
axisVector3The axis of rotation (should be normalized).
anglefloatThe rotation angle in radians.
Returns
FromEuler(float, float, float)
Creates a quaternion from Euler angles (in radians) applied in Z (roll) → X (pitch) → Y (yaw) order (intrinsic rotations).
public static Quaternion FromEuler(float pitch, float yaw, float roll)Parameters
pitchfloatRotation around the X axis in radians.
yawfloatRotation around the Y axis in radians.
rollfloatRotation around the Z axis in radians.
Returns
GetHashCode()
Returns the hash code for this instance.
public override int GetHashCode()Returns
- int
A 32-bit signed integer that is the hash code for this instance.
Lerp(Quaternion, Quaternion, float)
Linearly interpolates between two quaternions and normalizes the result.
public static Quaternion Lerp(Quaternion a, Quaternion b, float t)Parameters
aQuaternionThe start quaternion at t = 0.
bQuaternionThe end quaternion at t = 1.
tfloatThe interpolation factor, typically in the range [0, 1].
Returns
Slerp(Quaternion, Quaternion, float)
Performs spherical linear interpolation (Slerp) between two unit quaternions. Produces a constant-speed rotation along the shortest arc on the unit 4-sphere.
public static Quaternion Slerp(Quaternion a, Quaternion b, float t)Parameters
aQuaternionThe start rotation at t = 0.
bQuaternionThe end rotation at t = 1.
tfloatThe interpolation factor, typically in the range [0, 1].
Returns
ToEuler()
Decomposes this quaternion into Euler angles (pitch, yaw, roll) in radians.
public (float pitch, float yaw, float roll) ToEuler()Returns
Remarks
The angles are in the range [-π, π] for pitch, yaw, and roll. Gimbal lock may occur near the poles of pitch (±90°).
ToMatrix4x4()
Converts this quaternion to an equivalent 4×4 rotation matrix.
public Matrix4x4 ToMatrix4x4()Returns
ToString()
Returns the fully qualified type name of this instance.
public override string ToString()Returns
- string
The fully qualified type name.
Operators
operator ==(Quaternion, Quaternion)
Returns true if two quaternions have equal components.
public static bool operator ==(Quaternion lhs, Quaternion rhs)Parameters
lhsQuaternionrhsQuaternion
Returns
implicit operator Quaternion(Quaternion)
Implicitly converts a Quaternion to a Quaternion.
public static implicit operator Quaternion(Quaternion q)Parameters
Returns
implicit operator Quaternion(Quaternion)
Implicitly converts this quaternion to a Quaternion for use with SIMD-accelerated operations.
public static implicit operator Quaternion(Quaternion q)Parameters
Returns
operator !=(Quaternion, Quaternion)
Returns true if any component of two quaternions differs.
public static bool operator !=(Quaternion lhs, Quaternion rhs)Parameters
lhsQuaternionrhsQuaternion
Returns
operator *(Quaternion, Point3)
Rotates a Point3 by this quaternion.
public static Point3 operator *(Quaternion q, Point3 p)Parameters
qQuaternionpPoint3
Returns
operator *(Quaternion, Quaternion)
Multiplies two quaternions, composing their rotations.
The result applies rhs first, then lhs.
public static Quaternion operator *(Quaternion lhs, Quaternion rhs)Parameters
lhsQuaternionrhsQuaternion
Returns
operator *(Quaternion, Vector3)
Rotates a Vector3 by this quaternion using the sandwich product:
v' = q * v * q⁻¹.
public static Vector3 operator *(Quaternion q, Vector3 v)Parameters
qQuaternionvVector3