Struct FixedQuaternion

Namespace

FixedMathSharp

Assembly

FixedMathSharp.dll

Represents a quaternion (x, y, z, w) with fixed-point numbers. Quaternions are useful for representing rotations and can be used to perform smooth rotations and avoid gimbal lock.

[MemoryPackable(GenerateType.Object)]
public struct FixedQuaternion : IEquatable<FixedQuaternion>, ISpanFormattable, IFormattable, IMemoryPackable<FixedQuaternion>, IMemoryPackFormatterRegister

Implements

IEquatable<FixedQuaternion>

ISpanFormattable

IFormattable

IMemoryPackable<FixedQuaternion>

IMemoryPackFormatterRegister

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Extension Methods

FixedQuaternionExtensions.Angle(FixedQuaternion, FixedQuaternion)

FixedQuaternionExtensions.Dot(FixedQuaternion, FixedQuaternion)

FixedQuaternionExtensions.FuzzyEqual(FixedQuaternion, FixedQuaternion, Fixed64?)

FixedQuaternionExtensions.FuzzyEqualAbsolute(FixedQuaternion, FixedQuaternion, Fixed64)

FixedQuaternionExtensions.Lerp(FixedQuaternion, FixedQuaternion, Fixed64)

FixedQuaternionExtensions.QuaternionLog(FixedQuaternion)

FixedQuaternionExtensions.Slerp(FixedQuaternion, FixedQuaternion, Fixed64)

FixedQuaternionExtensions.ToAngularVelocity(FixedQuaternion, FixedQuaternion, Fixed64)

Remarks

Direction-oriented quaternion APIs use FixedMathSharp's canonical 3D convention: +X right, +Y up, and +Z forward. Convert external engine or tool directions before calling these APIs when their semantic basis differs.

Constructors

FixedQuaternion(Fixed64, Fixed64, Fixed64, Fixed64)

Creates a new FixedQuaternion with the specified components.

public FixedQuaternion(Fixed64 x, Fixed64 y, Fixed64 z, Fixed64 w)

Parameters

x Fixed64

y Fixed64

z Fixed64

w Fixed64

Fields

W

Represents the W component of the vector as a fixed-point value.

[JsonInclude]
[MemoryPackOrder(3)]
public Fixed64 W

Field Value

Fixed64

X

Represents the X component of the vector as a fixed-point value.

[JsonInclude]
[MemoryPackOrder(0)]
public Fixed64 X

Field Value

Fixed64

Y

Represents the Y component of the vector as a fixed-point value.

[JsonInclude]
[MemoryPackOrder(1)]
public Fixed64 Y

Field Value

Fixed64

Z

Represents the Z component of the vector as a fixed-point value.

[JsonInclude]
[MemoryPackOrder(2)]
public Fixed64 Z

Field Value

Fixed64

Properties

EulerAngles

Returns the Euler angles (in degrees) of this quaternion.

[JsonIgnore]
[MemoryPackIgnore]
public Vector3d EulerAngles { get; set; }

Property Value

Vector3d

Identity

Identity quaternion (0, 0, 0, 1).

public static FixedQuaternion Identity { get; }

Property Value

FixedQuaternion

this[int]

Gets or sets the component value at the specified index.

[JsonIgnore]
[MemoryPackIgnore]
public Fixed64 this[int index] { get; set; }

Parameters

index int

The zero-based index of the component to access. Valid values are 0 (x), 1 (y), 2 (z), and 3 (w).

Property Value

Fixed64

The value of the component at the specified index.

Remarks

Index 0 corresponds to the x component, 1 to y, 2 to z, and 3 to w.

Exceptions

IndexOutOfRangeException

Thrown when the specified index is less than 0 or greater than 3.

Magnitude

Gets the magnitude of this quaternion.

[JsonIgnore]
[MemoryPackIgnore]
public Fixed64 Magnitude { get; }

Property Value

Fixed64

MagnitudeSquared

Gets the squared magnitude of this quaternion.

[JsonIgnore]
[MemoryPackIgnore]
public Fixed64 MagnitudeSquared { get; }

Property Value

Fixed64

