| name | directxmath-usage |
| description | Guide for integrating DirectXMath into new projects and an overview of the API, types, and classes. Use this skill when asked about how to use DirectXMath, integrate it into a project, or for an overview of available functionality. |
| license | MIT |
| metadata | {"author":"chuckw","version":"1.0"} |
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.
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;
XMFLOAT3 position{ 1.0f, 2.0f, 3.0f };
XMVECTOR v = XMLoadFloat3(&position);
v = XMVector3Normalize(v);
XMFLOAT3 result;
XMStoreFloat3(&result, v);
Key Concepts
Load / Compute / Store Pattern
DirectXMath separates storage types (for memory layout) from the computation type (XMVECTOR). Always:
- Load from a storage type (
XMFLOAT3, XMFLOAT4, etc.) into XMVECTOR or XMMATRIX using XMLoad* functions.
- Compute using
XMVector*, XMMatrix*, XMQuaternion*, or XMColor* functions.
- 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
| Platform | SIMD Backend |
|---|
| Windows x86/x64 | SSE/SSE2 (baseline), up to AVX2 |
| Windows ARM64/ARM64EC | ARM-NEON |
| Linux x86_64 | SSE/SSE2 (baseline), up to AVX2 |
| Linux ARM64 | ARM-NEON |
| Any (fallback) | Pure C++ (_XM_NO_INTRINSICS_) |
Additional Resources
