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.

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.

See also the Visual C+ Team Blog

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:

• Windows desktop app using VS 2017
• Windows desktop app using VS 2015

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.

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.

• C++ Exception Handling
• How to: Break When an Exception is Thrown
• Dual-use Coding Techniques for Games
• Resource Acquisition Is Initialization
• ThrowIfFailed

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.

Additional information

Textures

Resource Barriers

PSOs, Shaders, and Signatures

Memory Management

Shader Model 6

Multi-GPU

Implementation