Adding the DirectX Tool Kit

Getting Started

After creating a new project in Using DeviceResources, the next step is to add the DirectX Tool Kit library and headers to the project so we can make use of it in our code.

NuGet package manager

The easiest way to achieve this is to use the NuGet package manager built into Visual Studio.

• From the drop-down menu, select Project / Manage NuGet Packages...
• Select "Browse" on the top tab, and make sure the Package source is set to "nuget.org"
• In the text search field type "DirectXTK12" and hit enter to search for the packages
• Select the package with the id directxtk12_desktop_2019 for Win32 or directxtk12_uwp for UWP
• Select "Install"
• When finished, close the NuGet Manager

You can check for updates to the NuGet package by selecting "Updates" in the top tab.

Both directxtk12_desktop_2019 and directxtk12_uwp support VS 2022 as well since they are all binary compatible.

Project-to-project references

Another option rather than using NuGet is to use Visual Studio's project-to-project references. This approach is a little more setup, but it does ensure that you are building the full DirectX Tool Kit library as part of your solution, and allows you to make changes directly to the tool kit if desired as well.

• Extract the release .zip file into a directory relative to the new project you created. For this tutorial, we will assume the DirectXTK12 folder is in the same folder as your new project's Visual Studio Solution (.sln) file.
• Right-click on your solution in the Solution Explorer, and select Add / Existing Project...
• Browse into the "DirectXTK12" folder and select DirectXTK_Desktop_20xx_Win10.vcxproj for Win32 -or- DirectXTK_Windows10_20xx.vcxproj for UWP, click "Open"
• If Visual Studio presents a "Security Warning", select "OK". Optional: Uncheck "Ask me for every project in this solution" first.
• Right-click on your project in the Solution Explorer, and select Add / Reference...
• Check DirectXTK12 and select "OK"
• Click on "Configuration Properties" in the left-hand tree view, then C/C++ / General
• Select "All Configurations" and "All Platforms"
• Edit Additional Include Directories to the relative path to the DirectXTK12\Inc folder. With our original assumption, you can use $(SolutionDir)\DirectXTK12\Inc.
• Select "OK"

For more information see DirectXTK under Adding to a VS solution.

For Xbox One XDK and Microsoft GDK on Xbox apps, you have to use project-to-project references instead of NuGet to ensure the built library matches the XDK/GDK edition specific headers and shader generation.

CMake projects

Using directly as a sub-project

For a CMake project, you can copy/clone the DirectXTK12 library into your CMake project repository, and add:

add_subdirectory(${CMAKE_SOURCE_DIR}/DirectXTK12 ${CMAKE_BINARY_DIR}/bin/CMake/DirectXTK12)
target_link_libraries(${PROJECT_NAME} PRIVATE DirectXTK12)

If using MinGW/GNUC, you should make use of the vcpkg solution instead. MinGW does not provide a working version of DirectXMath or Direct3D 12 headers, and vcpkg will provide them via the directxmath and directx-headers ports. Alternatively, you can manually build/install instances directly from GitHub for DirectXMath and DirectX-Headers.

vcpkg C++ Package Manager

For a CMake project, the DirectX Tool Kit is available as a CMake package, which you reference from your CMakeLists.txt as:

find_package(directxtk12 CONFIG REQUIRED)

target_link_libraries(${PROJECT_NAME} PRIVATE
    d3d12.lib dxgi.lib dxguid.lib uuid.lib
    kernel32.lib user32.lib
    comdlg32.lib advapi32.lib shell32.lib
    ole32.lib oleaut32.lib
    runtimeobject.lib
    Microsoft::DirectXTK12
)

You can build and install the cmake package version using vcpkg for the various 'flavors' you require:

vcpkg install directxtk12
vcpkg install directxtk12:x64-windows
vcpkg install directxtk12:arm64-uwp

If using CMakePresets.json set the environment variable VCPKG_ROOT and add:

"cacheVariables": {
  CMAKE_TOOLCHAIN_FILE": {
    value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
    "type": "FILEPATH"
  }
},

If not using vcpkg, you have to provide a per-configuration path to the individual installed package in the directxtk12_DIR variable:

