directxmath-usage

DirectXMath Usage

Overview

DirectXMath is a header-only SIMD C++ linear algebra library for use in games, graphics engines, and other performance-sensitive applications. It provides vector, matrix, and quaternion math optimized for SSE/SSE2 (x86/x64) and ARM-NEON (ARM64) instruction sets.

• Namespace: DirectX
• Minimum C++ Standard: C++11 (with conditional C++14/17/20 features)
• Minimum Compiler: Visual C++ 2017 (_MSC_VER >= 1910), or equivalent Clang/GCC
• Repository: https://github.com/microsoft/DirectXMath
• Documentation: https://github.com/microsoft/DirectXMath/wiki, https://learn.microsoft.com/windows/win32/dxmath/directxmath-portal
• NuGet Packages: directxmath
• vcpkg Port: directxmath

An optional C++ wrapper, SimpleMath, is available that provides a more user-friendly interface to the DirectXMath API with fewer alignment and usage restrictions. It is part of the DirectX Tool Kit for DirectX 11 and DirectX 12, and is intended to mimic the XNA Game Studio framework math library.

Integration Methods

vcpkg manifest-mode (Recommended)

In your vcpkg.json file, add the following:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "directxmath"
  ]
}

vcpkg (classic)

vcpkg install directxmath

Then in your CMakeLists.txt:

find_package(directxmath CONFIG REQUIRED)
target_link_libraries(YourTarget PRIVATE Microsoft::DirectXMath)

Features: dx11 (Spherical Harmonics math library for DirectX 11), dx12 (Spherical Harmonics math library for DirectX 12), xdsp (Digital Signal Processing library). Triplets: x64-windows, x64-linux, arm64-windows, etc.

NuGet

Install the directxmath package from nuget.org.

Windows SDK

The Windows SDK ships with DirectXMath, though it may not be the latest version. Include via:

#include <DirectXMath.h>

Basic Usage

#include <DirectXMath.h>
using namespace DirectX;

// Load data from storage type to SIMD register
XMFLOAT3 position{ 1.0f, 2.0f, 3.0f };
XMVECTOR v = XMLoadFloat3(&position);

// Perform computation in SIMD
v = XMVector3Normalize(v);

// Store result back to memory
XMFLOAT3 result;
XMStoreFloat3(&result, v);

Key Concepts

Load / Compute / Store Pattern

DirectXMath separates storage types (for memory layout) from the computation type (XMVECTOR). Always:

1. Load from a storage type (XMFLOAT3, XMFLOAT4, etc.) into XMVECTOR or XMMATRIX using XMLoad* functions.
2. Compute using XMVector*, XMMatrix*, XMQuaternion*, or XMColor* functions.
3. Store results back to a storage type using XMStore* functions.

Calling Conventions

Functions that accept XMVECTOR or XMMATRIX parameters use XM_CALLCONV and the parameter typedefs FXMVECTOR, GXMVECTOR, HXMVECTOR, CXMVECTOR, FXMMATRIX, and CXMMATRIX to maximize register usage across platforms.

Alignment

XMVECTOR and XMMATRIX require 16-byte alignment. Storage types with an A suffix (e.g., XMFLOAT4A) are aligned; the unsuffixed variants (e.g., XMFLOAT4) are unaligned and safe for use in arbitrary data structures.

API Reference

For detailed API signatures and function families, see the reference overview.

The canonical API documentation is on Microsoft Learn. All function signatures can be discovered in the public headers under the Inc/ directory.

Auxiliary Libraries

SHMath (Spherical Harmonics)

The SHMath/ directory provides spherical harmonic math functions for lighting computations. Unlike the core library, SHMath includes .cpp files that must be compiled.

See reference overview - SHMath section for details.

XDSP (Digital Signal Processing)

The XDSP/ directory provides header-only FFT and DSP functions built on DirectXMath.

See reference overview - XDSP section for details.

Platform Support

Additional Resources

• Getting Started (Microsoft Learn)
• API Reference (Microsoft Learn)
• GitHub Wiki
• Introductory Blog Post