This project is now hosted on GitHub
. This site is being maintained for now, but please move to using GitHub
particularly as the CodePlex copy of the tutorials are a little dated.
The first lesson in the
guide is to create a basic game loop.
Our starting point is to use the Direct3D Win32 Game
project template. Install
on your development system, and then start (or restart) Visual Studio 2013.
Creating a new project
- From the drop-down menu, select File and then New -> Project...
- Select "Visual C++" on the left-hand tree-view.
- Select "Direct3D Win32 Game".
- Fill in the "Name" and "Location" fields as desired.
- Optional: Uncheck "Create directory for solution" to keep the directory structure as bit flatter.
- Select "OK".
The newly created project contains the following files:
- Precompiled header files
- Main application entry-point and classic Windows procedure function
- Timer helper class
- The Game class
Running the application
Visual Studio will default to the Win32
platform / Debug
configuration which builds an x86 (32-bit) application with debugging enabled. The template contains both
configurations for both Win32
(x64 native 64-bit) platforms.
Press F5 to build and run the application It displays the following window:
If the base template fails to start, there are a few possibilities. First, if your system doesn't have any Direct3D capable device of any feature level, it will fail. This is pretty unlikely on modern versions of Windows. Second
if it runs fine in Release
but fails in Debug
, then you likely do not have the proper DirectX Debug Device installed for your operating system. For more see
Tour of the code
For now, we'll focus on the content of Game.cpp (which is open by default).
When the application first starts, execution is passed to the Initialize
method. The TODO here by default leaves the applications StepTimer in the 'variable length' mode. You uncomment the code if you want StepTimer in the 'fixed-step'
mode. We'll explain this more once we get to Update.
// Initialize the Direct3D resources required to run.
void Game::Initialize(HWND window)
m_window = window;
// TODO: Change the timer settings if you want something other than the default
// variable timestep mode.
// e.g. for 60 FPS fixed timestep update logic, call:
m_timer.SetTargetElapsedSeconds(1.0 / 60);
One of the two functions called by Initialize is the CreateDevice
function which sets up a Direct3D 11.0 (and optionally Direct3D 11.1) device using the maximum Direct3D Feature Level supported by the system which could range from 9.1 to 11.1. For Debug
builds, it enables the Direct3D "Debug device" which provides additional validation and diagnostic errors (seen in the "Output" window in Visual C++ when showing output from "Debug"). The TODO here is for adding the creation of
objects that depend on the m_d3dDevice
, but do not care about the size of the rendering window.
// These are the resources that depend on the device.
// TODO: Initialize device dependent objects here (independent of window size)
The other function called by Initialize is the CreateResources
function which sets up the swapchain (which defaults to a B8G8R8A8_UNORM format), depth buffer (which defaults to a 16-bit D16_FLOAT format for Feature Level 9.1 devices, and a 32-bit D32_FLOAT
format otherwise), and rendering viewport. The TODO here is for adding the creation of objects that depend on the size of the rendering window. Note that this function could be creating these objects for the first time, it could be re-creating already existing
objects due to a window-size change, or could be creating 'fresh' objects after a Direct3D device-removed or device-reset case.
// Allocate all memory resources that change on a window SizeChanged event.
// TODO: Initialize windows-size dependent objects here
method is intended to handle game-world state modification which is typically driven by time passing, simulation, and/or user-input. By default, Update is called once per 'frame' and can have an arbitrary delta-time. This is called
a 'variable-step' mode.
If in the Initialize method above you uncomment the TODO code, then each Update will be for a fixed time-step (1/60th of a second), with Update called as many time in a single 'frame' as needed to keep it up-to-date. This is called a 'fixed-step'
mode and potentially be more stable for many kinds of simulations.
// Updates the world
void Game::Update(DX::StepTimer const& timer)
float elapsedTime = float(timer.GetElapsedSeconds());
// TODO: Add your game logic here
function which should render a single 'frame' of the scene, which ends with a Present of the rendered frame.
// Draws the scene
// Don't try to render anything before the first Update.
if (m_timer.GetFrameCount() == 0)
// TODO: Add your rendering code here
function defaults to a background color of the classic "Cornflower blue".
// Helper method to clear the backbuffers
// Clear the views
D3D11_CLEAR_DEPTH, 1.0f, 0);
Since we are using
, most cleanup is automatic when the Game class is destroyed. If Present encounters a device-removed or device-reset (most commonly the driver crashed or was updated), then the application needs to release all Direct3D objects and recreate the device,
swapchain, and all Direct3D objects again. Therefore, the TODO in OnDeviceLost
should be updated to release your application's Direct3D objects.
// TODO: Add Direct3D resource cleanup here
We make use of the Microsoft::WRL::ComPtr smart-pointer for managing the lifetime of the Direct3D 11 COM objects, which is why we make use of ".Get()" in the code above. See
for more information.
Many Direct3D functions return an HRESULT
which is the standard for COM APIs. For robustness and easier debugging, it is important that you always check the result of every function that return an
. If you really can safely assume there is no error condition for a particular function, the function itself will return
instead of HRESULT
The Win32 game template makes use of the helper function ThrowIfFailed in the
C++ namespace. This is the same helper that is used by the Windows Store and Windows phone VS templates. This helper throws a C++ exception if the standard
macro returns true for a given HRESULT
DX::ThrowIfFailed(m_d3dDevice->CreateTexture2D(&depthStencilDesc, nullptr, &depthStencil));
Adding the DirectX Tool Kit