Getting Started

This is the Getting Started tutorial for DirectX Tool Kit which introduces the reader to using the DirectX Tool Kit with DirectX 12 in C++.

If you are new to DirectX, the place to start is the DirectX Tool Kit for DirectX 11 tutorials. DirectX 12 is an expert API which builds on knowing the ins & outs of DirectX 11. DirectX 12 is an extremely low-level API designed for graphic experts who have a solid understanding of the architecture of modern GPU hardware. Both DirectX 11 and DirectX 12 provide access to the same hardware features on Windows 10, but drive the hardware in different ways which can allow a well-optimized DirectX 12 engine to achieve much lower CPU overhead than in DirectX 11.

That said, if you already know the DirectX 11 version of DirectX Tool Kit, you'll find the DirectX 12 version familiar and will have an easier time with the transition.

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, simple lambdas (aka anonymous functions), and the standard smart-pointer std::unique_ptr / std::make_unique<T>(), but will generally be otherwise 'core' C++. Some aspects of the library make use of perfect-forwarding and variadic templates in the implementation, but the client code doesn't need to use these features directly. There is also one class that requires basic use of std::future.

If you are more comfortable with C#, then you should consider SharpDX.

The tutorial assumes the reader is already familiar with the DirectX 12 API, and is an expert in graphics programming. If you are already an expert in Direct3D 11 but are new to the DirectX 12 API, then you should start by reviewing the Direct3D 12 Programming Guide on Microsoft Docs.

Note that Direct3D 12 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, click the PLUS 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. DirectX 12 can also be used for non-game applications. The reader is assumed to be familiar with Direct3D programming and have a basic understanding of the DirectX 12 API.

System requirements

The DirectX Tool Kit for DirectX 12 tutorials assume you are using Windows 10. You also need a graphics card with DirectX 12 capable drivers. The DirectX Tool Kit only requires the D3D_FEATURE_LEVEL_11_0 Direct3D hardware feature level with Shader Model 6 support.

While a version of DirectX 12 is available for Windows 7 SP1 along with a down-level XAudio 2.9, this is not a good development environment for DirectX 12 applications. Tools like PIX, the debug layer, etc. are only available on Windows 10, so you should use Windows 10 for development even if planning to utilize the Windows 7 support.

For more information on Windows 7 support, see GitHub. Note that there is no support for DirectX 12 on Windows 8.x.

Software setup

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

Visual Studio 2017 (15.9 update) or Visual Studio 2019 Community, Professional, Premium, or Ultimate
Windows 10 SDK (19041 is recommended)
Windows 10 (May 2020 Update a.k.a. Version 2004 is recommended)

We will be using a Win32 desktop application project template, but all these techniques and APIs apply to Universal Windows Platform (UWP) 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 has no DirectX 12 material. Since the DirectX Tool Kit for DirectX 12 projects are built with _WIN32_WINNT set to 0x0A00, DirectX Tool Kit for Audio will make use of XAudio 2.9 which is included with Windows 10 and the Windows 10 SDK. There is also no need to use the DXSDK_DIR environment variable. This was only used by the legacy DirectX SDK and by an early DirectX 12 SDK Beta. The DirectX 12 headers & libraries are part of the standard Windows 10 SDK.

Visual Studio 2017 / 2019

When using the new lightweight installer be sure to select the appropriate workloads. Here are the recommended options to select:

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

Utility Header

The D3DX12.H utility header is not part of the Windows 10 SDK, nor is it a part of the DirectX Tool Kit. It's commonly used in DirectX 12 C++ programming, and is included as part of a number of templates including the Direct3D Game Visual Studio templates used for this tutorial. It's not actually required for DirectX 12 development, but it does contain useful helper code. You can obtain the latest version of this utility header from GitHub. See the wiki for more details.

Note that for Xbox development, D3DX12_X.H and D3DX12_XS.H are in the Xbox One XDK / Microsoft GDKX.

Samples

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

Basic drawing: SimpleTriangle12
Basic texturing: SimpleTexture12
Basic lighting: SimpleLighting12
DirectCompute: SimpleCompute12
Tessellation: SimpleBezier12
Instancing: SimpleInstancing12
Multisample Antialiasing: SimpleMSAA12

The official samples for DirectX 12 are available on GitHub.

Tutorials

Graphics

Input, Math, Audio

For materials on using DirectX Tool Kit's Input, Math, and Audio support, see the DirectX Tool Kit for DirectX 11 tutorials as all those types and classes are identical.