Vector, Matrix and MathHelper numerics: interpolation, clamping and degenerate inputs

CNA snapshot 3b43bd86  ·  Deep Dives › Framework core  ·  source links pinned to 3b43bd86

This page describes what CNA's vector, matrix and MathHelper functions compute in the cases a method name leaves open: amounts outside [0, 1], inverted ranges, NaN and signed-zero operands, zero-length vectors, singular matrices and degenerate camera inputs. It also compares each behaviour with the genuine XNA 4.0 implementation, because several functions with the same name compute differently in MathHelper and in the vector types. It is for gameplay and tools programmers who need predictable numbers, and for porters matching an XNA game's results. The bit-level precision story (which products are accumulated wider than float to match XNA's x87 arithmetic) is maintained on Math internals and summarised at the end.

Operation groups and what each promises

MathHelper::Lerp and the vectors' Lerp use the form a + (b − a)·t, which is XNA's; it is cheap but does not guarantee Lerp(a, b, 1) == b exactly for every pair. Matrix::Lerp interpolates all sixteen fields independently. It is not a substitute for decomposing two transforms and interpolating the rotation with Quaternion::Slerp: halfway between two different rotation matrices it generally yields axes shorter than one unit (between the identity and a 90-degree turn, the rotated axes have length √0.5), so the result also scales the object.

Same name, different function

A reader will assume that MathHelper::X and Vector3::X compute the same thing per component. At TARGET several do not; most of those differences are XNA's own, and the rest are last-bit ones:

The scalar and vector forms agree for ordinary finite inputs except in the last bit, and where they disagree on NaN they disagree exactly as XNA's two forms do. Since the 0.1.0 release Clamp, Min and Max follow XNA's operand selection in every vector type (the release let max win an inverted vector clamp and let scalar Max drop a NaN); MathBoundsCompatibilityTests.cpp pins both forms against expectations CNA states it took from the genuine runtime. The last-bit differences are real, though: a component divided by s and a component multiplied by 1/s can differ by one unit in the last place, so v / s, v /= s and XNA's v / s do not always agree (the /= source comment says it matches Divide's "reciprocal form", but Vector3::Divide(Vector3, float) divides directly). Where bit-exact agreement with a recorded XNA run matters, write the reciprocal multiplication yourself (CNA-BUG-068).

Angles, constants and epsilons

• MathHelper::Pi, TwoPi, PiOver2, PiOver4, E, Log2E and Log10E are static constexpr float with XNA's single-precision values (Pi is 3.14159274f).
• ToRadians is one single-precision multiplication by the single-precision constant 0.0174532924 and ToDegrees multiplies by 180.0f / Pi; both forms were chosen by comparison with the genuine XNA runtime's answers (31 angles each way in CNA's matrix oracle).
• WrapAngle returns an angle in the half-open range (−π, π]: π stays π and −π becomes π. It returns an angle already in range unchanged, otherwise takes std::fmod(angle, TwoPi) and adds or subtracts one TwoPi; XNA reaches the same range through Math.IEEERemainder.
• MathHelper::MachineEpsilonFloat is not a constant: it is a static const float computed during dynamic initialisation by halving until 1 + e compares equal to 1, which gives 2⁻²⁴ (about 5.96e-8) with ordinary float evaluation. WithinEpsilon(a, b) tests |a − b| < that value. A static initialiser in another translation unit that calls WithinEpsilon may run before the epsilon is set and see 0, so every comparison would be false; call it only after main starts. The geometry code uses XNA's literal constants instead: Matrix::Decompose 1e-4 (below), the ray–box test 1e-6, the ray–plane, ray–frustum and frustum point tests 1e-5; see Math internals: other numeric details.
• WithinEpsilon, Clamp(intcs, …) and ClosestMSAAPower are FNA-internal helpers that CNA makes public (C++ has no assembly-internal visibility); XNA's public MathHelper has none of them.

Named constants and static initialisation order

The MachineEpsilonFloat caveat above applies to most of the module's named constants as well. Only Vector2's four (Zero, One, UnitX, UnitY) are declared constinit in Vector2.cpp, which is possible because Vector2(float, float) is the only constexpr constructor among the vector types; they are constant-initialised and safe to read at any time. Vector3's eleven constants (including Up and Forward), Vector4's six, Quaternion::Identity, Point::Zero, Rectangle::Empty and the 141 named Color values are plain static const objects built by out-of-line constructors, so each is dynamically initialised when its own translation unit's initialisers run, in an order C++ leaves unspecified across translation units. A namespace-scope or static-member initialiser in game code that copies one of them can run first and copy the still zero-initialised storage: Vector3::Up then reads as (0, 0, 0) and a named colour as transparent black, with no diagnostic. Matrix is different: there is no Matrix::Identity object, and Matrix::getIdentityProperty() returns a function-local static built on first call (Matrix.cpp), which is safe at any time.

Inside functions (constructors, Initialize, Update) every constant is ready, because the program has reached main. At namespace scope, spell the value or build it on first use (syntax-checked against the headers at c1c316b9, whose declarations used here are unchanged at TARGET; not run):

// Unordered with Vector3.cpp's initialisers: may copy (0, 0, 0).
static const Vector3 kWorldUp = Vector3::Up;

