directxtk-usage

name	directxtk-usage
description	Guide for integrating DirectX Tool Kit for DirectX 11 into new projects and understanding the API surface. Use this skill when asked about how to use DirectX Tool Kit, integrate it into a project, or get an overview of its classes and functionality.
license	MIT
metadata	{"author":"chuckw","version":"1.0"}

DirectX Tool Kit for DirectX 11 — Usage Guide

Overview

The DirectX Tool Kit (aka DirectXTK) is a collection of helper classes for writing DirectX 11.x code in C++. It is designed to be used as a shared source project, NuGet package, or vcpkg port integrated into your game or graphics application.

• Repository: https://github.com/microsoft/DirectXTK
• Documentation: https://github.com/microsoft/DirectXTK/wiki
• NuGet Packages: directxtk_desktop_win10, directxtk_uwp
• vcpkg Port: directxtk

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": [
    "directxmath",
    "directxtk"
  ]
}

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": [
    "directxmath",
    {
      "name": "directxtk",
      "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": [
    "directxmath",
    {
      "name": "directxtk",
      "default-features": false,
      "features": [
        "gameinput",
        "xaudio2-9"
      ]
    }
  ]
}

vcpkg (classic)

vcpkg install directxtk

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(directxtk CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE Microsoft::DirectXTK)

See the d3d11game_vcpkg template for a complete example.

NuGet

Use directxtk_desktop_win10 for Win32 desktop applications or directxtk_uwp for UWP apps.

Project Reference

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

Minimum Setup

Every DirectXTK application needs:

1. A Direct3D 11 device
2. A Direct3D immediate device context
3. The application is responsible for the rendering, SwapChain management, and Present loop

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

DirectXTK 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 DirectXTK objects are device-dependent — they are created with a ID3D11Device* and must be recreated if the device is lost. Plan your resource management accordingly.

Thread Safety

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

Namespace

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

#include "SpriteBatch.h"

// Usage:
auto spriteBatch = std::make_unique<DirectX::SpriteBatch>(context);

Common Patterns

Drawing Sprites

#include "SpriteBatch.h"
#include "WICTextureLoader.h"

// Create
auto spriteBatch = std::make_unique<DirectX::SpriteBatch>(context);
ComPtr<ID3D11ShaderResourceView> texture;
DirectX::CreateWICTextureFromFile(device, L"cat.png", nullptr, texture.GetAddressOf());

// Draw
spriteBatch->Begin();
spriteBatch->Draw(texture.Get(), DirectX::XMFLOAT2(100, 100));
spriteBatch->End();

Loading and Drawing a 3D Model

#include "Model.h"
#include "CommonStates.h"
#include "Effects.h"

// Create
auto states = std::make_unique<DirectX::CommonStates>(device);
auto fxFactory = std::make_unique<DirectX::EffectFactory>(device);
auto model = DirectX::Model::CreateFromSDKMESH(device, L"ship.sdkmesh", *fxFactory);

// Draw
model->Draw(context, *states, world, view, projection);

Drawing Geometric Primitives

#include "GeometricPrimitive.h"

auto sphere = DirectX::GeometricPrimitive::CreateSphere(context);
sphere->Draw(world, view, projection);

Using Effects

#include "Effects.h"

auto effect = std::make_unique<DirectX::BasicEffect>(device);
effect->SetWorld(world);
effect->SetView(view);
effect->SetProjection(projection);
effect->SetTexture(textureSRV.Get());
effect->Apply(context);

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();

Getting Started Tutorial

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

Further Reading

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