DirectXMath Library

DirectXMath includes auxiliary libraries for specialized math tasks:

• SHMath (Spherical Harmonics): Provides spherical harmonic math functions for lighting computations. Note that SHMath/ contains .cpp files that must be compiled into your project.
• XDSP (Digital Signal Processing): A header-only library providing FFT and DSP functions built on top of DirectXMath.

The library is organized into several functional areas located in the Inc/ directory and specialized extension directories:

Core Library (Inc/)

• DirectXMath.h: The core library.
• DirectXPackedVector.h: Load/Store functions and types for compressed GPU formats.
• DirectXColors.h: .NET-style Color defines (sRGB and linear).
• DirectXCollision.h: Bounding volume collision library.

Instruction Set Extensions (Extentions/)

Provides advanced instruction set variants for guarded codepaths:

• DirectXMathSSE3.h, DirectXMathSSE4.h
• DirectXMathBE.h (SSSE3)
• DirectXMathAVX.h, DirectXMathAVX2.h
• DirectXMathF16C.h (Half-precision)
• DirectXMathFMA3.h, DirectXMathFMA4.h (Fused multiply-accumulate)

Specialized Math

• SHMath/: Spherical Harmonics math functions (via DirectXSH.h).
• XDSP/: Digital Signal Processing helper functions (via XDSP.h).

DirectXMath separates memory storage types from SIMD computation types. To use the library correctly, follow this three-step pattern:

1. Load: Transfer data from a storage type (like XMFLOAT3 or XMFLOAT4) into an XMVECTOR or XMMATRIX using XMLoad* functions.
2. Compute: Perform mathematical operations using XMVector*, XMMatrix*, XMQuaternion*, or XMColor* functions.
3. Store: Save the results from the SIMD register back to a storage type using XMStore* functions.

#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);

Calling Conventions

Functions accepting XMVECTOR or XMMATRIX use XM_CALLCONV and specific parameter typedefs (FXMVECTOR, GXMVECTOR, HXMVECTOR, CXMVECTOR, FXMMATRIX, and CXMMATRIX) to optimize register usage across different platforms.

Alignment Requirements

• SIMD Types: XMVECTOR and XMMATRIX require 16-byte alignment.
• Storage Types:
  • Types with an A suffix (e.g., XMFLOAT4A) are aligned.
  • Unsuffixed variants (e.g., XMFLOAT4) are unaligned and safe for use in arbitrary data structures where 16-byte alignment cannot be guaranteed.

To install DirectXMath using vcpkg in classic mode, run the install command and then configure your CMakeLists.txt to find and link the package.

Available features:

• dx11: Spherical Harmonics math library for DirectX 11
• dx12: Spherical Harmonics math library for DirectX 12
• xdsp: Digital Signal Processing library

Supported triplets include x64-windows, x64-linux, arm64-windows, etc.

vcpkg install directxmath

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

You can install DirectXMath using the following methods:

• NuGet: Install the directxmath package from nuget.org.
• Windows SDK: DirectXMath is included in the Windows SDK. Include it in your C++ code using #include <DirectXMath.h>.

The directxmath NuGet package is deprecated. The recommended way to integrate the latest DirectXMath into your C++ project is using vcpkg.

If you are using CMake, ensure you are using version 3.21 or later. Visual Studio 2019 users may need to install a standalone version of CMake 3.21 or later and add it to their PATH.

You can use GitHub CoPilot CLI to get assistance with DirectXMath by installing the specific skills via the GitHub CLI.

winget install GitHub.Copilot
winget install GitHub.cli
gh skill install microsoft/directxmath
copilot
/skills list

DirectXMath provides extension headers in the Extensions/ directory that offer optimized overrides for specific instruction sets. To use them, you must include the extension header after the core DirectXMath.h header. Functions within these extensions are accessed via their specific namespaces rather than the default DirectX namespace.

Note: If you are compiling with /arch:AVX or /arch:AVX2 compiler flags, these extensions are not required as the core library automatically utilizes those instructions.

To integrate DirectXMath into your project using vcpkg in manifest mode (recommended), add directxmath to the dependencies array in your vcpkg.json file.

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