Class WireMath
The codec arithmetic of 03-wire-protocol § 12 (decisions W1–W10): quantization, normalized values, angles, smallest-three quaternions, half floats and low-bit ticks, written so that C#, the TypeScript SDK and the engine produce bit-identical integer codes and bit-identical decoded doubles.
public static class WireMath
- Inheritance
-
WireMath
- Inherited Members
Remarks
The rules that make that true (W1). All arithmetic is binary64: a float32 input is widened first (exact) and a result is narrowed only after
decoding. Ties round half away from zero — never Round(double)'s default to-even, never floor(x + 0.5). Values are clamped in
double before any integer conversion. Only + − × ÷, Sqrt(double), Floor(double), Abs(double) and
comparisons appear; powers of two come from Pow2(int), built by doubling, never from Pow(double, double). Nothing here may call
Math.FusedMultiplyAdd or a MultiplyAddEstimate: a fused result differs in the last bit from the TypeScript one.
Operators evaluate left to right, one IEEE operation each, exactly as the formulas in § 12 are written. Reordering a product "for speed" changes the last bit and breaks the golden vectors — that is the point of having them.
Fields
CanonicalNaN
The one NaN a decoder produces: bits 0x7FF8000000000000. JavaScript has a single observable NaN, so a decoded NaN that kept its sign or payload
could never be bit-exact across languages. NaN is not it — its sign bit is set.
public static readonly double CanonicalNaN
Field Value
Sqrt1Over2
√½, identical to TypeScript's Math.SQRT1_2.
public static readonly double Sqrt1Over2
Field Value
Tau
2π, as C#'s Math.Tau and TypeScript's 2 * Math.PI both spell it.
public const double Tau = 6.283185307179586
Field Value
Methods
CanonicalizeNaN(double)
Replaces any NaN with CanonicalNaN.
public static double CanonicalizeNaN(double value)
Parameters
valuedoubleA decoded value.
Returns
- double
The value, or the canonical NaN.
DecodeAngle(int, int)
Decodes an angle: (q × 2π) / 2ᵇ.
public static double DecodeAngle(int q, int bits)
Parameters
Returns
- double
Radians in [−π, π).
DecodeHalf(ushort)
Decodes IEEE half bits, widened exactly.
public static double DecodeHalf(ushort bits)
Parameters
bitsushortThe half's bits.
Returns
- double
The value; every NaN pattern decodes as CanonicalNaN.
DecodeQuant(uint, double, double, int)
Decodes a quant code: min + q × step. Never clamps.
public static double DecodeQuant(uint q, double min, double max, int bits)
Parameters
quintThe code.
mindoubleThe declared minimum.
maxdoubleThe declared maximum.
bitsint8, 16, 24 or 32.
Returns
- double
The value, in [min, max − step].
DecodeQuantWithStep(uint, double, double)
Decodes a quant code with its step precomputed by QuantStep(double, double, int): the same operations, so the same bits.
public static double DecodeQuantWithStep(uint q, double min, double step)
Parameters
Returns
- double
The value.
DecodeQuat3(uint, Span<double>)
Decodes a smallest-three rotation into xyzw.
public static void DecodeQuat3(uint bits, Span<double> xyzw)
Parameters
DecodeSnorm(int, int)
Decodes a snorm: max(q / (2ᵇ⁻¹ − 1), −1).
public static double DecodeSnorm(int q, int bits)
Parameters
Returns
- double
A value in [−1, 1]; −1, 0 and 1 exact.
DecodeTickLo(ushort, uint)
Rebuilds an absolute tick from its low 16 bits against the frame's tick, assuming it is in the past and less than 2¹⁶ ticks old.
public static uint DecodeTickLo(ushort low, uint frameTick)
Parameters
Returns
- uint
The absolute tick.
DecodeUnorm(uint, int)
Decodes a unorm: q / (2ᵇ − 1) — a division, not a multiplication by the reciprocal, which differs in the last bit.
public static double DecodeUnorm(uint q, int bits)
Parameters
Returns
- double
A value in [0, 1]; 0 and 1 exact.
DecodeVec(int, double, int)
Decodes one vec component; the code −2ᵇ⁻¹ reads as −(2ᵇ⁻¹ − 1).
public static double DecodeVec(int q, double scale, int bits)
Parameters
Returns
- double
The value.
DecodeVel(int, int, int)
Decodes one vel axis to world units per tick: q × 2^unitExp, exact in binary64 (the unit is dyadic).
public static double DecodeVel(int q, int unitExp, int bits)
Parameters
Returns
- double
Displacement per tick.
EncodeAngle(double, int)
Encodes an angle as a two's-complement code over [−π, π).
public static int EncodeAngle(double theta, int bits)
Parameters
thetadoubleRadians; non-finite values, and values whose code would exceed 2⁵³ in magnitude, encode as 0.
bitsint8, 16, 24 or 32.
Returns
- int
The signed code, in [−2ᵇ⁻¹, 2ᵇ⁻¹).
EncodeHalf(double)
Converts a double to IEEE half bits directly (ties to even, overflow to infinity), with NaN canonicalized to 0x7E00.
public static ushort EncodeHalf(double value)
Parameters
valuedoubleThe value, in its source precision.
Returns
- ushort
The half's bits.
EncodeQuant(double, double, double, int)
Encodes a quant value (or one pos axis) over [min, max) at bits bits: step = (max − min) / 2ᵇ.
public static uint EncodeQuant(double v, double min, double max, int bits)
Parameters
vdoubleThe value; NaN, −∞ and anything below min encode as 0, anything at or above max − step/2 clamps to the top code.
mindoubleThe declared minimum (inclusive).
maxdoubleThe declared maximum (exclusive).
bitsint8, 16, 24 or 32.
Returns
- uint
The code, in [0, 2ᵇ − 1].
EncodeQuantWithStep(double, double, double, double)
EncodeQuant(double, double, double, int) with its step and top code computed once by the caller — the same operations on the same values, so the same code: a caller quantizing many values over one range divides once per value instead of twice.
public static uint EncodeQuantWithStep(double v, double min, double step, double top)
Parameters
vdoubleThe value.
mindoubleThe declared minimum.
stepdoubleThe quantum, exactly as QuantStep(double, double, int) computes it.
topdoubleThe top code,
2ᵇ − 1.
Returns
- uint
The code, in [0, top].
EncodeQuat3(double, double, double, double)
Encodes a rotation as smallest-three in 32 bits: index in bits 0–1, then three 10-bit signed components, ascending axis order.
public static uint EncodeQuat3(double x, double y, double z, double w)
Parameters
Returns
- uint
The 32-bit code.
EncodeSingle(double)
The single-precision bits a value encodes to: narrowing ties to even, NaN canonicalized to 0x7FC00000.
public static uint EncodeSingle(double value)
Parameters
valuedoubleThe value.
Returns
- uint
The single's bits.
EncodeSnorm(double, int)
Encodes a snorm: q = rha(clamp(v, −1, 1) × (2ᵇ⁻¹ − 1)).
public static int EncodeSnorm(double v, int bits)
Parameters
Returns
- int
The signed code.
EncodeUnorm(double, int)
Encodes a unorm: q = rhu(v × (2ᵇ − 1)), clamped to [0, 2ᵇ − 1].
public static uint EncodeUnorm(double v, int bits)
Parameters
Returns
- uint
The code.
EncodeVec(double, double, int)
Encodes one vec component: scale is one step; signed, clamped symmetrically to ±(2ᵇ⁻¹ − 1).
public static int EncodeVec(double v, double scale, int bits)
Parameters
Returns
- int
The signed code.
EncodeVel(double, int, int)
Encodes one vel axis (W5, typhon.3): displacement per tick in units of 2^unitExp metres per tick — an absolute unit, the same
in every realm — rounded half away from zero, signed, symmetric clamp.
public static int EncodeVel(double d, int unitExp, int bits)
Parameters
ddoubleDisplacement per tick, in world units; NaN encodes as 0.
unitExpintThe unit's binary exponent.
bitsint8, 16, 24 or 32.
Returns
- int
The signed code.
InterpolateAngle(double, double, double, int)
Interpolates two decoded angle values the short way round, in code space (03 § 6, W7): Δ = wrap_b(q1 − q0), then q0 + t × Δ, re-wrapped
into [−2ᵇ⁻¹, 2ᵇ⁻¹) and decoded.
public static double InterpolateAngle(double from, double to, double t, int bits)
Parameters
fromdoubleThe value at
t= 0, as the field decoded it.todoubleThe value at
t= 1, as the field decoded it.tdoubleThe fraction; outside [0, 1] it extrapolates along the same short way.
bitsintThe field's code width: 8, 16, 24 or 32.
Returns
- double
Radians in [−π, π).
Remarks
In code space rather than in radians so every SDK takes the same short way at exactly half a turn: Δ = −2ᵇ⁻¹ there, as the encoder's own wrap decides, where a radian wrap would have to pick a side of π itself.
InterpolateQuat3(ReadOnlySpan<double>, ReadOnlySpan<double>, double, Span<double>)
Interpolates two decoded quat3 rotations (03 § 6, W8): the shorter hemisphere — to negated when the dot product is negative —
then a linear interpolation, normalized. A zero result is the identity, as the encoder makes it.
public static void InterpolateQuat3(ReadOnlySpan<double> from, ReadOnlySpan<double> to, double t, Span<double> xyzw)
Parameters
fromReadOnlySpan<double>x, y, z, w at
t= 0.toReadOnlySpan<double>x, y, z, w at
t= 1.tdoubleThe fraction.
xyzwSpan<double>Receives x, y, z, w; may be
fromorto.
Pow2(int)
2ᵇ as an exact double, for b in [0, 64].
public static double Pow2(int b)
Parameters
bintThe exponent.
Returns
- double
2ᵇ.
QuantStep(double, double, int)
The quantization step of a quant or pos axis: (max − min) / 2ᵇ.
public static double QuantStep(double min, double max, int bits)
Parameters
Returns
- double
The step.
RoundHalfAwayFromZero(double)
Rounds half away from zero (rha).
public static double RoundHalfAwayFromZero(double x)
Parameters
xdoubleThe value.
Returns
- double
The nearest integer, ties away from zero.
SymmetricLimit(int)
The largest magnitude of a symmetric signed code: 2ᵇ⁻¹ − 1.
public static int SymmetricLimit(int bits)
Parameters
bitsint8, 16, 24 or 32.
Returns
- int
The limit.