Struct JQuaternion

Namespace

Jitter2.LinearMath

Assembly

Jitter2.dll

A structure representing a Quaternion: Q = xi + yj + z*k + w.
Uses the Hamilton convention where i² = j² = k² = ijk = -1.

public struct JQuaternion : IEquatable<JQuaternion>

Implements

IEquatable<JQuaternion>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Constructors

JQuaternion(float, in JVector)

Initializes a new instance of the JQuaternion struct.

public JQuaternion(float w, in JVector v)

Parameters

w float

The scalar (W) component.

v JVector

The vector (X, Y, Z) component.

JQuaternion(float, float, float, float)

A structure representing a Quaternion: Q = xi + yj + z*k + w.
Uses the Hamilton convention where i² = j² = k² = ijk = -1.

public JQuaternion(float x, float y, float z, float w)

Parameters

x float

y float

z float

w float

Fields

W

public float W

Field Value

float

X

public float X

Field Value

float

Y

public float Y

Field Value

float

Z

public float Z

Field Value

float

Properties

Identity

Gets the identity quaternion (0, 0, 0, 1).

public static JQuaternion Identity { get; }

Property Value

JQuaternion

Scalar

Gets the scalar part (w) of the quaternion.

public float Scalar { get; }

Property Value

float

Vector

Gets the vector part (x, y, z) of the quaternion.

public JVector Vector { get; }

Property Value

JVector

Methods

Add(in JQuaternion, in JQuaternion)

Adds two quaternions component-wise.

public static JQuaternion Add(in JQuaternion quaternion1, in JQuaternion quaternion2)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The second quaternion.

Returns

JQuaternion

The sum of the two quaternions.

Add(in JQuaternion, in JQuaternion, out JQuaternion)

Adds two quaternions component-wise.

public static void Add(in JQuaternion quaternion1, in JQuaternion quaternion2, out JQuaternion result)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The second quaternion.

result JQuaternion

Output: The sum of the two quaternions.

Conjugate()

Returns the conjugate of the quaternion.

public readonly JQuaternion Conjugate()

Returns

JQuaternion

The conjugate of the quaternion.

Remarks

The conjugate is defined as (-x, -y, -z, w).

Conjugate(in JQuaternion)

Returns the conjugate of a quaternion.

public static JQuaternion Conjugate(in JQuaternion value)

Parameters

value JQuaternion

The quaternion to conjugate.

Returns

JQuaternion

The conjugate of the quaternion.

Remarks

The conjugate is defined as (-x, -y, -z, w). For unit quaternions, the conjugate is equivalent to the inverse.

ConjugateMultiply(in JQuaternion, in JQuaternion)

Calculates conjugate(Q1) * Q2.

public static JQuaternion ConjugateMultiply(in JQuaternion quaternion1, in JQuaternion quaternion2)

Parameters

quaternion1 JQuaternion

The quaternion to conjugate and then multiply.

quaternion2 JQuaternion

The second quaternion.

Returns

JQuaternion

ConjugateMultiply(in JQuaternion, in JQuaternion, out JQuaternion)

Calculates conjugate(Q1) * Q2.

public static void ConjugateMultiply(in JQuaternion quaternion1, in JQuaternion quaternion2, out JQuaternion result)

Parameters

quaternion1 JQuaternion

The quaternion to conjugate and then multiply.

quaternion2 JQuaternion

The second quaternion.

result JQuaternion

Output: The resulting quaternion.

CreateFromAxisAngle(in JVector, float)

Creates a quaternion from a unit axis and an angle.

public static JQuaternion CreateFromAxisAngle(in JVector axis, float angle)

Parameters

axis JVector

The unit vector to rotate around (must be normalized).

angle float

The angle of rotation in radians.

Returns

JQuaternion

A unit quaternion representing the rotation.

Remarks

The axis must be normalized.

CreateFromMatrix(in JMatrix)

Creates a quaternion from a rotation matrix.

public static JQuaternion CreateFromMatrix(in JMatrix matrix)

Parameters

matrix JMatrix

The rotation matrix.