Normalized

Normalized version of this quaternion.

[JsonIgnore]
[MemoryPackIgnore]
public FixedQuaternion Normalized { get; }

Property Value

FixedQuaternion

Zero

Empty quaternion (0, 0, 0, 0).

public static FixedQuaternion Zero { get; }

Property Value

FixedQuaternion

Methods

Angle(FixedQuaternion, FixedQuaternion)

Returns the angle in degrees between two rotations a and b.

public static Fixed64 Angle(FixedQuaternion a, FixedQuaternion b)

Parameters

a FixedQuaternion

The first rotation.

b FixedQuaternion

The second rotation.

Returns

Fixed64

The angle in degrees between the two rotations.

AngleAxis(Fixed64, Vector3d)

Creates a quaternion from an angle and axis.

public static FixedQuaternion AngleAxis(Fixed64 angle, Vector3d axis)

Parameters

angle Fixed64

The angle in degrees.

axis Vector3d

The axis to rotate around. Nonzero inputs are normalized; zero returns identity.

Returns

FixedQuaternion

A quaternion representing the rotation.

Conjugate()

Returns the conjugate of this quaternion (inverses the rotational effect).

public FixedQuaternion Conjugate()

Returns

FixedQuaternion

Deconstruct(out Fixed64, out Fixed64, out Fixed64, out Fixed64)

Deconstructs the quaternion into its four Fixed64 components.

public void Deconstruct(out Fixed64 x, out Fixed64 y, out Fixed64 z, out Fixed64 w)

Parameters

x Fixed64

y Fixed64

z Fixed64

w Fixed64

Deconstruct(out double, out double, out double, out double)

Deconstructs the quaternion into its four double components.

public void Deconstruct(out double x, out double y, out double z, out double w)

Parameters

x double

y double

z double

w double

Deconstruct(out int, out int, out int, out int)

Deconstructs the quaternion into its four int components.

public void Deconstruct(out int x, out int y, out int z, out int w)

Parameters

x int

y int

z int

w int

Deconstruct(out long, out long, out long, out long)

Deconstructs the quaternion into its four long components.

public void Deconstruct(out long x, out long y, out long z, out long w)

Parameters

x long

y long

z long

w long

Divide(FixedQuaternion, FixedQuaternion)

Divides one quaternion by another using inverse quaternion multiplication.

public static FixedQuaternion Divide(FixedQuaternion dividend, FixedQuaternion divisor)

Parameters

dividend FixedQuaternion

divisor FixedQuaternion

Returns

FixedQuaternion

Remarks

This is equivalent to dividend * Inverse(divisor).

Exceptions

InvalidOperationException

Thrown when divisor is not invertible.

Dot(FixedQuaternion, FixedQuaternion)

Calculates the dot product of two quaternions.

public static Fixed64 Dot(FixedQuaternion a, FixedQuaternion b)

Parameters

a FixedQuaternion

The first quaternion.

b FixedQuaternion

The second quaternion.

Returns

Fixed64

The dot product of the two quaternions.

Equals(FixedQuaternion)

public bool Equals(FixedQuaternion other)

Parameters

other FixedQuaternion

Returns

bool

Equals(object?)

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

FromAxisAngle(Vector3d, Fixed64)

Creates a quaternion representing a rotation around a specified axis by a given angle.

public static FixedQuaternion FromAxisAngle(Vector3d axis, Fixed64 angle)

Parameters

axis Vector3d

The axis to rotate around. Nonzero inputs are normalized; zero returns identity.

angle Fixed64

The rotation angle in radians.

Returns

FixedQuaternion

A quaternion representing the rotation.

FromDirection(Vector3d)

Creates a quaternion representing the rotation needed to align canonical +Z forward with the given direction.

public static FixedQuaternion FromDirection(Vector3d direction)

Parameters

direction Vector3d

The target direction vector.

Returns

FixedQuaternion

A quaternion representing the rotation to align with the direction.

Remarks

Forward returns Identity. If an external API names -Z as forward, convert that direction into the canonical convention before calling this method.

FromEulerAngles(Fixed64, Fixed64, Fixed64)

