Direct3D Win32 Game Visual Studio template


For people new to DirectX development, MSDN provides numerous tutorials for writing Windows Store apps, Windows phone apps, and Universal apps which all begin with creating a new project using a Visual Studio template built into to VS 2012 or VS 2013. For people targeting Win32 desktop (i.e. when developing on or for Windows 7), however, there’s no “DirectX” project template to be found in Visual Studio. Instead, you have to use the generic Win32 project and then add support for Direct3D such as is done with the Direct3D Win32 tutorial.

Ideally, I’d like a Win32 desktop project template that looks similar to the other C++ DirectX templates as a common starting point for some tutorials and other explanatory posts. And so, here it is! This is a Visual Studio extension for VS 2013 Pro, VS 2013 Premium, VS 2013 Ultimate, or VS 2013 Community which installs a Direct3D Win32 Game project template for Visual C++.

VS Express for Windows Desktop: I recommend taking a look at the VS 2013 Community edition if you don’t have the budget for purchasing a license for the VS 2013 Pro+ editions.

DirectX 12: The details of the Direct3D 12 versions of Direct3D Win32 Game 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.

Related: Direct3D Game Visual Studio templates (Redux)

Using the VSIX

To Install, launch Direct3DWin32Game.vsix on a system with VS 2013 installed. If VS 2013 was already open, exit and restart it.

To Uninstall, in VS 2013 go to Tools / Extensions and Updates… then uninstall “Direct3DWin32Game”. You then restart VS 2013.

Creating a new project

To create a new project, use File / New -> Project…

When finished, you have a Win32 desktop app project that is ready to use for learning Direct3D 11 on Windows 7 or Windows 8.x. For those familiar with the existing “DirectX App” VS templates or XNA Game Studio, it has a similar structure with a Game class with methods like Render, Update, and Clear. Search for TODO for hints as to where to add your code.

Template overview

The project has the following properties:

  • It creates a window, Direct3D 11 device, and swap chain with depth buffer. This supports both DirectX 11.0 and DirectX 11.1 runtime systems. Debug configurations enable the Direct3D debug device with some additional debugging features enabled.
  • By default it supports all possible Direct3D feature levels from 9.1 to 11.1.
  • The default swapchain format is BGRA 8-bit UNORM with a D24S8 depth buffer.
  • The default is for Game::Clear to render a classic “Cornflower blue” screen.
  • This project makes use of StepTimer calling the Game::Update method as needed to update the game state, and defaults to variable-time steps.
  • The application handles resizing–the smallest window allowed is 320 x 200, defaulting to 800 x 600 or whatever is returned by Game::GetDefaultSize. When the window is resized, Game::OnWindowSizeChanged is called which in turn calls Game::CreateResources in order update the swap chain, re-create any window-sized dependent resources like the depth buffer, and reset the default viewport.

The project template makes some simplifying assumptions:

  • If the window is minimized, Game::OnSuspending is called (same as if a power management state is encountered).
  • No support for either ‘exclusive’ full-screen or ‘fake’ full-screen.
  • It does not have any handling of input (keyboard/mouse), which you can add by modifying the WndProc in Main.cpp. You can easily add support for the Xbox Common Controller gamepad using DirectX Tool Kit‘s GamePad class.

Some additional notes:

  • This makes use of Microsoft::WRL::ComPtr as a smart-pointer to manage the lifetime of the COM objects.
  • It makes use of C++ Exception handling for errors, including the DX::ThrowIfFailed helper present in the other DirectX templates.
  • The modules default to using the DirectX namespace to simplify use of DirectXMath or other helper libraries like DirectX Tool Kit. Following good C++ coding practice, you should use fully qualified names in the headers (i.e. in Game.h).
  • If Game::Present detects as a device-removed or device-reset case, it will call Game::OnDeviceLost which releases all Direct3D objects and then calls Game::CreateDevice and Game::CreateResources again to re-create them.
  • COM is initialized using a multi-threading model to simplify use of Windows Imaging Component (WIC) or XAudio2.
  • The project sets _WIN32_WINNT to 0x0600 in pch.h to support Windows Vista, Windows 7, or Windows 8.x. Set this to 0x0601 to require Windows 7 or later (i.e. you don’t want to deal with Windows Vista Direct3D 11 deployment), or 0x0602 to require Windows 8.0 or later (so you can rely on XAudio 2.8 or XInput 1.4).
  • The project includes a complete embedded manifest.
  • The project supports both Win32 (32-bit) and x64 native configurations (Debug and Release).

