Getting Started

This is the Getting Started tutorial for DirectX Tool Kit which introduces the reader to using the DirectX Tool Kit with DirectX 11 in C++. This takes the form of a series of tutorial lessons for introducing the various functional parts of the tool kit. If you are just looking for basic integration instructions, see Adding to a VS solution.

If you are looking to use DirectX 12 and are already familiar with Direct3D 11, the place to start is the DirectX Tool Kit for DirectX 12 tutorials. Keep in mind that DirectX 12 is an expert API which builds on knowing the ins & outs of DirectX 11, and can be an unforgiving API to developers new to Direct3D or graphics in general.

Background

This tutorial assumes the reader is familiar with the basics of C++ programming using Microsoft Visual C++, including writing code, building applications, and basic debugging. Coding conventions here will make use of C++11 language features such as nullptr, auto, ranged-based for loops, simple lambdas (aka anonymous functions), the standard smart-pointer std::unique_ptr / std::make_unique<T>(), and std::function<>. Familiarity with the Standard C++ Library std::wstring and the std::vector container are required as well.

If you are more comfortable with C#, then you should consider SharpDX and read this blog post.

This tutorial does not assume prior experience with Direct3D, but the reader should be familiar with the basic graphics concepts for DirectX or OpenGL. That said, you can get a long way using DirectX Tool Kit without much in the way of graphics experience. You may also find it useful to review the Programming Guide for Direct3D 11 on Microsoft Docs.

Note that Direct3D 11 and DirectX Tool Kit are not Windows Runtime (aka "WinRT") components, so we do not make use of the C++/CX language extensions (a.k.a. /ZW switch) or C++/WinRT language projections, although it is compatible with both of those programming models. DirectX Tool Kit is a 'pure' C++ library, which is why it's not directly usable by Visual Basic, C# or HTML+JavaScript applications.

Error handling

One thing that many C++ developers, particularly game developers, may not be all that familiar with is "C++ Exception Handling". This is distinct from "Structured Exception Handling" (SEH) which some developers have seen in the past, and can leave an unfavorable impression of C++ EH. On both ARM and x64 native platforms, C++ EH is very efficient, although the x86 32-bit implementation does have some quirks. In any case, DirectX Tool Kit uses C++ Exception Handling for most error conditions, just as the Standard Template Library (STL) does and the standard behavior of the operator new.

For debugging exceptions thrown by the DirectX Tool Kit, you should enable the checkbox next to std::exception in the Visual Studio Exception Settings dialog (Debug -> Windows -> Exception Settings). It's not on by default. Then select the "C++ Exceptions" line, right-click and select the + button, and type DirectX::com_exception to add that one. If working with the Direct3D VS Game templates you should do this once more typing DX::com_exception.

Exception Settings

For some more detail on how the Visual Studio debugger deals with exceptions, read this blog post.

Audience

These tutorials are written with game development in mind as the target application since games are an excellent fit for the 'immersive DirectX app' model. Keep in mind, however, that the majority of the functionality in the DirectX Tool Kit is applicable to DirectX graphics programming in general for both game and non-game applications.

System requirements

The DirectX Tool Kit for DirectX 11 tutorials assume you are using Windows 7 Service Pack 1, Windows 8.1, Windows 10 or Windows 11. The DirectX Tool Kit supports D3D_FEATURE_LEVEL_9_1 Direct3D hardware feature level or greater. Any use of 32-bit index buffers (DXGI_FORMAT_R32_UINT) requires at least D3D_FEATURE_LEVEL_9_2.

A few features such as DebugEffect, DGSLEffect, NormalMapEffect, PBREffect, PostProcess, and dual-parabolic environment maps require D3D_FEATURE_LEVEL_10_0 or better.

Older versions of the tool kit supported Windows phone 8 and Windows Vista SP2 with KB971644.

Software setup

For learning purposes, these instructions are going to focus on the following setup:

Visual Studio 2019 (16.11) or VS 2022 Community, Professional, Premium, or Ultimate
Windows 10 SDK (19041 is the minimum supported version)
Windows 7 Service Pack 1, Windows 8.1, Windows 10 (May 2020 Update a.k.a. Version 2004 or later is recommended), or Windows 11.

We will be using a Win32 desktop application project template in order to support developers using Windows 7, but all these techniques and APIs apply to Universal Windows Platform apps and Xbox as well.

There is no need to install the legacy DirectX SDK to use DirectX Tool Kit. The DirectX SDK is deprecated and you should not use it per Microsoft Docs. See this blog post, The Zombie DirectX SDK, DirectX SDK Samples Catalog, and DirectX SDK Tools Catalog.

Visual Studio 2019 / 2022

When using the new lightweight installer be sure to select the appropriate workloads:

Workload: Game development with C++ or Desktop development with C++

For UWP apps, include:

Workload: Universal Windows Platform development
Optional component: C++ Universal Windows Platform tools

Samples

For a quick introduction to DirectX 11 programming, take a look at the Introductory Graphics samples on Xbox-ATG-Samples.

Basic drawing: SimpleTriangle
Basic texturing: SimpleTexture
Basic lighting: SimpleLighting
DirectCompute: SimpleCompute
Tessellation: SimpleBezier
Instancing: SimpleInstancing
Multisample Antialiasing: SimpleMSAA

The official samples for DirectX 11 were originally shipped in the legacy DirectX SDK. There is an unofficial repository of these samples available on GitHub: directx-sdk-samples that have been updated to remove most of their legacy dependencies. There are a few additional DirectX 11 samples on directx-sdk-legacy-samples