Directxtk12 Usage Agent Skill

DirectX Tool Kit for DirectX 12 — Usage Guide

Overview

The *DirectX Tool Kit for DirectX 12* (DirectXTK12) is a collection of helper classes for writing Direct3D 12 C++ code for Win32 desktop applications (Windows 10+), Xbox Series X|S, Xbox One, and Universal Windows Platform (UWP) apps.

• Repository: <https://github.com/microsoft/DirectXTK12>
• Documentation: <https://github.com/microsoft/DirectXTK12/wiki>
• NuGet Packages: directxtk12_desktop_win10, directxtk12_uwp
• vcpkg Port: directxtk12

Integration Methods

vcpkg manifest-mode (Recommended)

In your vcpkg.json file, add the following:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "directx-headers",
    "directxmath",
    "directxtk12"
  ]
}

If using GameInput for the game input functionality, add the following:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "directx-headers",
    "directxmath",
    {
      "name": "directxtk12",
      "default-features": false,
      "features": [
        "gameinput"
      ]
    }
  ]
}

If using DirectX Tool Kit for Audio and GameInput, add the following:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "directx-headers",
    "directxmath",
    {
      "name": "directxtk12",
      "default-features": false,
      "features": [
        "gameinput",
        "xaudio2-9"
      ]
    }
  ]
}

vcpkg (classic)

vcpkg install directxtk12

Features: xaudio2-9 (DirectX Tool Kit for Audio using XAudio 2.9), gameinput (Using GameInput for gamepad, keyboard, and mouse), tools (command-line tools). Triplets: x64-windows, arm64-windows, etc.

For DLL usage (x64-windows default triplet), define DIRECTX_TOOLKIT_IMPORT in your consuming project. For static library usage, use -static-md triplet variants.

CMakeLists.txt:

find_package(directxtk12 CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE Microsoft::DirectXTK12)

Use the d3d12game_vcpkg template as a starting point.

NuGet

Use directxtk12_desktop_win10 for Win32 desktop applications or directxtk12_uwp for UWP apps.

Project Reference

Add the appropriate .vcxproj from the DirectXTK12/ folder to your solution and add a project reference. Add the DirectXTK12\Inc directory to your Additional Include Directories.

Minimum Requirements

• Windows 10 May 2020 Update SDK (19041) or later
• Visual Studio 2022, Visual Studio 2026, clang for Windows v12+, or MinGW 12.2
• Direct3D Feature Level 11.0 or higher

Getting Started

For a full step-by-step walkthrough, see the Getting Started tutorial on the wiki.

A minimal initialization sequence:

• Create a ID3D12Device.
• Create a GraphicsMemory instance (one per device).
• Create a DescriptorHeap for SRV/CBV/UAV descriptors.
• Use ResourceUploadBatch to upload textures and static buffers to the GPU.
• Create rendering helpers (e.g., SpriteBatch, Effects, Model) with the appropriate pipeline state.
• Each frame, call GraphicsMemory::Commit after executing command lists.

API Reference

The public API is defined in the header files in the Inc/ directory. See the reference overview for a categorized summary of all classes and helpers.

Full documentation for each class is available on the GitHub wiki.

API signatures are defined in the public headers under the Inc/ directory. Always consult those headers for the authoritative function signatures, parameters, and SAL annotations.

Key Concepts

Resource Ownership

DirectXTK12 classes follow RAII principles. Most objects are created with std::make_unique and destroyed automatically. COM resources are managed with Microsoft::WRL::ComPtr.

Device-Dependent vs Device-Independent

Most DirectXTK12 objects are device-dependent — they are created with a ID3D12Device* and must be recreated if the device is lost. Plan your resource management accordingly.

Thread Safety

DirectXTK12 rendering classes (SpriteBatch, Effects, PrimitiveBatch, etc.) are not thread-safe. Use one instance per thread, or synchronize access externally. Resource creation (texture loading, model loading) can be done from any thread.

Key Concepts for DirectX 12 Users

• Pipeline State Objects (PSOs): Unlike the DX11 version, DX12 requires explicit PSO management. Use EffectPipelineStateDescription and RenderTargetState to configure PSOs for effects and rendering helpers.
• Descriptor Heaps: Use DescriptorHeap to manage shader-visible descriptor heaps. Most rendering classes require descriptor heap indices at draw time.
• Resource Upload: GPU resources must be uploaded explicitly. ResourceUploadBatch batches uploads into a single command list for efficiency.
• Graphics Memory: GraphicsMemory manages per-frame dynamic allocations (constant buffers, dynamic vertex/index buffers). Call Commit once per frame.

Namespace

All classes and functions reside in the DirectX namespace. Headers that contain Direct3D 12-specific types use inline namespace DX12 to avoid conflicts when both DX11 and DX12 toolkits are linked together.

#include "SpriteBatch.h"

// Usage:
auto spriteBatch = std::make_unique<DirectX::SpriteBatch>(device, ...);

Common Patterns

Creating an Effect

#include "Effects.h"
#include "EffectPipelineStateDescription.h"
#include "RenderTargetState.h"

RenderTargetState rtState(DXGI_FORMAT_B8G8R8A8_UNORM, DXGI_FORMAT_D32_FLOAT);

EffectPipelineStateDescription pd(
    &VertexPositionNormalTexture::InputLayout,
    CommonStates::Opaque,
    CommonStates::DepthDefault,
    CommonStates::CullCounterClockwise,
    rtState);

auto effect = std::make_unique<BasicEffect>(device, EffectFlags::Lighting | EffectFlags::Texture, pd);

Loading and Drawing a Model

#include "Model.h"

auto model = Model::CreateFromSDKMESH(device, L"mymodel.sdkmesh");

// Upload resources
ResourceUploadBatch upload(device);
upload.Begin();
model->LoadStaticBuffers(device, upload);
upload.End(commandQueue).wait();

// Draw (simplified — see wiki for full parameter details)
model->Draw(commandList, ...);

Texture Loading

#include "DDSTextureLoader.h"
#include "ResourceUploadBatch.h"
#include "DescriptorHeap.h"

ResourceUploadBatch upload(device);
upload.Begin();

Microsoft::WRL::ComPtr<ID3D12Resource> texture;
CreateDDSTextureFromFile(device, upload, L"texture.dds", texture.ReleaseAndGetAddressOf());

upload.End(commandQueue).wait();

Input Handling

#include "Keyboard.h"
#include "Mouse.h"
#include "GamePad.h"

auto keyboard = std::make_unique<DirectX::Keyboard>();
auto mouse = std::make_unique<DirectX::Mouse>();
auto gamePad = std::make_unique<DirectX::GamePad>();

// In update loop
auto kb = keyboard->GetState();
if (kb.Escape)
    PostQuitMessage(0);

auto pad = gamePad->GetState(0);
if (pad.IsConnected())
{
    if (pad.IsAPressed())
        /* jump */;
}

Audio

#include "Audio.h"

// Create audio engine
auto audioEngine = std::make_unique<DirectX::AudioEngine>();

// Load and play a sound
auto soundEffect = std::make_unique<DirectX::SoundEffect>(audioEngine.get(), L"explosion.wav");
soundEffect->Play();

// Per-frame update
audioEngine->Update();

> Note: Code examples above are simplified for clarity. Consult the wiki tutorials and public headers in Inc/ for complete working code with all required parameters.

Further Reading

• DirectXTK Wiki
• DirectX Tool Kit for Audio
• SimpleMath documentation
• Project templates