Returns

JQuaternion

The quaternion representing the rotation.

CreateFromMatrix(in JMatrix, out JQuaternion)

Creates a quaternion from a rotation matrix.

public static void CreateFromMatrix(in JMatrix matrix, out JQuaternion result)

Parameters

matrix JMatrix

The rotation matrix.

result JQuaternion

Output: The quaternion representing the rotation.

CreateFromToRotation(JVector, JVector)

Creates a quaternion that rotates the unit vector from into the unit vector to.

public static JQuaternion CreateFromToRotation(JVector from, JVector to)

Parameters

from JVector

Source direction (must be unit length).

to JVector

Target direction (must be unit length).

Returns

JQuaternion

A unit quaternion representing the shortest rotation.

Remarks

This calculation relies on the half-angle formula. If the vectors are parallel (dot ≈ 1), Identity is returned. If the vectors are opposite (dot ≈ -1), a rotation of 180° (π radians) around an arbitrary orthogonal axis is returned.

CreateRotationX(float)

Creates a quaternion representing a rotation around the X-axis.

public static JQuaternion CreateRotationX(float radians)

Parameters

radians float

The angle of rotation in radians.

Returns

JQuaternion

The resulting quaternion.

CreateRotationY(float)

Creates a quaternion representing a rotation around the Y-axis.

public static JQuaternion CreateRotationY(float radians)

Parameters

radians float

The angle of rotation in radians.

Returns

JQuaternion

The resulting quaternion.

CreateRotationZ(float)

Creates a quaternion representing a rotation around the Z-axis.

public static JQuaternion CreateRotationZ(float radians)

Parameters

radians float

The angle of rotation in radians.

Returns

JQuaternion

The resulting quaternion.

Dot(in JQuaternion, in JQuaternion)

Calculates the dot product of two quaternions.

public static float Dot(in JQuaternion quaternion1, in JQuaternion quaternion2)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The second quaternion.

Returns

float

The dot product.

Equals(JQuaternion)

Indicates whether the current object is equal to another object of the same type.

public readonly bool Equals(JQuaternion other)

Parameters

other JQuaternion

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override readonly bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetBasisX()

Calculates the transformation of the X-axis (1, 0, 0) by this quaternion.

public readonly JVector GetBasisX()

Returns

JVector

The transformed vector.

Remarks

Mathematically equivalent to q · (1,0,0) · q⁻¹.
Result: [1 - 2(y² + z²), 2(xy + zw), 2(xz - yw)]

GetBasisY()

Calculates the transformation of the Y-axis (0, 1, 0) by this quaternion.

public readonly JVector GetBasisY()

Returns

JVector

The transformed vector.

Remarks

Mathematically equivalent to q · (0,1,0) · q⁻¹.
Result: [2(xy - zw), 1 - 2(x² + z²), 2(yz + xw)]

GetBasisZ()

Calculates the transformation of the Z-axis (0, 0, 1) by this quaternion.

public readonly JVector GetBasisZ()

Returns

JVector

The transformed vector.

Remarks

Mathematically equivalent to q · (0,0,1) · q⁻¹.
Result: [2(xz + yw), 2(yz - xw), 1 - 2(x² + y²)]

GetHashCode()

Returns the hash code for this instance.

public override readonly int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

Inverse(in JQuaternion)

Returns the inverse of a quaternion.

public static JQuaternion Inverse(in JQuaternion value)

Parameters

value JQuaternion

Returns

JQuaternion

Remarks

Unlike Conjugate(in JQuaternion), this handles non-unit quaternions correctly by dividing by the squared length.

Length()

Calculates the Euclidean length of the quaternion.

public readonly float Length()

Returns

float

The length (magnitude).

LengthSquared()

Calculates the squared Euclidean length of the quaternion.

public readonly float LengthSquared()

Returns

float

The squared length.

Lerp(in JQuaternion, in JQuaternion, float)

Linearly interpolates between two quaternions and normalizes the result.

public static JQuaternion Lerp(in JQuaternion quaternion1, in JQuaternion quaternion2, float amount)

