Home

http://go.microsoft.com/fwlink/?LinkID=615560

DirectXMath is an all inline SIMD C++ linear algebra library for use in games and graphics apps.

See this post.

Headers

#include <DirectXMath.h>
#include <DirectXCollision.h>
#include <DirectXColors.h>
#include <DirectXPackedVector.h>

Namespace

All the functions in the library are in the DirectX C++ namespace. The packed vector types and functions are in the DirectX::PackedVector C++ namespace.

using namespace DirectX;

Documentation

The DirectXMath library is documented on Microsoft Docs.

You can file PRs directly against the Microsoft Docs via the Edit button. The table-of-contents, overviews, and class descriptions are hosted on GitHub win32, while the function reference is hosted on GitHub sdk-api.

Windows SDK

The DirectXMath library is included in the Windows SDK starting with version 8.0. Therefore it is included with Visual C++ 2012 and later. For a full list versions, see releases.

NuGet

DirectXMath is also available on NuGet.

vcpkg

DirectXMath is available from vcpkg.

vcpkg install directxmath

As an all inline header, there is no library. You still need to install it for each build triplet you use. arm, arm64, x86, x64, windows, windows-static, windows-static-md, and uwp triplets are supported.

For Windows Subsystem for Linux, use:

./vcpkg install directxmath:x64-linux

./vcpkg install directxmath:arm64-linux

Instruction set

For x86/x64, DirectXMath makes use of SSE/SSE2 intrinsics. All x64 native CPUs are required to support SSE and SSE2. Windows 8.0 (32-bit) or later will not install without SSE/SSE2 support.

For ARM, DirectXMath makes use of ARMv7 ARM-NEON intrinsics. All Windows on ARM devices support ARM-NEON and VFPv3.

For ARM64, DirectXMath makes use of ARMv8 ARM-NEON intrinsics. ARM-NEON and VFPv4 support is required for the ARM 64 architecture.

See this blog series for full details.

Using _XM_NO_INTRINSICS_ results in only C/C++ codepaths which should work on any architecture, but the library is not optimized for this case.

Architecture switch

If you build with /arch:AVX (-mavx or -mf16c on clang/LLVM) such that your binary requires Intel Advanced Vector Extensions, DirectXMath 3.09 or later will make use of SSE3, SSE4.1, and AVX instructions.

The primary benefit of building with /arch:AVX is the use of the VEX prefix in all generated SSE instructions.

If you build with /arch:AVX2 (-mavx2 on clang/LLVM) such that your binary requires Intel Advanced Vector Extensions 2, DirectXMath 3.09 or later will make use of SSE3, SSE4.1, AVX, and F16C instructions.

The compiler should make use of FMA3 as appropriate when building with /arch:AVX2 even without explicit use of the _mm_f*add_ps intrinsic. In DirectXMath 3.10 or later, XMVerifyCPUSupport will check for AVX2 and FMA3 instruction support when building with /arch:AVX2.

Windows XP

The DirectXMath library is all inline and uses only Visual C++ intrinsics. Therefore, it is compatible with all version of Windows supported by Visual C++. There's no standard configuration that will put DirectXMath in the include path when using the v1x0_xp Platform Toolset, but you can add it manually or make use of the NuGet package. Keep in mind there are a number of other differences when doing DirectX development for Windows XP support. See this post.

Migrating code

Details on moving from XNAMath to DirectXMath are covered in Code Migration from the XNA Math Library.

Moving from the legacy D3DX9/D3DX10 D3DXMath is covered in Working with D3DXMath.

Math conventions

DirectX has historically used row-major matrices, row vectors, pre-multiplication, and left-handed coordinates. The DirectXMath library uses row-major matrices, and offers both left-handed (LH) and right-handed (RH) coordinate versions of the relevant matrix functions.

See this blog post for a detailed description of the convention choices, and the historic context for the DirectX vs. OpenGL differences in conventions.

Calling convention

Be sure to read the Microsoft Docs details on the calling convention types which are designed to deal with the various architectures and vector calling conventions. The best way to ensure you have them correct is to attempt to build your code with x86, x64, and ARM.

Language extensions

DirectXMath is written using standard Intel-style intrinsics, which should be portable to other compilers. The ARM and ARM64 codepaths use ARM-style intrinsics (earlier versions of the library used Visual C++ specific __n64 and __n128), so these are also portable.

The DirectXMath library make use of two commonly implemented extensions to Standard C++:

• anonymous structs, which are widely supported and are part of the C11 standard. Note that the library also uses anonymous unions, but these are part of the C++ and C99 standard.
• #pragma once rather than old-style #define based guards, but are widely supported

