Direct3D Game Visual Studio templates (Redux)

direct3d, uwp, visualc

Originally posted to Chuck Walbourn's Blog on MSDN, Dec 17, 2015

Back in January, I released a D3D11Win32Game Visual Studio 2013 template for Win32 desktop development primarily to support my DirectX Tool Kit tutorials. I modeled it after the basic template that we ship with the Xbox One XDK that consist of a Game class which sets up a device, swap chain, and timed rendering loop. I’ve since updated the templates on GitHub and now have versions for VS 2015, for the Universal Windows Platform, for Direct3D 12, and versions with the DeviceResources abstraction that is used in the official Windows Store and UWP templates.

VS Express users: I recommend taking a look at the VS Community edition which supports Windows desktop development if you don’t have the budget for purchasing a license for the Pro+ editions

Using the VSIX

To install: VS 2013 users should run Direct3DWin32Game.vsix (July 2017), VS 2015 users should run Direct3DUWPGame.vsix (October 2019), VS 2017 users should run Direct3DUWPGame.vsix (March 2022), and VS 2019 / VS 2022 users should run Direct3DUWPGame.vsix. These packages install all the templates supported for that version of Visual Studio under the “Visual C++” node of the New Project dialog. If you have Visual Studio open, you should shut it down and restart it. If you have an older version installed of this VSIX installed, you should uninstall the old one first.

To remove: Go to Tools / Extensions and Updates… then uninstall “Direct3DWin32Game” or “Direct3DUWPGame”.

Template	VS 2013	VS 2015 / 2017 / 2019 / 2022	Description
Direct3D Win32 Game	ü	ü	Win32 desktop Direct3D 11 Game template
Direct3D Win32 Game DR	ü	ü	Win32 desktop Direct3D 11 Game template with `DeviceResources` abstraction
Direct3D UWP Game	û	ü	Universal Windows app Direct3D 11 Game template using C++/CX (`/ZW`)
Direct3D UWP Game (C++/WinRT)	û	ü	Universal Windows app Direct3D 11 Game template using C++/WinRT language projections.
Direct3D UWP Game DR	û	ü	Universal Windows app Direct3D 11 Game template with `DeviceResources` abstraction using C++/CX
Direct3D UWP Game DR (C++/WinRT)	û	ü	Universal Windows app Direct3D 11 Game template with `DeviceResources` abstraction using C++/WinRT
Direct3D 12 Win32 Game	û	ü	Win32 desktop Direct3D 12 Game template
Direct3D 12 Win32 Game DR	û	ü	Win32 desktop Direct3D 12 Game template with `DeviceResources` abstraction
Direct3D 12 UWP Game	û	ü	Universal Windows app Direct3D 12 Game template using C++/CX
Direct3D 12 UWP Game (C++/WinRT)	û	ü	Universal Windows app Direct3D 12 Game template using C++/WinRT
Direct3D 12 UWP Game DR	û	ü	Universal Windows app Direct3D 12 Game template with `DeviceResources` abstraction using C++/CX
Direct3D 12 UWP Game DR (C++/WinRT)	û	ü	Universal Windows app Direct3D 12 Game template with `DeviceResources` abstraction using C++/WinRT

DirectX 12: The Direct3D 12 versions of the template set _WIN32_WINNT to 0x0A00 (Windows 10), while the Direct3D 11 versions still use 0x0600 (Windows Vista). You need to have the Windows 10 SDK installed to build the Direct3D 12 templates, and Windows 10 to run it.

UWP: You have to be using Windows 8.1 or Windows 10 with the Windows 10 SDK installed to build the UWP templates. You need a Windows 10 device to run it.

C++/WinRT: See this post for more information. C++/WinRT–prior to the Windows 10 SDK (17134)–requires the cppwinrt NuGet package.

DeviceResources

The basic template puts all the code for creating the device and swapchain into the main Game class. This makes it very simple to reference especially in the tutorial lessons. This does have the result, however, of putting a fair amount of ‘boiler plate’ code that clutters up the main Game class. The alternative for larger projects are the “DR” versions which add a helper class called DeviceResources. This class owns the Direct3D device, the DXGI swap chain, the depth/stencil buffer, and the render views needed for basic rendering. This does requires a few changes in the Game class.

Game::Game()
{
    m_deviceResources = std::make_unique<DX::DeviceResources>();
    m_deviceResources->RegisterDeviceNotify(this);
}

