DirectXTK

Headers

Public headers are in the Inc folder of the distribution package.

Namespace

All the functions in the library are in the DirectX C++ namespace.

using namespace DirectX;

The XBoxDDSTextureLoader functions are in the Xbox C++ namespace.

Modules

Audio* - low-level audio API using XAudio2
BufferHelpers - C++ helpers for creating D3D resources from CPU data
CommonStates - common D3D state combinations
DDSTextureLoader - light-weight DDS file texture loader
DescriptorHeap - helper for managing DX12 descriptor heaps
- DescriptorPile
DirectXHelpers - misc C++ helpers for D3D programming
EffectPipelineStateDescription - helper for creating PSOs
Effects - set of built-in shaders for common rendering tasks
- IEffectFactory, EffectFactory, PBREffectFactory
- IEffectTextureFactory, EffectTextureFactory
- IEffect, IEffectMatrices, IEffectLights, IEffectFog, IEffectSkinning
- AlphaTestEffect, BasicEffect, DualTextureEffect, EnvironmentMapEffect, SkinnedEffect
- NormalMapEffect, SkinnedNormalMapEffect
- PBREffect, SkinnedPBREffect
- DebugEffect
GamePad* - gamepad controller helper using XInput or Windows.Gaming.Input
GeometricPrimitive - draws basic shapes such as cubes and spheres
GraphicsMemory - helper for managing graphics memory allocation
Keyboard* - keyboard state tracking helper
Model - draws meshes loaded from .CMO, .SDKMESH, or .VBO files
- ModelMesh, ModelMeshPart, ModelBone
Mouse* - mouse helper
PostProcess - set of built-in shaders for common post-processing operations
- BasicPostProcess, DualPostProcess, ToneMapPostProcess
PrimitiveBatch - simple and efficient way to draw user primitives
RenderTargetState - helper for communicating render target requirements when creating PSOs
ResourceUploadBatch - helper for managing texture resource upload to the GPU
ScreenGrab - light-weight screen shot saver
SimpleMath* - simplified C++ wrapper for DirectXMath
SpriteBatch - simple & efficient 2D sprite rendering
SpriteFont - bitmap based text rendering
VertexTypes - structures for commonly used vertex data formats
WICTextureLoader - WIC-based image file texture loader
XboxDDSTextureLoader - DDSTextureLoader variant for Xbox One exclusive app developers

* = Audio, GamePad, Keyboard, Mouse, and SimpleMath are identical to the original DirectX Tool Kit implementation.

Tools

MakeSpriteFont - builds .spritefont data files for use with SpriteFont class
XWBTool - builds .xwb XACT-style wave banks for use with WaveBank class

Note that the tools are hosted on the original DirectX Tool Kit site since they are unchanged for DirectX 12.

Building

This code is designed to build with Visual Studio 2019 or later. It requires the Windows SDK (19041) or later. The expectation is that you are building with _WIN32_WINNT set to 0x0A00. See Using the Windows Headers.

HLSL shaders

The required Direct3D shaders are built as headers in Src\Shader\Compiled\*.inc and included into the DirectXTK static library. They are automatically built by the Visual Studio project if they are not present, and cleared by a Clean. They can also be manually rebuilt using the CompileShaders.cmd script (i.e. ...\DirectXTK12\Src\Shaders)

DirectX Tool Kit for DX12 uses Shader Model 6.

Adding to a VS solution

Using project-to-project references

In your application's solution, right-click on the Solution and use Add \ Existing Project... to add the appropriate .vcxproj file to your solution.

DirectXTK_Desktop_2022_Win10	Windows desktop applications for Windows 10/Windows 11 building with VS 2022 Community, Professional or higher with the latest installed Windows SDK.
DirectXTK_Windows10_2022	Universal Windows Platform (UWP) apps building with VS 2022 with the latest installed Windows SDK.
DirectXTK_GDK_2022	Windows 10, Windows 11, and Xbox games building with VS 2022 using the Microsoft GDK.

DirectXTK_Desktop_2019_Win10	Windows desktop applications for Windows 10/Windows 11 building with VS 2019 Community, Professional or higher with the latest installed Windows SDK.
DirectXTK_Windows10_2019	Universal Windows Platform (UWP) apps building with VS 2019 with the latest installed Windows SDK.
DirectXTK_GDK_2019	Windows 10, Windows 11, and Xbox games building with VS 2019 using the Microsoft GDK.

For VS 2019, use of the 16.11 is required as all previous versions are no longer supported.

In your application's project, right-click on the Project and use "References...", then "Add New Reference...", and then check the DirectXTK12 project name and click OK.

In your application's project settings, on the "C++ / General" page set Configuration to "All Configurations", set Platform to "All Platforms", and then add the relative path to DirectXTK12\inc;--assuming you have the DirectXTK12 folder in the same directory as your sln file, it should be $(SolutionDir)\DirectXTK12\inc;--to the Additional Include Directories properties. Click Apply.

Settings dialog

All DirectXTK12 projects are built to require Windows 10, so DirectX Tool Kit for Audio is included which makes use of XAudio 2.9, built into Windows 10, Windows 11, and Windows SDK.

Using NuGet package manager

Alternatively you can use NuGet to install one of the DirectX Tool Kit packages. Use Project / Manage NuGet Packages... then select "Browse", make sure the Package source is set to "nuget.org", and search for "DirectXTK12".

directxtk12_desktop_2019	This NuGet is configured for Windows desktop C++ applications building for Windows 10/Windows 11 with VS2019 or VS 2022 Community/Professional or higher.
directxtk12_uwp	This NuGet is configured for Universal Windows Platform apps for Windows 10/Windows 11 building with VS2019 or VS 2022 Community/Professional or higher.

You should use the NuGet interface to check for updates if you have an older version installed.