The CMakeList.txt from directx-vs-templates for Win32 desktop and UWP C++/WinRT have commented out code to supporting VCPKG integration of directxtk12.

Adding the headers

Now that we have the DirectX Tool Kit usable in your project, the next step is to include the library headers into your project.

General advice for C++ projects is that you should only add the headers you actually use to your project, but to simplify the tutorial we will go ahead and add them all to your new project's pch.h header:

//
// pch.h
// Header for standard system include files.
//

#pragma once

...

#include "BufferHelpers.h"
#include "CommonStates.h"
#include "DDSTextureLoader.h"
#include "DescriptorHeap.h"
#include "DirectXHelpers.h"
#include "EffectPipelineStateDescription.h"
#include "Effects.h"
#include "GamePad.h"
#include "GeometricPrimitive.h"
#include "GraphicsMemory.h"
#include "Keyboard.h"
#include "Model.h"
#include "Mouse.h"
#include "PostProcess.h"
#include "PrimitiveBatch.h"
#include "RenderTargetState.h"
#include "ResourceUploadBatch.h"
#include "ScreenGrab.h"
#include "SimpleMath.h"
#include "SpriteBatch.h"
#include "SpriteFont.h"
#include "VertexTypes.h"
#include "WICTextureLoader.h"

This does not include the DirectX Tool Kit for Audio header Audio.h which is covered by another tutorial.

Next, adding a C++ namespace using statement to your Game.cpp file will make it a bit easier to use the SimpleMath types:

//
// Game.cpp -
//

#include "pch.h"
#include "Game.h"

using namespace DirectX;
using namespace DirectX::SimpleMath;

using Microsoft::WRL::ComPtr;

...

Graphics memory

To finish off setup, in the Game.h file, add the following variable to the bottom of the Game class's private declarations:

std::unique_ptr<DirectX::GraphicsMemory> m_graphicsMemory;

In Game.cpp, add to the TODO of CreateDeviceDependentResources:

m_graphicsMemory = std::make_unique<GraphicsMemory>(device);

In Game.cpp, in Render add a call to GraphicsMemory Commit right after the present:

void Game::Render()
{
    // Don't try to render anything before the first Update.
    if (m_timer.GetFrameCount() == 0)
    {
        return;
    }

    // Prepare the command list to render a new frame.
    m_deviceResources->Prepare();

    auto commandList = m_deviceResources->GetCommandList();

    Clear();

    // TODO: Add your rendering code here.

    // Show the new frame.
    m_deviceResources->Present();
    m_graphicsMemory->Commit(m_deviceResources->GetCommandQueue());
}

In Game.cpp, add to the TODO of OnDeviceLost:

m_graphicsMemory.reset();

Technical notes

In DirectX 12, the application must manage the lifetime of all video memory resources. The GraphicsMemory class is a helper for managing allocations and lifetimes for an 'upload heap'. This is used for constant buffers, dynamic vertex & index buffers, and as a source for copying data to 'dedicated video memory' on the GPU. Lifetime is managed by 'fences' which are injected once per frame, in combination with reference counts. The Commit method must be called once-per-frame to ensure proper tracking and cleanup.

Shader Model 6

As of the June 2021 release of DirectX Tool Kit for DX12, the library requires Shader Model 6 support. The May 2021 or later version of the directx-vs-templates for DirectX 12 already include the relevant CheckFeatureSupport to validate this at startup. For more details, see Shader Model 6. If you see this debug message in your output window running this template, then you should see if your hardware has newer drivers and that you are on Windows 10 (14393) or later:

ERROR: Shader Model 6.0 is not supported

Platform notes

If you are using the DirectX Tool Kit with the Xbox One XDK or Microsoft GDK for Xbox, then you may need to build the Xbox shaders that match your release. Generally this is handled automatically, but if you run into problems you can build them directly from the Xbox Developer Command prompt using CompileShaders.cmd xbox or CompileShaders.cmd gxdk / CompileShaders.cmd gxdk scarlett.

Next lessons: Sprites and textures, Game controller input, Using the SimpleMath library, Adding audio to your project