void Game::Initialize(HWND window, int width, int height)
{
    m_deviceResources->SetWindow(window, width, height);

    m_deviceResources->CreateDeviceResources();
    CreateDeviceDependentResources();

    m_deviceResources->CreateWindowSizeDependentResources();
    CreateWindowSizeDependentResources();
    ...
}

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

    Clear();

    // TODO: Add your rendering code here.

    m_deviceResources->Present();
}

// Helper method to clear the back buffers.
void Game::Clear()
{
    // Clear the views
    auto context = m_deviceResources->GetD3DDeviceContext();
    auto renderTarget = m_deviceResources->GetBackBufferRenderTargetView();
    auto depthStencil = m_deviceResources->GetDepthStencilView();

    context->ClearRenderTargetView(renderTarget, Colors::CornflowerBlue);
    context->ClearDepthStencilView(depthStencil, D3D11_CLEAR_DEPTH, 1.0f, 0);
    context->OMSetRenderTargets(1, &renderTarget, depthStencil);

    // Set the viewport.
    auto viewport = m_deviceResources->GetScreenViewport();
    context->RSSetViewports(1, &viewport);
}

void Game::CreateDeviceDependentResources()
{
    // TODO: Initialize device dependent objects here (independent of window size).
}

// Allocate all memory resources that change on a window SizeChanged event.
void Game::CreateWindowSizeDependentResources()
{
    // TODO: Initialize windows-size dependent objects here.
}

void Game::OnDeviceLost()
{
    // TODO: Add Direct3D resource cleanup here.
}

void Game::OnDeviceRestored()
{
    CreateDeviceDependentResources();

    CreateWindowSizeDependentResources();
}

A few key things to note about this code compared with the non-DR version:

The Game::CreateDevice method has been replaced with a call to DeviceResources::CreateDeviceResources and Game::CreateDeviceDependentResources.
The Game::CreateResources method has been replaced with a call to DeviceResources::CreateWindowSizeDependentResources and Game::CreateWindowSizeDependentResources.
The Game::OnDeviceLost method is now a callback from DeviceResources and only handles the cleanup. The Game::OnDeviceRestored call is made when the device has been re-recreated.
The usage difference can be seen in Game::Clear where instead of using local member variables, accessors on DeviceResources are used to obtain the device, context, etc.

Otherwise the DR version of the template is the same as the original D3DGame templates, including using StepTimer. See this page for a more detailed overview.

DirectX 12: The details of the Direct3D 12 versions of DeviceResources is different than the Direct3D 11 version since the APIs are quite different, but it’s the same design. See this page for a more detailed overview.

VS 2013 vs. 2015: Note there is one minor code difference between the VS 2013 and VS 2015 version of the templates because VS 2013 does not support C++11 uniform initialization. Otherwise the code is basically the same. VS 2015 is required for UWP development, and the Windows 10 SDK is required for Direct3D 12 development which only officially integrates with VS 2015–you can use a props solution to get it to work with VS 2013.

Note that the VS 2013 version of the template was last updated in July 2017.

VS 2017: Direct3DUWPGame.vsix (March 2017 or later) supports both VS 2015 and VS 2017. On VS 2015, it will use Platform Toolset v140 while for VS 2017 it uses v141. The Direct3D 11 Win32 game template originally used the VS 2015 default Windows 8.1 SDK while the other templates all require a Windows 10 SDK. Since VS 2017 only includes a Windows 10 SDK by default, the Direct3D 11 Win32 game template and it’s DeviceResources variant now trigger the same Windows 10 SDK selection wizard as the UWP and Direct3D 12 templates.

VS 2019: Direct3DUWPGame.vsix (April 2019 or later) now supports VS 2015, 2017, and 2019. It uses a Platform Toolset of v140, v141, or v142 accordingly. You can also change it to use clang-cl. Note that VS 2015 support was dropped starting in March 2020.

VS 2022: The latest version of the Direct3DUWPGame.vsix (October 2021 or later) now supports VS 2017, 2019, and 2022. It uses a Platform Toolset of v141, v142, or v143 accordingly. You can also change it to use clang-cl. Note that for Win32 desktop projects, it no longer prompts for Windows SDK selection. Instead it uses Windows 10 SDK (19041) for VS 2017 or “Use latest installed” (10.0) for VS 2019 / VS 2022. For UWP projects, it still uses the SDK selection dialog.

Games for Windows and the DirectX SDK blog

Using the VSIX

DeviceResources