Because of these, DirectXMath is not compatible with Visual C++'s /Za switch which enforces ISO C89 / C++11. It does work with /permissive-.

Compiler support

Officially the library is supported with Microsoft Visual C++ 2017 or later, clang/LLVM v9 or later, and GCC 9 or later. It should also compile with the Intel C++ and MinGW compilers.

When building with clang/LLVM or other GNU C compilers, the _XM_NO_XMVECTOR_OVERLOADS_ control define is set because these compilers do not support creating operator overloads for the XMVECTOR type. You can choose to enable this preprocessor define explicitly to do the same thing with Visual C++ for improved portability.

To build for non-Windows platforms, you need to provide a sal.h header in your include path. You can obtain an open source version from GitHub.

cd DirectXMath/Inc
wget https://raw.githubusercontent.com/dotnet/corert/master/src/Native/inc/unix/sal.h

With GCC, the SAL annotation preprocessor symbols can conflict with the GNU implementation of the Standard C++ Library. The workaround is to include the system headers before including DirectXMath:

#include <algorithm>
#include <iterator>
#include <utility>

#include <DirectXMath.h>

Intel Short Vector Math Library

In Visual Studio 2019, the Intel® Short Vector Library is now available as part of the Visual C++ runtime libraries. In DirectXMath 3.16 or later, I make use of this library to replace the minimax approximations of various transcendental and other math functions listed below. With the GitHub, NuGet, and VCPKG versions this is enabled automatically, but can be disabled by defining the preprocessor symbol _XM_DISABLE_INTEL_SVML_. With the Windows 11 SDK, developers must opt-in by defining the preprocessor symbol _XM_SVML_INTRINSICS_.

For the x86/x64 platform, enabling the SVML makes the following DirectXMath functions into simple inline wrappers around the appropriate SVML function:

XMVectorExp2	_mm_exp2_ps		XMVectorLog2	_mm_log2_ps
XMVectorExp10	_mm_exp10_ps		XMVectorLog10	_mm_log10_ps
XMVectorExpE	_mm_exp_ps		XMVectorLogE	_mm_log_ps
XMVectorPow	_mm_pow_ps		XMVectorSinCos	_mm_sincos_ps
XMVectorSin XMVectorSinEst	_mm_sin_ps		XMVectorCos XMVectorCosEst	_mm_cos_ps
XMVectorSinH	_mm_sinh_ps		XMVectorCosH	_mm_cosh_ps
XMVectorTan XMVectorTanEst	_mm_tan_ps		XMVectorTanH	_mm_tanh_ps
XMVectorASin XMVectorASinEst	_mm_asin_ps		XMVectorACos XMVectorACosEst	_mm_acos_ps
XMVectorATan XMVectorATanEst	_mm_atan_ps		XMVectorATan2 XMVectorATan2Est	_mm_atan2_ps

The Intel® Short Vector Library routines are generally optimized for SSE/SSE2, SSE 4, and AVX selected at runtime. They are work well on both Intel and AMD CPUs. See the Intel site for more information.

Additional content

Extensions - Advanced instruction set variants for DirectXMath
SHMath - Spherical Harmonics math
XDSP - Digital Signal Processing helper functions
Stereo3D - Stereo 3D matrix helper functions

Related

See the DirectX Tool Kit's SimpleMath wrapper for DirectXMath.

The XDSP.h header is included in the XAudio2Redist NuGet package.

Support

For questions, consider using Stack Overflow with the directxmath tag, or the DirectX Discord Server in the dx12-developers or dx9-dx11-developers channel.

For bug reports and feature requests, please use GitHub issues for this project.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Tests for new features should also be submitted as a PR to the Test Suite repository.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Credits

The xboxmath library was originated by Matt Bronder with contributions from Sakphong Chanbai and David Hefner for the Xbox 360.

The xnamath library for the DirectX SDK and Xbox XDK was the work of Chuck Walbourn and Becky Heineman based on xboxmath, with contributions from Jeremy Gup, Dan Haffner, Matt Lee, Casey Meekhof, Rich Sauer, Jason Strayer, and Xiaoyue Zheng.

The DirectXMath library for the Windows SDK and Xbox One XDK is the work of Chuck Walbourn based on xnamath, with contributions from Darren Anderson, Matt Lee, Aaron Rodriguez Hernandez, Yuichi Ito, Reza Nourai, Rich Sauer, and Jason Strayer.

Thanks to Dave Eberly for his contributions particularly in improving the transcendental functions.

Thanks to Bruce Dawson for his help with the rounding functions.

Thanks to Andrew Farrier for the fixes to XMVerifyCPUSupport to properly support clang.

Thanks to Scott Matloff for his help in getting the library updated to use Intel SVML for VS 2019.

Further reading

Resources