Parameters

quaternion1 JQuaternion

Source quaternion.

quaternion2 JQuaternion

Target quaternion.

amount float

Weight of the interpolation.

Returns

JQuaternion

The interpolated unit quaternion.

Multiply(in JQuaternion, in JQuaternion)

Multiplies two quaternions (Hamilton Product).

public static JQuaternion Multiply(in JQuaternion quaternion1, in JQuaternion quaternion2)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The second quaternion.

Returns

JQuaternion

The product of the two quaternions.

Remarks

Non-commutative. Q1 * Q2 represents the rotation Q2 followed by Q1 (local frame) or Q1 followed by Q2 (global frame).

Multiply(in JQuaternion, in JQuaternion, out JQuaternion)

Multiplies two quaternions.

public static void Multiply(in JQuaternion quaternion1, in JQuaternion quaternion2, out JQuaternion result)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The second quaternion.

result JQuaternion

Output: The product of the two quaternions.

Multiply(in JQuaternion, float)

Multiplies a quaternion by a scalar factor.

public static JQuaternion Multiply(in JQuaternion quaternion1, float scaleFactor)

Parameters

quaternion1 JQuaternion

The quaternion.

scaleFactor float

The scalar factor.

Returns

JQuaternion

The scaled quaternion.

Multiply(in JQuaternion, float, out JQuaternion)

Multiplies a quaternion by a scalar factor.

public static void Multiply(in JQuaternion quaternion1, float scaleFactor, out JQuaternion result)

Parameters

quaternion1 JQuaternion

The quaternion.

scaleFactor float

The scalar factor.

result JQuaternion

Output: The scaled quaternion.

MultiplyConjugate(in JQuaternion, in JQuaternion)

Calculates Q1 * conjugate(Q2).

public static JQuaternion MultiplyConjugate(in JQuaternion quaternion1, in JQuaternion quaternion2)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The quaternion to conjugate.

Returns

JQuaternion

MultiplyConjugate(in JQuaternion, in JQuaternion, out JQuaternion)

Calculates Q1 * conjugate(Q2).

public static void MultiplyConjugate(in JQuaternion quaternion1, in JQuaternion quaternion2, out JQuaternion result)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The quaternion to conjugate.

result JQuaternion

Output: The resulting quaternion.

Normalize()

Normalizes the quaternion to unit length.

[Obsolete("In-place Normalize() is deprecated; use the static Normalize method or NormalizeInPlace.")]
public void Normalize()

Normalize(in JQuaternion)

Returns a normalized version of the quaternion.

public static JQuaternion Normalize(in JQuaternion value)

Parameters

value JQuaternion

The source quaternion.

Returns

JQuaternion

Normalize(in JQuaternion, out JQuaternion)

Returns a normalized version of the quaternion.

public static void Normalize(in JQuaternion value, out JQuaternion result)

Parameters

value JQuaternion

The source quaternion.

result JQuaternion

Output: The normalized unit quaternion.

NormalizeInPlace(ref JQuaternion)

Normalizes the provided quaternion structure in place.

public static void NormalizeInPlace(ref JQuaternion quaternion)

Parameters

quaternion JQuaternion

The quaternion to normalize.

Slerp(in JQuaternion, in JQuaternion, float)

Interpolates between two quaternions using Spherical Linear Interpolation (SLERP).

public static JQuaternion Slerp(in JQuaternion quaternion1, in JQuaternion quaternion2, float amount)

Parameters

quaternion1 JQuaternion

Source quaternion.

quaternion2 JQuaternion

Target quaternion.

amount float

Weight of the interpolation.

Returns

JQuaternion

The interpolated quaternion.

Subtract(in JQuaternion, in JQuaternion)

Subtracts the second quaternion from the first component-wise.

public static JQuaternion Subtract(in JQuaternion quaternion1, in JQuaternion quaternion2)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The second quaternion.

Returns

JQuaternion

The difference of the two quaternions.

Subtract(in JQuaternion, in JQuaternion, out JQuaternion)

Subtracts the second quaternion from the first component-wise.