Adding DirectX Tool Kit

The basic project template is self-contained. If you want to make use of DirectX Tool Kit with this template, there are two ways to add it:

Use NuGet

Go to Project / Manage NuGet Packages…

Search for “DirectX Tool Kit” online and select the package with Id: directxtk_desktop_2013 (use the latest one which is 2014.11.24.2 at this time; if you have an older version you can update it using the NuGet interface)

Use Project-to-project references

Follow the directions given on the CodePlex site under Adding to a VS solution with the DirectXTK_Desktop_2013.vcxproj project, and adding the appropriate Additional Include Directories property for all platforms & configurations.

Note: This applies to adding use of DirectXTex, DirectXMesh, Effects 11, and/or UVAtlas to the project as well.

Adding DirectX Tool Kit headers

Edit the pch.h file in the project and add the following lines at the end:

 #include "CommonStates.h"
 #include "DDSTextureLoader.h"
 #include "DirectXHelpers.h"
 #include "Effects.h"
 #include "GamePad.h"
 #include "GeometricPrimitive.h"
 #include "Model.h"
 #include "PrimitiveBatch.h"
 #include "ScreenGrab.h"
 #include "SimpleMath.h"
 #include "SpriteBatch.h"
 #include "SpriteFont.h"
 #include "VertexTypes.h"
 #include "WICTextureLoader.h"

Then add the following line near the top of Game.cpp after the existing using namespace statement to make it easier to use SimpleMath in your code.

using namespace DirectX::SimpleMath;

Windows Store 8.1 / Windows phone 8.1 / Universal apps

You can get a similar “empty” starting project creating a new DirectX App project, removing/deleting all files under the Content folder and then replacing them with these two files:

Game.h

 // Game.h

#pragma once

#include “..\Common\DeviceResources.h”
#include “..\Common\StepTimer.h”

namespace DXTKApp1 // TODO: Change to match project namespace
{
class Game
{
public:
Game(const std::shared_ptr<DX::DeviceResources>& deviceResources);
void Update(DX::StepTimer const& timer);
void Render();
void CreateDeviceDependentResources();
void CreateWindowSizeDependentResources();
void ReleaseDeviceDependentResources();

private:
// Cached pointer to device resources.
std::shared_ptr<DX::DeviceResources> m_deviceResources;

// Direct3D Objects (cached)
D3D_FEATURE_LEVEL m_featureLevel;
Microsoft::WRL::ComPtr<ID3D11Device2> m_d3dDevice;
Microsoft::WRL::ComPtr<ID3D11DeviceContext2> m_d3dContext;
};
}

Game.cpp

 // Game.cpp
#include "pch.h"
#include "Game.h"

#include "..\Common\DirectXHelper.h"

using namespace DXTKApp1; // TODO: Change to match project namespace

using namespace DirectX;
using namespace Windows::Foundation;

Game::Game(const std::shared_ptr<DX::DeviceResources>& deviceResources) :
m_deviceResources(deviceResources)
{
CreateDeviceDependentResources();
CreateWindowSizeDependentResources();
}

void Game::Update(DX::StepTimer const& timer)
{
float elapsedTime = float(timer.GetElapsedSeconds());

// TODO: Add your game logic here
elapsedTime;
}

void Game::Render()
{
// TODO: Add your rendering code here
}

void Game::CreateDeviceDependentResources()
{
m_featureLevel = m_deviceResources->GetDeviceFeatureLevel();
m_d3dDevice = m_deviceResources->GetD3DDevice();
m_d3dContext = m_deviceResources->GetD3DDeviceContext();

// TODO: Initialize device dependent objects here (independent of window size)
}

