PackedVector Types

Microsoft::Xna::Framework::Graphics::PackedVector — compact integer representations for GPU vertex and texture data

Overview

The Microsoft::Xna::Framework::Graphics::PackedVector namespace contains types that pack floating-point component values into compact integer representations. They are broadly useful in vertex layouts. Texture use is renderer-qualified: Skia promotes packed/normalized formats, IGL promotes only Rg32/Single, and other families retain the framework's Color-only public texture gate.

Each packed type stores its data in the smallest integer that can hold all components. The GPU can decode them natively in hardware, so pack-on-CPU, unpack-in-shader is both fast and lossless within the precision of each format. Using packed types instead of raw float arrays can cut vertex buffer size by 50–75% for typical 3D meshes.

All 17 types are available in the Microsoft::Xna::Framework::Graphics::PackedVector namespace in CNA, matching the XNA 4.0 public API exactly. Two additional names, Vector2 and Vector4, appear in the XNA 4.0 PackedVector namespace as type aliases; in CNA these resolve to Microsoft::Xna::Framework::Vector2 and Microsoft::Xna::Framework::Vector4 respectively.

IPackedVector interface

Every packed type implements the IPackedVector<T> interface, where T is the underlying integer storage type (uint8_t, uint16_t, uint32_t, or uint64_t). The interface defines three members:

Types with a single component also implement the non-generic IPackedVector base interface, which exposes only ToVector4(). This allows generic rendering code to unpack any packed type to Vector4 without knowing the concrete type.

Complete type reference

IEEE 754 half-float (float16)

The three half-float types — HalfSingle, HalfVector2, and HalfVector4 — use the 16-bit IEEE 754 binary16 format, commonly called half-float or fp16. CNA implements the full conversion path in C++23 without relying on compiler extensions or hardware intrinsics, so the code is portable across all supported platforms.

Format layout

The representable normal range is approximately ±6.10×10^-5 to ±65504. The smallest positive subnormal is approximately 5.96×10^-8.

HalfTypeHelper

All float32 ↔ float16 conversions go through the internal HalfTypeHelper class. It handles every case defined by the IEEE 754-2008 standard:

• Normal numbers — re-biased exponent and rounded mantissa (round-to-nearest-even).
• Subnormals — exponent field is 0, mantissa is non-zero; correctly decoded during unpack.
• Positive and negative zero — sign bit preserved; both ±0 round-trip correctly.
• Positive and negative infinity — exponent field all-ones, mantissa zero; preserved on pack and unpack.
• NaN — exponent field all-ones, mantissa non-zero; both quiet and signaling NaN are packed as quiet NaN (all mantissa bits set to 1) to avoid platform-dependent signaling behaviour.
• Overflow — float32 values with magnitude greater than 65504 saturate to ±infinity in the float16 result.
• Underflow — float32 values smaller than the smallest subnormal flush to ±zero.

Code examples

Creating and packing a HalfVector4

// Pack four floats into 64 bits (4 x float16)
HalfVector4 hv4;
hv4.Pack(Vector4(1.0f, 0.5f, -0.25f, 2.0f));

// Access the raw bit pattern
uint64_t bits = hv4.PackedValue;

// Unpack back to float
Vector4 result = hv4.ToVector4();
// result.X == 1.0f, result.Y == 0.5f, result.Z == -0.25f, result.W == 2.0f

Using NormalizedByte4 for a vertex normal

NormalizedByte4 is a compact format for storing unit normals and tangents in vertex buffers. Each component uses a signed 8-bit integer mapped to the -1..1 range, cutting normal storage from 12 bytes to 4 bytes per vertex.

// Pack a vertex normal (unit vector) into 4 bytes
NormalizedByte4 packedNormal;
packedNormal.Pack(Vector4(0.0f, 1.0f, 0.0f, 0.0f));  // pointing up

// Use as part of a vertex declaration
VertexElement normalElem(
    offsetof(MyVertex, Normal),
    VertexElementFormat::Byte4,
    VertexElementUsage::Normal,
    0
);

// Unpack on retrieval
Vector4 normal = packedNormal.ToVector4();
// normal.X == 0.0f, normal.Y == 1.0f, normal.Z == 0.0f

Using Rgba1010102 for HDR colour data

Rgba1010102 packs red, green, and blue each into 10 bits (0..1023 per channel, normalized to 0.0..1.0) and alpha into 2 bits. This provides roughly 3× the per-channel precision of Bgra5551 in the same 32-bit footprint, making it suitable for HDR render targets and wide-gamut textures.

// Pack an HDR colour (values above 1.0 are clamped by the packer)
Rgba1010102 hdrColor;
hdrColor.Pack(Vector4(0.95f, 0.72f, 0.12f, 1.0f));

// The 2-bit alpha maps 0.0..1.0 to 0..3
// The 10-bit RGB channels give ~0.001 precision per channel
Vector4 unpacked = hdrColor.ToVector4();

Checking HalfSingle precision and special values

// Normal value round-trip
HalfSingle hs;
hs.Pack(1.5f);
float v = hs.ToVector4().X;  // == 1.5f exactly (representable in float16)

// Infinity is preserved
hs.Pack(std::numeric_limits<float>::infinity());
// hs.PackedValue == 0x7C00 (positive infinity in float16)

// Values beyond float16 range saturate to infinity
hs.Pack(70000.0f);
// hs.PackedValue == 0x7C00 (overflow -> +inf)

// NaN is preserved as quiet NaN
hs.Pack(std::numeric_limits<float>::quiet_NaN());
// hs.PackedValue has exponent=0x1F and non-zero mantissa

// Zero sign is preserved
hs.Pack(-0.0f);
// hs.PackedValue == 0x8000 (negative zero in float16)