public static void Subtract(in JQuaternion quaternion1, in JQuaternion quaternion2, out JQuaternion result)

Parameters

quaternion1 JQuaternion

The first quaternion.

quaternion2 JQuaternion

The second quaternion.

result JQuaternion

Output: The difference of the two quaternions.

ToAxisAngle(JQuaternion, out JVector, out float)

Decomposes a unit quaternion into an axis and an angle.

public static void ToAxisAngle(JQuaternion quaternion, out JVector axis, out float angle)

Parameters

quaternion JQuaternion

The unit quaternion to decompose.

axis JVector

Output: The unit rotation axis.

angle float

Output: The rotation angle (radians).

Remarks

Assumes quaternion is normalized. Returns the shortest arc (angle in [0, π]).

ToString()

Returns a string representing the quaternion in the format X=..., Y=..., Z=..., W=....

public override readonly string ToString()

Returns

string

UnsafeAs<T>()

Reinterprets the bits of this JQuaternion as T.

public T UnsafeAs<T>() where T : unmanaged

Returns

T

The reinterpreted value.

Type Parameters

T

The target unmanaged type.

Remarks

Valid only if T has identical size and compatible layout. Memory order is X, Y, Z, W (W is last).

UnsafeFrom<T>(in T)

Reinterprets the bits of value as a JQuaternion.

public static JQuaternion UnsafeFrom<T>(in T value) where T : unmanaged

Parameters

value T

The value to reinterpret.

Returns

JQuaternion

The reinterpreted quaternion.

Type Parameters

T

The source unmanaged type.

Remarks

Valid only if T has identical size and compatible layout. Expects memory order X, Y, Z, W (W is last).

Operators

operator +(in JQuaternion, in JQuaternion)

Adds two quaternions component-wise.

public static JQuaternion operator +(in JQuaternion value1, in JQuaternion value2)

Parameters

value1 JQuaternion

value2 JQuaternion

Returns

JQuaternion

operator ==(JQuaternion, JQuaternion)

public static bool operator ==(JQuaternion left, JQuaternion right)

Parameters

left JQuaternion

right JQuaternion

Returns

bool

implicit operator Quaternion(in JQuaternion)

public static implicit operator Quaternion(in JQuaternion q)

Parameters

q JQuaternion

Returns

Quaternion

implicit operator JQuaternion(in Quaternion)

public static implicit operator JQuaternion(in Quaternion q)

Parameters

q Quaternion

Returns

JQuaternion

implicit operator JQuaternion((float x, float y, float z, float w))

public static implicit operator JQuaternion((float x, float y, float z, float w) tuple)

Parameters

tuple (float x, float y, float z, float w)

Returns

JQuaternion

operator !=(JQuaternion, JQuaternion)

public static bool operator !=(JQuaternion left, JQuaternion right)

Parameters

left JQuaternion

right JQuaternion

Returns

bool

operator *(in JQuaternion, in JQuaternion)

Multiplies two quaternions (Hamilton Product).

public static JQuaternion operator *(in JQuaternion value1, in JQuaternion value2)

Parameters

value1 JQuaternion

value2 JQuaternion

Returns

JQuaternion

operator *(in JQuaternion, float)

Scales a quaternion by a factor.

public static JQuaternion operator *(in JQuaternion value1, float value2)

Parameters

value1 JQuaternion

value2 float

Returns

JQuaternion

operator *(float, in JQuaternion)

Scales a quaternion by a factor.

public static JQuaternion operator *(float value1, in JQuaternion value2)

Parameters

value1 float

value2 JQuaternion

Returns

JQuaternion

operator -(in JQuaternion, in JQuaternion)

Subtracts the second quaternion from the first component-wise.

public static JQuaternion operator -(in JQuaternion value1, in JQuaternion value2)

Parameters

value1 JQuaternion

value2 JQuaternion

Returns

JQuaternion

operator -(in JQuaternion)

Flips the sign of each component of the quaternion.

public static JQuaternion operator -(in JQuaternion value)

Parameters

value JQuaternion

Returns

JQuaternion