Converts Euler angles (pitch, yaw, roll) to a quaternion and normalizes the result afterwards. Assumes the input angles are in radians.

public static FixedQuaternion FromEulerAngles(Fixed64 pitch, Fixed64 yaw, Fixed64 roll)

Parameters

pitch Fixed64

yaw Fixed64

roll Fixed64

Returns

FixedQuaternion

Remarks

The order of operations is YXZ or yaw-pitch-roll

FromEulerAnglesInDegrees(Fixed64, Fixed64, Fixed64)

Assume the input angles are in degrees and converts them to radians before calling FromEulerAngles(Fixed64, Fixed64, Fixed64)

public static FixedQuaternion FromEulerAnglesInDegrees(Fixed64 pitch, Fixed64 yaw, Fixed64 roll)

Parameters

pitch Fixed64

yaw Fixed64

roll Fixed64

Returns

FixedQuaternion

FromMatrix(Fixed3x3)

Converts a rotation matrix into a quaternion representation.

public static FixedQuaternion FromMatrix(Fixed3x3 matrix)

Parameters

matrix Fixed3x3

The rotation matrix to convert.

Returns

FixedQuaternion

A quaternion representing the same rotation as the matrix.

FromMatrix(Fixed4x4)

Converts a rotation matrix (upper-left 3x3 part of a 4x4 matrix) into a quaternion representation.

public static FixedQuaternion FromMatrix(Fixed4x4 matrix)

Parameters

matrix Fixed4x4

The 4x4 matrix containing the rotation component.

Returns

FixedQuaternion

A quaternion representing the same rotation as the matrix.

Remarks

Extracts the upper-left 3x3 rotation part of the 4x4

GetHashCode()

public override int GetHashCode()

Returns

int

GetMagnitude(FixedQuaternion)

Calculates the magnitude (or length) of the specified quaternion.

public static Fixed64 GetMagnitude(FixedQuaternion q)

Parameters

q FixedQuaternion

The quaternion for which to compute the magnitude.

Returns

Fixed64

The magnitude of the quaternion as a Fixed64 value. Returns 0 if the quaternion is the zero quaternion.

Remarks

Component squares are accumulated exactly and the integer square root is rounded once. Only an unrepresentable rounded result saturates.

GetNormalized(FixedQuaternion)

Normalizes the quaternion to a unit quaternion.

public static FixedQuaternion GetNormalized(FixedQuaternion q)

Parameters

q FixedQuaternion

Returns

FixedQuaternion

Inverse()

Returns the inverse of this quaternion.

public FixedQuaternion Inverse()

Returns

FixedQuaternion

IsNormalized()

Checks whether this nonzero quaternion's squared magnitude is within epsilon of one.

public bool IsNormalized()

Returns

bool

Lerp(FixedQuaternion, FixedQuaternion, Fixed64)

Performs a simple linear interpolation between the components of the input quaternions

public static FixedQuaternion Lerp(FixedQuaternion a, FixedQuaternion b, Fixed64 t)

Parameters

a FixedQuaternion

b FixedQuaternion

t Fixed64

Returns

FixedQuaternion

LookRotation(Vector3d, Vector3d?)

Creates a quaternion whose canonical forward direction aligns with the specified direction.

public static FixedQuaternion LookRotation(Vector3d forward, Vector3d? upwards = null)

Parameters

forward Vector3d

The forward direction vector.

upwards Vector3d?

The upwards direction vector (optional, default: Vector3d.Up).

Returns

FixedQuaternion

A quaternion representing the rotation from one direction to another.

Remarks

The forward and upwards vectors are expressed in FixedMathSharp's canonical basis: +X right, +Y up, and +Z forward. Use CoordinateConvention3d or adapter-specific basis conversion before calling this method when external APIs use different semantic axes.

NormalizeInPlace()

Normalizes this quaternion in place.

public FixedQuaternion NormalizeInPlace()

Returns

FixedQuaternion

QuaternionLog(FixedQuaternion)

Computes the logarithm of a quaternion, which represents the rotational displacement. This is useful for interpolation and angular velocity calculations.