// Safe at any time: spelled literally, built on first call.
const Vector3& WorldUp()
{
    static const Vector3 up(0.0f, 1.0f, 0.0f);
    return up;
}

Degenerate inputs are quiet

Most of the module follows IEEE arithmetic instead of validating: a degenerate input produces infinities or NaNs, not an exception, exactly as XNA does for the same functions. The cases that reach games most often:

The practical rule is to validate where bad values enter: user-authored axes, scales, planes, camera inputs and curve keys, and anything read from a file, before it reaches gameplay, rendering or a native API. A guarded move-towards step (syntax-checked against the headers at c1c316b9; the declarations it uses are unchanged at TARGET):

Vector2 MoveToward(Vector2 position, Vector2 target, float speed, float deltaSeconds)
{
    Vector2 toTarget = target - position;
    const float distance = toTarget.Length();
    if (distance > 0.0001f)                      // never normalise a zero vector
    {
        toTarget.Normalize();
        position = position + toTarget * std::min(speed * deltaSeconds, distance);  // no overshoot
    }
    return position;
}

The private CheckForNaNs helpers on the vectors, Matrix and Quaternion (ported XNA debugging aids that throw System::NotFiniteNumberException; the matrix and quaternion versions only without NDEBUG) are never called, so nothing in CNA traps a NaN for you.

Where the arithmetic is wider than float

XNA 4.0 is a 32-bit assembly whose float arithmetic runs on the x87 unit, so an expression is accumulated at extended precision and rounded once when stored. CNA reproduces that, with double intermediates, wherever it measured the difference against the genuine runtime, and since the 0.1.0 release that covers most of the module:

• Products and transforms. Matrix::Multiply, Matrix::Invert, Vector3::Transform and Vector3::TransformNormal by a matrix, the Dot products of Vector2, Vector3 and Vector4, and Vector3::Cross, which also keeps XNA's subtraction order and with it the sign of a zero component (VectorProductCompatibilityTests.cpp).
• Magnitudes. Vector3::Length, LengthSquared, Distance and DistanceSquared accumulate in double and round once; so do Length of Vector2, Vector4 and Quaternion and Distance of Vector2 and Vector4, which is why a vector with a component of 1e20 reports a length of 1e20 instead of infinity. LengthSquared and DistanceSquared of Vector2 and Vector4, and Quaternion::LengthSquared, stay single-precision sums, as in XNA; the squared length of that vector is infinite in every type (MagnitudeCompatibilityTests.cpp).
• Normalisation. Normalize on the three vector types and on Quaternion rounds the length to float and then multiplies by its reciprocal in double; Plane::Normalize does the same and leaves a near-unit plane unchanged (see Planes and half-spaces).
• Quaternion inverse and division. Quaternion::Inverse and Quaternion::Divide keep the squared norm, its reciprocal and the products in double, so a representable result is not lost to an overflowing or underflowing intermediate (QuaternionRangeTests.cpp).
• Geometry. BoundingSphere::CreateFromPoints, the sphere and frustum containment tests, and BoundingBox::Contains(BoundingSphere) and Intersects(BoundingSphere); the details are on Planes, rays and bounding volumes.

The MathHelper interpolators use double for a different reason (their comments cite lost precision). Everything else is single precision, including Vector2::Transform, Vector4::Transform, Plane::DotCoordinate and the quaternion products. The measured table, the corpus sizes and the negative controls are on Math internals: which arithmetic is wider than float. For game code the consequence is small but real: results can differ in the last bit from earlier CNA releases, and an exact-boundary containment test can flip.

What the tests pin

At TARGET the math test directory holds 42 files with 957 statically counted GoogleTest definitions (TEST, TEST_F and TYPED_TEST, a typed test counted once; not executed for this page). 586 assertions use EXPECT_FLOAT_EQ (GoogleTest's four-ULP comparison); explicit EXPECT_NEAR tolerances are 1e-5 (79 uses), 1e-6 (65) and 1e-4 (8), and the per-file kEps is 1e-5 except in BoundingFrustumTests.cpp, where it is 1e-4. Three suites compare with answers recorded from the genuine XNA framework: MatrixOracleTests (444 cases), BoundingSphereOracleTests (445 point sets) and FrustumSeparationOracleTests (a frustum against spheres, boxes and frustums). The compatibility files added after the 0.1.0 release (MathBoundsCompatibilityTests, MagnitudeCompatibilityTests, VectorProductCompatibilityTests, VectorArrayRangeCompatibilityTests, MatrixDecomposeCompatibilityTests, MatrixPerspectiveCompatibilityTests, QuaternionRangeTests and others) compare bits exactly with expectations CNA states it measured on the genuine runtime; the colour and packed-vector rounding cases are checked from the graphics tree. The inverted-range Clamp, NaN and signed-zero operands, zero-vector normalisation, the field-of-view upper bound and Decompose's reflection and refusal rules are now pinned, and MatrixTest.SingularAffineInverseMatchesXnaInfinityAndNaNClassifications pins one singular inversion; the scalar-division rounding has no test against XNA, and the math regression-test recipe shows how to add one. When porting, compare the original program's observable results — projected points, collision answers, curve samples — rather than trusting a shared function name. Everything here was checked by reading TARGET at 3b43bd86 and the decompiled XNA 4.0 Microsoft.Xna.Framework assembly; nothing was run.