void Game::CreateWindowSizeDependentResources()
{
// TODO: Initialize windows-size dependent objects here
}

void Game::ReleaseDeviceDependentResources()
{
m_d3dDevice.Reset();
m_d3dContext.Reset();

// TODO: Add Direct3D resource cleanup here
}

After that, update the *Main.cpp/.h files to use the new Game class rather than Sample3DSceneRenderer, and remove SampleFpsTextRenderer usage. Remember to update the DXTKApp1 namespace in both Game.cpp/.h files to match that in the rest of the project.

You can use NuGet (Id: directxtk_windowsstore_8_1 or directxtk_windowsphone_8_1) or project-to-project references (DirectXTK_Windows81.vcxproj or DirectXTK_WindowsPhone81.vcxproj) to add DirectX Tool Kit.

DirectX Tool Kit: This template is used extensively in the DirectX Tool Kit tutorial series.

GitHub: The files for the template are also hosted on GitHub.

Download: Direct3DWin32Game.vsix (VS 2013), Direct3DUWPGame (VS 2015 for both Win32 and UWP)

Comments (13)

  1. jschroedl says:

    Excellent! I will definitely be trying this out. Thanks for sharing – about time the Desktop saw more love.

  2. sdflysha says:

    Maybe you can add the 'DeviceResource' class like windows store apps and add support for Visual Studio 2015 (preview), thank you!

  3. DeviceResource is a complicated beast, and it assumes that you have the DirectX 11.1 runtime (i.e. won't work on WIndows Vista, Windows 7 RTM, or Windows 7 SP1 without KB2670838) so you can make use of Direct2D/DirectWrite as well as Direct3D 11. It also handles issues like orientation which is not needed for Win32 desktop apps. Which part do you find yourself missing?

    BTW the Direct3DWin32Game template structure is identical to the Xbox One XDK/ADK templates which also do not use DeviceResources, and Xbox One XDK doesn't support Direct2D/DirectWrite.

    I'll be adding VS 2015 support soon, likely whenever they hit their next public preview release.

  4. Craig says:

    Can this be extended to support templates in Visual Basic for those few of us who are C impaired?

  5. @Craig – In order to use DirectX from any .NET language (VB, C#, etc.) you need assemblies that expose the DirectX API. As such, this is really a question for the maintainers of SharpDX, SlimDX, etc. My main purpose in creating this template is to have a Win32 desktop equivalent to the other DirectX VS template for C++ developers in order to write tutorials for DirectX Tool Kit, which is a C++ library. I totally see the value in having a VB DirectX template, but that's going to have to be integrating something like SharpDX to actually work.

  6. Craig says:

    @Chuck – Thanks. I appreciate the sobering response.  Makes me fond for the VS2005-ish days when it was very easy in VB.NET to work with DirectX.  Hopefully they will get this all back on track for Windows desktop in VS2015?

  7. Even back in VS 2002 .NET, you still needed managed assemblies to use DirectX from VB. I hear great things about SharpDX as a wrapper, so check it out.

  8. Ethan says:

    I like this. It's very useful to me. However, I'm a bit confused as to

    1. why no support for fullscreen?

    2. How do I add support for fullscreen?

    Thanks!

  9. Doing fullscreen correctly is actually quite challenging, and really complicates the template. I have a task on my backlog to do a tutorial lesson on making it work fullscreen, but generally for development and education purposes it's better if it's windowed.

  10. Ethan says:

    Ah, I see. I actually figured out how to make it fullscreen, with just  a couple lines of code. Thanks for the template!

  11. Getting it to go fullscreen is easy enough. Doing it robustly without getting any performance issues is the complicated part 🙂 Also, the template really has to support both DirectX 11.0 and DirectX 11.1+ methods for doing fullscreen, and potentially cope with multi-monitor as well.

  12. Ethan says:

    Fair point. But the current fullscreen will be enough for me for now.

  13. Jens says:

    I second the request for the a fullscreen template. I've gone through this one: msdn.microsoft.com/…/ee417025(v=vs.85).aspx, but without code samples it is daunting to get it prefect.

Skip to main content