Math Types

Microsoft::Xna::Framework math library — vectors, matrices, quaternions, colors, bounding volumes, curves

Overview

CNA provides the complete XNA 4.0 math library as a C++23 implementation. It lives in the math module (CNA::Math), which is a compiled library — modules/math/src/*.cpp — with public headers, not a header-only one, and it links only that module and Sharp Runtime, so it can be used with no renderer. Types are value types (structs) and support the same member functions, static helpers, and operator overloads as their XNA counterparts. Floating-point arithmetic follows XNA semantics: row-major matrices, right-handed coordinate system for CreateLookAt and view-space conventions, and clockwise winding by default.

Two spelling rules apply throughout, because the C++ API mirrors the C# one: the vector, quaternion, plane, ray, point and matrix element components are plain public fields (v.X, m.M11, box.Min), while everything that is a property in C# is an accessor pair — getXProperty() / setXProperty(value) — for example Color::getRProperty(), Rectangle::getCenterProperty() and Matrix::getIdentityProperty(). Tables below name the accessor where one exists.

The library is organized into three groups: core types (vectors, matrix, quaternion, color, and helpers), bounding types (collision and visibility volumes), and curve types (animation splines). A separate PackedVector sub-namespace in Microsoft::Xna::Framework::Graphics::PackedVector provides GPU-format value types documented separately.

Core types

Vector2

A 2D vector with float components X and Y. Supports arithmetic with other vectors and scalars, and provides the most common geometric operations.

Vector3

A 3D vector with float components X, Y, Z. Used for positions, directions, normals, and colors throughout the 3D API.

Vector4

A 4D vector with float components X, Y, Z, W. Used for homogeneous coordinates, RGBA colors, and as shader parameter types.

Matrix

A 4×4 row-major floating-point matrix. Elements are named M11–M44 (row, column). Used for world/view/projection transforms and general linear algebra. Multiplication is left-to-right (row-vector convention), matching XNA 4.0 exactly.

Quaternion

A unit quaternion representing a 3D rotation, stored as X, Y, Z (imaginary) and W (real) float components. Quaternions avoid gimbal lock and are the preferred rotation representation for animation and interpolation.

Color

An RGBA color stored as four byte (uint8) components, packed into a 32-bit integer. Over 140 named static colors are provided as static fields, matching the XNA Color class exactly (including CornflowerBlue, the classic XNA clear color).

Rectangle

An axis-aligned integer rectangle defined by its top-left corner (X, Y) and its dimensions (Width, Height). Used for screen regions, texture source rectangles, and 2D collision detection.

Point

A pair of integer values X and Y. Used for screen coordinates, texture offsets, and as the return type of several Rectangle properties.

MathHelper

A static utility class with common scalar math functions and constants. Mirrors Microsoft.Xna.Framework.MathHelper, and additionally exposes four FNA-internal helpers publicly (WithinEpsilon, MachineEpsilonFloat, an integer Clamp and ClosestMSAAPower); those four are not XNA API.

Bounding types

Bounding volume types live in Microsoft::Xna::Framework alongside the core math types. They are used for frustum culling, collision detection, and ray casting. Contains returns a ContainmentType enum value (Disjoint, Contains, or Intersects). Intersects returns bool except for ray tests which return std::optional<float> (the hit distance along the ray).

BoundingBox

An axis-aligned bounding box (AABB) defined by its minimum and maximum corner points as Vector3 values.

BoundingSphere

A bounding sphere defined by a center Vector3 and a float radius.

BoundingFrustum

A view frustum defined by a combined view-projection matrix. Computes the six clip planes automatically from the matrix and exposes them as Plane objects. Typically used for frustum culling.

Plane

A half-space plane defined by a Normal (Vector3) and a scalar distance D, satisfying the equation Normal·X + D = 0.

Ray

A ray defined by an origin (Position) and a unit direction (Direction), both Vector3. The primary use is ray casting against bounding volumes and planes.

Curve types

The curve types provide 1D floating-point animation splines. They are used by the content pipeline and by AnimationPlayer implementations to drive scalar properties over time.

Curve

A piecewise Hermite spline that maps a float position (typically time) to a float value. The spline is defined by a sorted collection of CurveKey control points and loop types that govern behaviour outside the key range.

The CurveLoopType enum controls what happens outside the key range:

CurveKey

A single control point on a Curve. Stores the position, value, and in/out tangents that define the Hermite segment connecting adjacent keys.

PackedVector types

The Microsoft::Xna::Framework::Graphics::PackedVector namespace provides 17 GPU-oriented packed value types such as HalfVector2, HalfVector4, NormalizedByte4, Rgba1010102, and others. These types implement the IPackedVector interface and are used as vertex element formats. All 17 are real, including a correct IEEE-754 half-float codec that handles subnormals, infinities and NaN in both directions. Float construction of the 14 integer-packed types saturates, rounds ties-to-even and packs NaN as 0, as measured on the genuine XNA 4.0 runtime (the three half-float types use the IEEE half codec instead), and all 17 implement ToString(), GetHashCode() and Equals (alpha.1 lacked these).

See the dedicated PackedVector Types reference for the full per-type breakdown. These values are broadly usable as vertex data. Texture-format admission is narrower and renderer-qualified: the default Reach profile refuses the wider formats (Rgba1010102, Rg32, Rgba64, Alpha8, Single, Vector2, Vector4, the half-float formats and HdrBlendable) unless HiDef is requested, and on top of that only eight renderer families promote the broader formats for a public Texture2D (DirectX 11, the EasyGL identities, SDL_GPU, WebGPU, Vulkan, Metal, FNA3D and Software), while the other four identities (SDL_RENDERER, DIRECTX9, HEADLESS and STUB) accept only SurfaceFormat::Color.

Code examples

The snippets below compile against the CNA headers at this snapshot (syntax-checked with the same include set as the tutorials); they assume using namespace Microsoft::Xna::Framework; and, for the graphics types, Microsoft::Xna::Framework::Graphics.

Vector3 math — normalize and dot product

// Compute the angle between two directions using dot product
Vector3 toEnemy = enemy.Position - player.Position;
float distance  = toEnemy.Length();
Vector3 dir     = Vector3::Normalize(toEnemy);          // unit direction

Vector3 facing  = Vector3::Normalize(player.Forward);
float   cosAngle = Vector3::Dot(facing, dir);            // in [-1, 1]
float   angleDeg = MathHelper::ToDegrees(std::acos(cosAngle));

if (angleDeg < 45.0f)
    DrawAimingReticle();

Matrix camera setup — LookAt and PerspectiveFieldOfView

// Build a standard view-projection matrix pair (inside a Game subclass)
Matrix view = Matrix::CreateLookAt(
    Vector3(0.0f, 5.0f, 10.0f),   // eye position
    Vector3::Zero,                  // look-at target
    Vector3::Up                     // world up
);

Matrix projection = Matrix::CreatePerspectiveFieldOfView(
    MathHelper::ToRadians(60.0f),   // vertical FOV
    getGraphicsDeviceProperty().getViewportProperty().getAspectRatioProperty(),
    0.1f,   // near plane
    1000.0f // far plane
);

// Pass to a BasicEffect
effect->setViewProperty(view);
effect->setProjectionProperty(projection);

Quaternion rotation interpolation — Slerp

// Smoothly rotate an object from startRotation to endRotation over 2 seconds
Quaternion startRotation = Quaternion::CreateFromYawPitchRoll(0.0f, 0.0f, 0.0f);
Quaternion endRotation   = Quaternion::CreateFromAxisAngle(Vector3::Up,
                               MathHelper::ToRadians(180.0f));

float elapsed = 0.0f;              // a member of your Game
const float duration = 2.0f;

// Inside Update(GameTime& gameTime):
elapsed += (float)gameTime.getElapsedGameTimeProperty().getTotalSecondsProperty();
float t = MathHelper::Clamp(elapsed / duration, 0.0f, 1.0f);
Quaternion current = Quaternion::Slerp(startRotation, endRotation, t);

Matrix world = Matrix::CreateFromQuaternion(current);
effect->setWorldProperty(world);

BoundingSphere intersection test

// Simple frustum-culling check before submitting a draw call
BoundingSphere sphere(center, radius);
BoundingFrustum frustum(view * projection);

if (frustum.Contains(sphere) != ContainmentType::Disjoint)
{
    // Sphere is at least partially visible — draw it
    DrawMesh(mesh);
}

// Ray-cast from the cursor to pick an object: Viewport::Unproject returns a
// world-space Vector3, so unproject the near and far plane points and build the Ray
Vector3 nearPoint = viewport.Unproject(Vector3(cursorPos.X, cursorPos.Y, 0.0f),
                                       projection, view, Matrix::getIdentityProperty());
Vector3 farPoint  = viewport.Unproject(Vector3(cursorPos.X, cursorPos.Y, 1.0f),
                                       projection, view, Matrix::getIdentityProperty());
Ray pickRay(nearPoint, Vector3::Normalize(farPoint - nearPoint));

std::optional<float> hitDistance = sphere.Intersects(pickRay);
if (hitDistance.has_value())
    SelectObject(object, hitDistance.value());

MathHelper.Lerp for smooth transitions

// Smoothly fade a value (e.g. music volume) toward a target each frame
float currentVolume = 0.0f;
float targetVolume  = 1.0f;
const float speed   = 2.0f;   // units per second

// Inside Update(GameTime& gameTime):
float dt = (float)gameTime.getElapsedGameTimeProperty().getTotalSecondsProperty();
currentVolume = MathHelper::Lerp(currentVolume, targetVolume,
                                  MathHelper::Clamp(speed * dt, 0.0f, 1.0f));
MediaPlayer::setVolumeProperty(currentVolume);

Numerical behaviour: what matches the XNA runtime

Because CNA reproduces XNA's numerical behaviour rather than merely its API, a few results can differ in the last bits from alpha.1 and from a plain float reimplementation. The evidence is limited to the measured subsets below; it is not a claim that every math member is bit-identical.