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 2022 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.

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 GameInput 'v0' and links to gameinput.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.1, 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

Integration

Implementation