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 header-only C++23 implementation. Types are value types (structs) and support the same member functions, static helpers, and operator overloads as their XNA counterparts. All floating-point arithmetic matches XNA semantics: row-major matrices, right-handed coordinate system for CreateLookAt and view-space conventions, and clockwise winding by default.

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 exactly.

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 and texture pixel formats. They are fully implemented with the same 100% test coverage as the core math types.

A dedicated PackedVector reference page is planned. In the meantime, the namespace and all member names mirror XNA 4.0 exactly.

Code examples

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 PerspectiveFOV

// Build a standard view-projection matrix pair
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
    graphicsDevice->Viewport().AspectRatio(),
    0.1f,   // near plane
    1000.0f // far plane
);

// Pass to a BasicEffect
effect->SetView(view);
effect->SetProjection(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;
const float duration = 2.0f;

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

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

BoundingSphere intersection test

// Simple frustum-culling check before submitting a draw call
BoundingSphere sphere(mesh.Center, mesh.Radius);
BoundingFrustum frustum(camera.View * camera.Projection);

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

// Ray-cast from the cursor to pick an object
Ray pickRay = viewport.Unproject(cursorPos, projection, view, Matrix::Identity);
auto 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():
float dt = (float)gameTime.ElapsedSeconds();
currentVolume = MathHelper::Lerp(currentVolume, targetVolume,
                                  MathHelper::Clamp(speed * dt, 0.0f, 1.0f));
MediaPlayer::SetVolume(currentVolume);