public static Vector3d QuaternionLog(FixedQuaternion q)

Parameters

q FixedQuaternion

The quaternion to compute the logarithm of.

Returns

Vector3d

A Vector3d representing the logarithm of the quaternion (axis-angle representation).

Remarks

The logarithm of a unit quaternion is given by: log(q) = (θ * v̂), where:

• θ = 2 * acos(w) is the rotation angle.
• v̂ = (x, y, z) / ||(x, y, z)|| is the unit vector representing the axis of rotation. If the quaternion is close to identity, the function returns a zero vector to avoid numerical instability.

Rotate(Vector3d)

Rotates a vector by this quaternion.

public Vector3d Rotate(Vector3d v)

Parameters

v Vector3d

Returns

Vector3d

Rotated(Fixed64, Fixed64, Vector3d?)

Rotates this quaternion by a given angle around a specified axis (default: Y-axis).

public FixedQuaternion Rotated(Fixed64 sin, Fixed64 cos, Vector3d? axis = null)

Parameters

sin Fixed64

Sine of the rotation angle.

cos Fixed64

Cosine of the rotation angle.

axis Vector3d?

The axis to rotate around (default: Vector3d.Up).

Returns

FixedQuaternion

A new quaternion representing the rotated result.

Set(Fixed64, Fixed64, Fixed64, Fixed64)

Set x, y, z and w components of an existing Quaternion.

public void Set(Fixed64 newX, Fixed64 newY, Fixed64 newZ, Fixed64 newW)

Parameters

newX Fixed64

newY Fixed64

newZ Fixed64

newW Fixed64

Slerp(FixedQuaternion, FixedQuaternion, Fixed64)

Calculates the spherical linear interpolation, which results in a smoother and more accurate rotation interpolation

public static FixedQuaternion Slerp(FixedQuaternion a, FixedQuaternion b, Fixed64 t)

Parameters

a FixedQuaternion

b FixedQuaternion

t Fixed64

Returns

FixedQuaternion

ToAngularVelocity(FixedQuaternion, FixedQuaternion, Fixed64)

Computes the angular velocity required to move from previousRotation to currentRotation over a given time step.

public static Vector3d ToAngularVelocity(FixedQuaternion currentRotation, FixedQuaternion previousRotation, Fixed64 deltaTime)

Parameters

currentRotation FixedQuaternion

The current orientation as a quaternion.

previousRotation FixedQuaternion

The previous orientation as a quaternion.

deltaTime Fixed64

The time step over which the rotation occurs.

Returns

Vector3d

A Vector3d representing the angular velocity (in radians per second).

Remarks

This function calculates the change in rotation over deltaTime and converts it into angular velocity.

• First, it computes the relative rotation: rotationDelta = currentRotation * previousRotation.Inverse().
• Then, it applies QuaternionLog(rotationDelta) to extract the axis-angle representation.
• Finally, it divides by deltaTime to compute the angular velocity.

ToDirection()

Converts this FixedQuaternion to the rotated canonical forward direction.

public Vector3d ToDirection()

Returns

Vector3d

A Vector3d representing the rotated canonical forward direction.

Remarks

The identity quaternion returns Forward because FixedMathSharp's canonical 3D forward direction is +Z.

ToEulerAngles()

Converts this quaternion to Euler angles in degrees. Returns angles as (pitch, yaw, roll), where: pitch = rotation around X yaw = rotation around Y roll = rotation around Z

The extraction matches FromEulerAngles(), which composes rotations in YXZ order: q = qy * qx * qz

public Vector3d ToEulerAngles()

Returns

Vector3d

ToMatrix3x3()

Converts the quaternion into a 3x3 rotation matrix.

public Fixed3x3 ToMatrix3x3()

Returns

Fixed3x3

A FixedMatrix3x3 representing the same rotation as the quaternion.

Remarks

Every nonzero scalar multiple represents the same rotation. The zero quaternion converts to Identity.

ToString()

Returns a string that represents the current object in the format "(x, y, z, w)".

public override string ToString()

Returns

string

A string containing the values of the object formatted as a tuple.

ToString(string?, IFormatProvider?)