Archived

This package is no longer supported:

Using the vcpkg C++ library manager

The DirectX Tool Kit is also available through the vcpkg C++ Library Manager.

vcpkg install directxtk12

For the 64-bit version of the library, use:

vcpkg install directxtk12:x64-windows

For the Universal Windows Platform (UWP) versions, use:

vcpkg install directxtk12:x64-uwp

arm, arm64, x86, x64, windows, windows-static, windows-static-md, and uwp triplets are supported.

Windows Subsystem for Linux (i.e. arm64-linux and x64-linux) is not supported.

The vcpkg port supports five optional features. The default is to build without DirectX Tool Kit for Audio support except UWP which always includes it.

tools: Installs MakeSpriteFont and xwbtool command-line tools
spectre: Builds the library with Spectre-mitigation enabled
xaudio2-8 Use XAudio 2.8 for Windows 8.x or later support
xaudio2-9 Use XAudio 2.9 for Windows 10/Windows 11
xaudio2redist Use the XAudio2Redist for Windows 7 SP1 or later support

For Xbox Series X|S with the Microsoft GDK with Xbox Extensions installed:

./vcpkg install directxtk12:x64-xbox-scarlett

For Xbox One with the Microsoft GDK with Xbox Extensions installed:

./vcpkg install directxtk12:x64-xbox-xboxone

CMake

You can reference the DirectX Tool Kit CMake package using:

find_package(directxtk12 CONFIG REQUIRED)

target_link_libraries(foo Microsoft::DirectXTK12)

If using vcpkg C++ Package Manager, then you add the CMAKE_TOOLCHAIN_FILE path to vcpkg\scripts\buildsystems\vcpkg.cmake. If not using vcpkg, you need to provide a per-configuration path to the installed location in the directxtk12_DIR variable. Otherwise the find_package will fail.

vcpkg toolchain setting

There are also CMakePresets.json files available for the CMake projects on directx-vs-templates that use the VCPKG_ROOT environment variable to locate the VCPKG install directory. See the commented out code in CMakeLists.txt, Game.cpp, Game.h, and pch.h as well.

Dependencies

The DirectX Tool Kit library assumes your binary is linking with the following system libraries:

d3d12.lib: Provides the Direct3D device creation function D3D12CreateDevice
dxgi.lib: Provides the DXGI factory creation function CreateDXGIFactory1 / CreateDXGIFactory2
dxguid.lib: Provides COM GUID values for IID_ID3D12Device, IID_ID3D12Resource, etc.
windowscodecs.lib or uuid.lib: Provides COM GUID values for WIC usage such as CLSID_WICImagingFactory, CLSID_WICImagingFactory1, CLSID_WICImagingFactory2, etc.
For Win32 desktop applications, ole32.lib: Provides CoCreateInstance. For other platforms, this export is in the umbrella library (WindowsApps.lib, onecore.lib, etc.).

DirectX Tool Kit for Audio

For "Windows 10" configurations of the AudioEngine class, you'll need to use xaudio2.lib.

GamePad

For "Windows 10" configurations of the GamePad class that use Windows.Gaming.Input, you need runtimeobject.lib for Win32 desktop apps. For UWP apps, this is already handled with the umbrella lib Windowsapp.lib.

For the "Gaming.Desktop.x64" platform configuration in the Microsoft GDK, the GamePad class uses XInput 1.4 via xinput.lib.

For "Gaming.Xbox.*.x64" platform configurations in the Microsoft GDKX, the GamePad class uses GameInput which in the xgameplatform.lib umbrella lib.

Content pipeline

To use the Visual Studio graphics assets tools in the build system, be sure to add them to your project.

Note: When adding .spritefont, .sdkmesh, or .xwb files to your Universal Windows Platform (UWP) app or Xbox One app project, you need to manually set the file properties to "Content: Yes" for all configurations to have these files included in your AppX package. .dds files, other image file formats, and .wav files are automatically detected as a media file and are included as content by default.

Error handling

DirectXTK makes use of C++ exception handling which should be enabled by the application via the /EHsc compiler switch. In Visual Studio, this is set in the project settings under "C++ / Code Generation" with Enable C++ Exceptions set to "Yes (/EHsc)" for all configurations.

Smart-pointers and reference counting

DirectXTK encourages and makes use of a number of smart-pointers to simplify resource lifetime tracking.

std::unique_ptr - A smart-pointer that has exactly one 'owner' of the memory
std::shared_ptr - A smart-pointer that tracks memory use with reference counting
Microsoft::WRL::ComPtr - A COM smart-pointer for reference count management very similar to ATL's CComPtr
Smart Pointers (Modern C++)
Managing the Lifetime of an Object
COM Coding Practices
Reference Counting (Direct3D 10)

Feature Level Notes

The minimum Direct3D Hardware Feature Level supported for DirectX 12 is Feature Level 11.0 (i.e. there are no WDDM 2.0 drivers planned to support DirectX 12 on 9.x or 10.x feature levels). The DirectX Tool Kit for DirectX 12 therefore assumes the hardware features and resource size limitations defined for Direct3D Feature Level 11.0

Platform support

DirectX Tool Kit for DirectX 12 requires Windows 10. If you want support for Windows 8.x or Windows 7, you should use DirectX Tool Kit for DirectX 11. You cannot use both versions of the DirectX Tool Kit in the same application EXE/DLL as many of the names conflict. You are expected to use one or the other.

There is a version of DirectX 12 available for Windows 7 SP1 along with a down-level XAudio 2.9, but this is not a scenario I've tested beyond enabling D3D12_DEBUG_FEATURE_EMULATE_WINDOWS7 in my test suite. For more information on Windows 7 support, see GitHub. Note that there is no support for DirectX 12 on Windows 8.x.