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 Xbox One exclusive application XBoxDDSTextureLoader functions are in the Xbox C++ namespace.

Modules

• Audio - low-level audio API using XAudio2
  • AudioEngine, SoundEffect, SoundEffectInstance, SoundStreamInstance, DynamicSoundEffectInstance, WaveBank, AudioListener, AudioEmitter
• BufferHelpers - C++ helpers for creating D3D resources from CPU data
• CommonStates - factory providing commonly used D3D state objects
• DDSTextureLoader - light-weight DDS file texture loader
• DirectXHelpers - misc C++ helpers for D3D programming
• Effects - set of built-in shaders for common rendering tasks
  • IEffectFactory, EffectFactory, PBREffectFactory, DGSLEffectFactory
  • IEffect, IEffectMatrices, IEffectLights, IEffectFog, IEffectSkinning
  • AlphaTestEffect, BasicEffect, DualTextureEffect, EnvironmentMapEffect, SkinnedEffect
  • NormalMapEffect, SkinnedNormalMapEffect
  • PBREffect, SkinnedPBREffect
  • DebugEffect
  • DGSLEffect, SkinnedDGSLEffect
• GamePad - gamepad controller helper using XInput or Windows.Gaming.Input
• GeometricPrimitive - draws basic shapes such as cubes and spheres
• GraphicsMemory - helper for managing dynamic graphics memory allocation
• Keyboard - keyboard state tracking helper
• Model - draws simple 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
• ScreenGrab - light-weight screen shot saver
• SimpleMath - simplified C++ wrapper for DirectXMath
  • Rectangle, Vector2, Vector3, Vector4, Matrix, Quaternion, Plane, Ray, Color, Viewport
• 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

Tools

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

Building

This code is designed to build with Visual Studio 2022 or later. It requires the Windows SDK (19041) or later for functionality such as the DirectXMath library and the DXGI 1.2 headers.

These components are designed to work without requiring any content from the DirectX SDK. For details, see Where is the DirectX SDK?, Where is the DirectX SDK (2021 Edition)?, and The Zombie DirectX SDK.

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. ...\DirectXTK\Src\Shaders)

Dependencies

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

• d3d11.lib: Provides the Direct3D device creation function D3D11CreateDevice
• dxgi.lib: Provides the DXGI factory creation function CreateDXGIFactory1 / CreateDXGIFactory2
• dxguid.lib: Provides COM GUID values for IID_ID3D11Device, WKPDID_D3DDebugObjectName, 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 configurations of the AudioEngine class, you'll need to use xaudio2.lib.

For XAudio2Redist, the Microsoft.XAudio2.Redist NuGet package provides the xaudio2_9redist.lib.

GamePad

For "Windows 10" and "Windows 11" 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 "Windows 8.1" configurations of the GamePad class using XInput 1.4, you'll need xinput.lib.

For the "Gaming.Desktop.x64" platform configuration in the Microsoft GDK, the GamePad class uses GameInput 'v0' and links to gameinput.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) or Xbox One 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

Visual Studio Express editions have limited exception handling debugging support, so consider using VS Community or Pro+ instead.

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)

Additional information

Integration

Implementation