Returns a string that represents the current object in the format "(x, y, z, w)".

public string ToString(string? format, IFormatProvider? formatProvider)

Parameters

format string

formatProvider IFormatProvider

Returns

string

TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider?)

Formats this quaternion into the provided destination buffer.

public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider)

Parameters

destination Span<char>

charsWritten int

format ReadOnlySpan<char>

provider IFormatProvider

Returns

bool

TryGetRelativeOffset(Vector3d, Vector3d, Vector3d, Vector3d, out Vector3d)

Attempts to obtain the exact relative offset firstOrigin + firstOffset - secondOrigin - Rotate(secondLocalPoint).

public bool TryGetRelativeOffset(Vector3d firstOrigin, Vector3d firstOffset, Vector3d secondOrigin, Vector3d secondLocalPoint, out Vector3d result)

Parameters

firstOrigin Vector3d

firstOffset Vector3d

secondOrigin Vector3d

secondLocalPoint Vector3d

result Vector3d

Returns

bool

Remarks

No rotated point or intermediate sum is narrowed independently. The zero quaternion preserves the legacy zero-rotation-result contract.

TryInverseTransformScaledPoint(Vector3d, Vector3d, Vector3d, out Vector3d)

Attempts to inverse-transform a world point by this rotation, a world origin, and a component scale with one final round-half-to-even conversion per local component.

public bool TryInverseTransformScaledPoint(Vector3d origin, Vector3d worldPoint, Vector3d scale, out Vector3d result)

Parameters

origin Vector3d

The world-space origin of the scaled local frame.

worldPoint Vector3d

The world-space point to inverse-transform.

scale Vector3d

The component scale of the local frame.

result Vector3d

The local-space point on success; otherwise zero.

Returns

bool

true when this quaternion is nonzero, every scale component is nonzero, and every final local coordinate is representable; otherwise false.

Remarks

Computes InverseRotate(worldPoint - origin) / scale without narrowing the world offset or rotated point independently. A zero quaternion or any zero scale component returns false.

TryRotate(Vector3d, out Vector3d)

Attempts to rotate a vector using the quaternion's exact scale-invariant rational basis.

public bool TryRotate(Vector3d vector, out Vector3d result)

Parameters

vector Vector3d

result Vector3d

Returns

bool

true when every final component is representable; otherwise, false and result is default.

Remarks

Each result component is rounded once after the complete linear combination. The zero quaternion preserves the legacy Rotate(Vector3d) result of zero.

TryTransformPoint(Vector3d, Vector3d, Vector3d, out Vector3d)

Attempts to transform a local point by this rotation and add two world origins with one final round-half-to-even conversion per component.

public bool TryTransformPoint(Vector3d firstOrigin, Vector3d secondOrigin, Vector3d localPoint, out Vector3d result)

Parameters

firstOrigin Vector3d

secondOrigin Vector3d

localPoint Vector3d

result Vector3d

Returns

bool

Remarks

The zero quaternion preserves the legacy rotation contract and returns the exact sum of the two origins.

TryTransformPoint(Vector3d, Vector3d, out Vector3d)

Attempts to transform a local point by this rotation and a world origin with one final round-half-to-even conversion per component.

public bool TryTransformPoint(Vector3d origin, Vector3d localPoint, out Vector3d result)

Parameters

origin Vector3d

localPoint Vector3d

result Vector3d

Returns

bool

Remarks

The zero quaternion preserves the legacy rotation contract and returns origin.

TryTransformScaledPoint(Vector3d, Vector3d, Vector3d, Vector3d, out Vector3d)

Attempts to transform a component-scaled local point plus an unscaled local displacement by this rotation and a world origin with one final round-half-to-even conversion per component.

public bool TryTransformScaledPoint(Vector3d origin, Vector3d localPoint, Vector3d scale, Vector3d localDisplacement, out Vector3d result)

Parameters

origin Vector3d

localPoint Vector3d

scale Vector3d

localDisplacement Vector3d

result Vector3d

Returns

bool

Remarks

Computes origin + Rotate(scale * localPoint + localDisplacement) without narrowing the scaled point, local sum, or rotated offset independently. The zero quaternion preserves the legacy rotation contract and returns origin.

