Games for Windows and the DirectX SDK blog

Technical tips, tricks, and news about game development for Microsoft platforms including desktop, Xbox, and UWP

Project maintained by walbourn Hosted on GitHub Pages — Theme by mattgraham
Home | Posts by Tag | Posts by Month

Direct3D Win32 Game Visual Studio template

direct3d, uwp, visualc

Originally posted to Chuck Walbourn's Blog on MSDN,

For people new to DirectX development, Microsoft Docs 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 GitHub 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
#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
#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)