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

CNA snapshot 009d40f5  ·  Deep Dives › Framework core  ·  source links pinned to 009d40f5

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, and some differ from XNA as well:

The algebra agrees everywhere in that table except Clamp with an inverted range and the NaN cases, so for ordinary finite inputs the differences are last-bit ones. They 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. The inverted-range Clamp and the NaN selection are recorded on Known Issues; order your bounds before clamping, or clamp per component with MathHelper::Clamp, whose rule matches XNA.

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. Matrix::Decompose uses a different, file-local threshold (FLT_EPSILON, twice as large, with <=), and the ray–plane and frustum code use their own 1e-5 constants; see Math internals: the two epsilons.
• 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 TARGET headers; 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 TARGET headers:

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 std::logic_error; 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, exactly where it measured the difference against the genuine runtime: Matrix::Multiply, Matrix::Invert, Vector3::Transform and Vector3::TransformNormal by a matrix, and BoundingSphere::CreateFromPoints. The MathHelper interpolators use double for a different reason (their comments cite lost precision), and BoundingBox::Contains(BoundingSphere) and Intersects(BoundingSphere) accumulate their squared distance in double (the source gives no reason and no math oracle suite covers the two functions). Everything else is single precision, including Vector4::Transform, Vector2::Transform, the quaternion operations and, notably, Vector3::Length, LengthSquared, Distance and DistanceSquared, although the same measurement found XNA accumulating those wide; only private helpers inside BoundingSphere.cpp follow the wide rule for lengths. 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 from XNA, and from earlier CNA releases, in the last bit, and an exact-boundary containment test can flip.

What the tests pin

At TARGET the math test directory holds 27 files with 873 statically counted GoogleTest definitions (not executed for this page). 586 assertions use EXPECT_FLOAT_EQ (GoogleTest's four-ULP comparison); explicit tolerances are 1e-5 (75 uses), 1e-6 (64) and 1e-4 (4), and the per-file kEps is 1e-5 except in BoundingFrustumTests.cpp, where it is 1e-4. Two suites compare bits with recorded answers of the genuine XNA framework: MatrixOracleTests (444 cases) and BoundingSphereOracleTests (445 point sets); the colour and packed-vector rounding cases are checked from the graphics tree. Most other expectations are derived analytically. The inverted-range Clamp, NaN and signed-zero operands, zero-vector normalisation, singular inversion, the field-of-view upper bound and the scalar-division rounding have no test; 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 009d40f5 and the decompiled XNA 4.0 Microsoft.Xna.Framework assembly; nothing was run.