TryTransformScaledPoint(Vector3d, Vector3d, Vector3d, out Vector3d)

Attempts to transform a component-scaled local point by this rotation and a world origin with one final round-half-to-even conversion per component.

public bool TryTransformScaledPoint(Vector3d origin, Vector3d localPoint, Vector3d scale, out Vector3d result)

Parameters

origin Vector3d

localPoint Vector3d

scale Vector3d

result Vector3d

Returns

bool

Operators

operator +(FixedQuaternion, FixedQuaternion)

Adds two quaternions component-wise and returns the resulting quaternion.

public static FixedQuaternion operator +(FixedQuaternion q1, FixedQuaternion q2)

Parameters

q1 FixedQuaternion

The first quaternion to add.

q2 FixedQuaternion

The second quaternion to add.

Returns

FixedQuaternion

A new FixedQuaternion whose components are the sums of the corresponding components of q1 and q2.

Remarks

This operation performs a simple component-wise addition.

operator /(FixedQuaternion, Fixed64)

Divides each component of the specified quaternion by the given scalar value.

public static FixedQuaternion operator /(FixedQuaternion q, Fixed64 scalar)

Parameters

q FixedQuaternion

The quaternion whose components are to be divided.

scalar Fixed64

The scalar value by which to divide each component of the quaternion.

Returns

FixedQuaternion

A new FixedQuaternion whose components are the result of dividing the corresponding components of the input quaternion by the scalar value.

Remarks

Division by zero will result in an exception or undefined behavior.

operator ==(FixedQuaternion, FixedQuaternion)

Determines whether two FixedQuaternion instances are equal.

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

Parameters

left FixedQuaternion

right FixedQuaternion

Returns

bool

operator !=(FixedQuaternion, FixedQuaternion)

Determines whether two FixedQuaternion instances are not equal.

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

Parameters

left FixedQuaternion

right FixedQuaternion

Returns

bool

operator *(Fixed64, FixedQuaternion)

Multiplies each component of the specified quaternion by the given scalar value.

public static FixedQuaternion operator *(Fixed64 scalar, FixedQuaternion q)

Parameters

scalar Fixed64

The scalar value by which to multiply each component of the quaternion.

q FixedQuaternion

The quaternion whose components are to be multiplied.

Returns

FixedQuaternion

A new FixedQuaternion whose components are the result of multiplying the corresponding components of the input quaternion by the scalar value.

operator *(FixedQuaternion, Fixed64)

Multiplies each component of the specified quaternion by the given scalar value.

public static FixedQuaternion operator *(FixedQuaternion q, Fixed64 scalar)

Parameters

q FixedQuaternion

The quaternion whose components are to be multiplied.

scalar Fixed64

The scalar value by which to multiply each component of the quaternion.

Returns

FixedQuaternion

A new FixedQuaternion whose components are the result of multiplying the corresponding components of the input quaternion by the scalar value.

operator *(FixedQuaternion, FixedQuaternion)

Multiplies two quaternions, combining their rotations into a single quaternion.

public static FixedQuaternion operator *(FixedQuaternion a, FixedQuaternion b)

Parameters

a FixedQuaternion

The first quaternion to multiply.

b FixedQuaternion

The second quaternion to multiply.

Returns

FixedQuaternion

A new FixedQuaternion representing the combined rotation of the two input quaternions.

Remarks

Quaternion multiplication is not commutative; the order of operands affects the result. This operation is commonly used to concatenate rotations.

operator -(FixedQuaternion, FixedQuaternion)

Subtracts two quaternions component-wise and returns the resulting quaternion.

public static FixedQuaternion operator -(FixedQuaternion q1, FixedQuaternion q2)

Parameters

q1 FixedQuaternion

q2 FixedQuaternion

Returns

FixedQuaternion

Remarks

This operation performs component-wise subtraction.

operator -(FixedQuaternion)

Negates each component of the specified quaternion.

public static FixedQuaternion operator -(FixedQuaternion q)

Parameters

q FixedQuaternion

Returns

FixedQuaternion