Sign in
Home Dashboard Docs Samples Downloads Support Community
Dev Center - Windows Store apps > Docs > End-to-end apps > Developing games > Prepare your Windows Store DirectX game programming environment > Create a DirectX game project from a template

Create a DirectX game project from a template

1 out of 2 rated this helpful - Rate this topic
Summary

In this article

[This documentation is preliminary and is subject to change.]

There are three GDC 2013 game templates for creating a Windows Store DirectX game available for download. This topic describes the differences between the templates to you help decide which template is best for you.

Note  Get the full example code: download the GDC 2013 game templates.

Prerequisites

To create DirectX game project you need to:

Choosing a template

The three GDC 2013 game templates are: DirectX with a CoreWindow template, DirectX with a XAML overlay template, and DirectX and XAML with a view controller template. Which template you choose depends on performance and what technologies you want to use. Let's go over the differences among the templates.

Menu UI and in-game overlay

The GDC 2013 game templates use different technologies for the menu UI and the in-game overlay (such as scores, health bars, radars, text, 2D graphics): XAML, Direct2D, or both. They also differ in how they handle the app bar. All of the templates can pause the game or perform other actions when the user accesses the charms.

Each template has a tradeoff between complexity and performance. Here is a table that summarizes the differences.

TemplateMenu UIIn-game overlayOverview and comparison
DirectX with a CoreWindowDirect2DDirect2D

The DirectX with a CoreWindow template uses Direct2D for both the menu UI and the in-game overlay. You must draw and handle the input to any in-game overlays, menu controls, and the app bar.

Direct2D performs slightly better than a XAML overlay in many cases.

DirectX with a XAML overlayXAMLXAML

The DirectX with a XAML overlay template uses XAML for both the menu UI and the in-game overlay. The swap chain composes the XAML in-game overlay onto the Direct3D content.

When you display a menu, you can use a different XAML page than the in-game XAML page.

XAML provides ready made controls, such as app bars, that Direct2D does not.

Using XAML means less UI and overlay work at a small cost of performance.

DirectX and XAML with view controllerXAMLDirect2D

The DirectX and XAML with a view controller template is a combination of the other two templates. It uses XAML for the menu UI and it uses Direct2D for the in-game overlay.

This template has a XAML view with a SwapChainBackground panel control and a CoreWindow view with no XAML. A view controller helps synchronize rendering to the current view.

This adds a bit more complexity than either of the previous two templates, but allows you to use XAML only when you need it.

 

Template code and project structures

All three of the GDC 2013 game templates use Direct3D. They all use the same RenderObject class to display Direct3D content and a Direct2D overlay. (Direct2D is disabled by default in the DirectX with a XAML overlay template.) The code here is the declaration of the class from RenderObject.h.

C++
Copy 

// To enable D2D:
// 1. Add the included files D2DOverlay.* to your project
// 2. Link to these libraries: d2d1.lib; dwrite.lib; dxguid.lib; 
// 3. Uncomment the following line.
// #define TEMPLATE_USING_D2D

#include "Common_DirectX\FpsCounter.h"
#include "ShaderStructures.h"

#ifdef TEMPLATE_USING_D2D
#include "D2DOverlay.h"
#endif

// This class renders a simple spinning cube. It can switch between a CoreWindow
// swap chain, which it creates by default, and a SwapChainBackGroundPanel for
// XAML interop.
class RenderObject sealed
{
public:
	RenderObject();

	// Methods for initialization and re-initialization.
	void Initialize( _In_ Windows::UI::Core::CoreWindow^ window );
	void Initialize(
		_In_ Windows::UI::Core::CoreWindow^ window,
		_In_ Windows::UI::Xaml::Controls::SwapChainBackgroundPanel^ panel
		);
	void CreateDeviceResources();
	void CreateDeviceIndependentResources();
	void CreateWindowSizeDependentResources();
	void UpdateForWindowSizeChange();
	void SetProjectDir(Platform::String^ str);
	
	// Methods to switch between using XAML (or not).
	void SetPanel(
		_In_ Windows::UI::Xaml::Controls::SwapChainBackgroundPanel^ panel
		);
	void SwitchToCoreWindow();
	void SwitchToSCBP();

	// Render loop methods.
	void Update(
		_In_ uint64 tickDelta,
		_In_ float timeDelta,
		_In_ float leftover,
		_In_ float lastFrameTime = 0.f
		);
	void Render();
	void Present();

#ifdef TEMPLATE_USING_D2D
	// Method to render a D2D overlay.
	void RenderHud(bool paused);
#endif

private:
	void HandleDeviceLost();
	void DiscardViews();
	void SetDpi( _In_ float dpi );
	float ConvertDipsToPixels( _In_ float dips );

	// The CoreWindow and the SwapChainBackgroundPanel don't have to be from the 
	// same view.
	Platform::Agile<Windows::UI::Core::CoreWindow>			m_window;
	Windows::UI::Xaml::Controls::SwapChainBackgroundPanel^	m_panel;

	// DirectX core objects.
	Microsoft::WRL::ComPtr<ID3D11Device1>			m_d3dDevice;
	Microsoft::WRL::ComPtr<ID3D11DeviceContext1>	m_d3dContext;
	Microsoft::WRL::ComPtr<IDXGISwapChain1>			m_swapChainComposition;
	Microsoft::WRL::ComPtr<IDXGISwapChain1>			m_swapChainCoreWindow;
	Microsoft::WRL::ComPtr<ID3D11RenderTargetView>	m_d3dRenderTargetViewComp;
	Microsoft::WRL::ComPtr<ID3D11RenderTargetView>	m_d3dRenderTargetViewWin;

	// Direct3D rendering objects. Required for 3D.
	Microsoft::WRL::ComPtr<ID3D11DepthStencilView>	m_d3dDepthStencilView;

	// Cached properties of the hardware and window state.
	D3D_FEATURE_LEVEL								m_featureLevel;
	Windows::Foundation::Size						m_d3dRenderTargetSize;
	Windows::Foundation::Rect						m_windowBounds;
	Windows::Graphics::Display::DisplayOrientations	m_displayOrientation;
	float											m_dpi;
	
	// Direct3D resources for cube geometry.
	Microsoft::WRL::ComPtr<ID3D11InputLayout>		m_inputLayout;
	Microsoft::WRL::ComPtr<ID3D11Buffer>			m_vertexBuffer;
	Microsoft::WRL::ComPtr<ID3D11Buffer>			m_indexBuffer;
	Microsoft::WRL::ComPtr<ID3D11VertexShader>		m_vertexShader;
	Microsoft::WRL::ComPtr<ID3D11PixelShader>		m_pixelShader;
	Microsoft::WRL::ComPtr<ID3D11Buffer>			m_constantBuffer;
	
	// System resources for cube geometry.
	ModelViewProjectionConstantBuffer	m_constantBufferData;
	uint32								m_indexCount;

	// Transform used for display orientation.
	DirectX::XMFLOAT4X4	m_displayOrientationTransform3D;

#ifdef TEMPLATE_USING_D2D
	// Direct2D rendering objects. Required for 2D.
	Microsoft::WRL::ComPtr<ID2D1Factory1>			m_d2dFactory;
	Microsoft::WRL::ComPtr<ID2D1Device>				m_d2dDevice;
	Microsoft::WRL::ComPtr<ID2D1DeviceContext>		m_d2dContext;
	Microsoft::WRL::ComPtr<ID2D1Bitmap1>			m_d2dTargetBitmapComposition;
	Microsoft::WRL::ComPtr<ID2D1Bitmap1>			m_d2dTargetBitmapCoreWindow;

	// DirectWrite and Windows Imaging Component objects.
	Microsoft::WRL::ComPtr<IDWriteFactory1>			m_dwriteFactory;
	Microsoft::WRL::ComPtr<IWICImagingFactory2>		m_wicFactory;

	// Direct2D transform for display orientation.
	D2D1::Matrix3x2F	m_displayOrientationTransform2D;

	// Helper objects for D2D overlay.
	Hud			m_hud;
	PauseScreen	m_pause;
#endif

	// Helper object measures FPS and per-frame render time
	FpsCounter	m_fpsCounter;

	// Internal variables used with the rendering loop.
	bool	m_usePanel;
	bool	m_loadingComplete;
	bool	m_newPanel;	// Signals recreation of swap chain resources for SCBP.
	uint32	m_degreesPerSecond;
	uint64	m_ticks;

	// Name of the subfolder for DirectX project (if needed).
	Platform::String^ m_projectDir;
};

__forceinline void RenderObject::SetProjectDir(Platform::String^ dir)
{
	m_projectDir = dir;
}

The RenderObject class sets up Direct3D, Direct2D (optional), DXGI, and renders a spinning cube object. This class handles the render loop and displays the content. This is the class that you replace or customize to create graphics for your game.

Each GDC 2013 game templates has a different structure for the views and windows that displays the content.

DirectX with a CoreWindow

The DirectX with a CoreWindow template has a single view and CoreWindow. The DirectX content is rendered on to the window by using a DXGI swap chain for CoreWindow. The code here shows the code for the main game class, which implements the methods of IFrameworkView only.

C++
Copy 

[Windows::Foundation::Metadata::WebHostHiddenAttribute]
ref class SimpleDirect3DApp sealed : public Windows::ApplicationModel::Core::IFrameworkView
{
public:
	SimpleDirect3DApp();
	
	// IFrameworkView methods.
	virtual void Initialize(Windows::ApplicationModel::Core::CoreApplicationView^ applicationView);
	virtual void SetWindow(Windows::UI::Core::CoreWindow^ window);
	virtual void Load(Platform::String^ entryPoint);
	virtual void Run();
	virtual void Uninitialize();

private:
	RenderObject	m_renderer;	// The rendering class.
	StepTimer		m_timer;	// Rendering loop timer.

	bool	m_windowClosed;
	bool	m_paused;
	bool	m_visible;
	float	m_lastFrameTime;
};

[Windows::Foundation::Metadata::WebHostHiddenAttribute]
ref class Direct3DApplicationSource sealed : Windows::ApplicationModel::Core::IFrameworkViewSource
{
public:
	virtual Windows::ApplicationModel::Core::IFrameworkView^ CreateView();
};

For more information on rendering to a CoreWindow view, see How to set up your DirectX Windows Store app to display a view.

DirectX with a XAML overlay

There are two important parts of the overlay template: the XAML declaration of the SwapChainBackgroundPanel and the composition swap chain that draws to the panel.

The code here from Direct3DPage.xaml declares the background panel and the XAML controls that render over the Direct3D background.

C++
Copy 

    <SwapChainBackgroundPanel x:Name="m_swapChainPanel">
        <Grid.RowDefinitions>
            <RowDefinition Height="75*" />
            <RowDefinition Height="560*" />
            <RowDefinition Height="50*" />
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="90*" />
            <ColumnDefinition Width="660*" />
            <ColumnDefinition Width="90*" />
        </Grid.ColumnDefinitions>

        <TextBlock Name="Title" Text="Direct3D and XAML" Foreground="YellowGreen"  
                   Margin="10,10,10,10" FontSize="75" Grid.Row="0" Grid.Column="1" 
                   TextWrapping="NoWrap" VerticalAlignment="Top" TextAlignment="Center" />
        <TextBlock Name="FrameTime" Text=" - " Foreground="YellowGreen" 
                   Margin="10,10,10,10" FontSize="36"  Grid.Row="2" Grid.Column="0" 
                   TextWrapping="NoWrap" VerticalAlignment="Bottom" TextAlignment="Left"/>
        <TextBlock Name="FPS" Text=" - " Foreground="YellowGreen" Margin="10,10,10,10" 
                   FontSize="36"  Grid.Row="2" Grid.Column="2" TextWrapping="NoWrap" 
                   VerticalAlignment="Bottom" TextAlignment="Right"/>
        <Image Source="Assets/sdklogo.png" Margin="10,10,10,10" Grid.Row="0" 
               Grid.Column="0" Name="Logo" HorizontalAlignment="Left" 
               VerticalAlignment="Top" Width="90" Height="90" />
    </SwapChainBackgroundPanel>

The x:Name="m_swapChainPanel" attribute designates the variable name that can be referenced in the Direct3DPage C++ class. The Direct3DPage constructor passes the SwapChainBackgroundPanel to the RenderObject class.

The code here shows how to create a swap chain to be composited with XAML and connect it to the background panel.

C++
Copy 

  DXGI_SWAP_CHAIN_DESC1 swapChainDesc = {0};
		swapChainDesc.Width = static_cast<UINT>(m_d3dRenderTargetSize.Width); // Match the size of the window.
		swapChainDesc.Height = static_cast<UINT>(m_d3dRenderTargetSize.Height);
		swapChainDesc.Format = DXGI_FORMAT_B8G8R8A8_UNORM; // This is the most common swap chain format.
		swapChainDesc.Stereo = false;
		swapChainDesc.SampleDesc.Count = 1; // Don't use multi-sampling.
		swapChainDesc.SampleDesc.Quality = 0;
		swapChainDesc.BufferUsage = DXGI_USAGE_RENDER_TARGET_OUTPUT;
		swapChainDesc.BufferCount = 2; // Use double-buffering to minimize latency.
		swapChainDesc.SwapEffect = DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL; // All Windows Store apps must use this SwapEffect.
		swapChainDesc.Flags = 0;
		
		if (m_panel)
		{
			// The following two values are important for Direct3D to interoperate with XAML.
			swapChainDesc.Scaling = DXGI_SCALING_STRETCH;
			swapChainDesc.AlphaMode = DXGI_ALPHA_MODE_IGNORE;

			DX::ThrowIfFailed(
				dxgiFactory->CreateSwapChainForComposition(
					m_d3dDevice.Get(),
					&swapChainDesc,
					nullptr, // Allow on all displays.
					&m_swapChainComposition
					)
				);

			// Associate the new swap chain with the SwapChainBackgroundPanel element.
			ComPtr<ISwapChainBackgroundPanelNative> panelNative;
			DX::ThrowIfFailed(
				reinterpret_cast<IUnknown*>(m_panel)->QueryInterface(IID_PPV_ARGS(&panelNative))
				);
		
			DX::ThrowIfFailed(
				panelNative->SetSwapChain(m_swapChainComposition.Get())
				);

Now you have a swap chain that works the same as in any other Direct3D app.

DirectX and XAML with a view controller

The DirectX and XAML with a view controller template is a combination of the other two templates. The menu screen is DirectX with a XAML overlay and the game screen is DirectX with a CoreWindow. Both share the same renderer, but the RenderObject class creates two render targets, one for each view. You switch between the views using the ViewStateChangeNotifier class included in the template.

The template solution has two projects: XAML_MENU and DirectXScreen. The former is the main class for the app, and the latter is a DLL with the "main" class for the game. The DirectXScreen project is similar to the DirectX with a CoreWindow template with some important differences that add complexity:

  • The class derived from IFrameworkView (DirectXView) and its constructor are public.
  • The DirectXView class is explicitly declared in the root namespace.
  • The project settings output a WinRT DLL and WinMD file.
  • The DirectXScreen project is set as a reference in the main project.

View the project settings for the DirectX and XAML with a view controller template

The settings for the projects in the DirectX and XAML with a view controller template are different than a single project app. Here's the how to view the settings for this template.

  1. The root namespace must the same as the namespace that contains the DirectXView class. You view the root namespace by clicking on the project in the Solution Explorer and changing the value in the Properties pane.

    Dn166882.DirectXScreenProperties(en-us,WIN.10).png

    This allows the Direct3DPage class to create a new view. Here is the code from the Direct3DPage class that creates a new view.

    C++
    Copy 
    
m_dxView = Windows::ApplicationModel::Core::CoreApplication::CreateNewView("DirectXScreen.DirectXView", "DirectXView");

  2. Select the Project->Properties menu option and note that Configuration Properties->General->Configuration Type is set to Dynamic Library (.dll).

    Dn166882.DirectXScreenConfigurationType(en-us,WIN.10).png

  3. The Configuration Properties->C/C++->Preprocessor->Preprocessor Definitions is set to _WINRT_DLL;%(PreprocessorDefinitions).

    Dn166882.DirectXScreenPreprocessor(en-us,WIN.10).png

  4. Select the Direct3D with XAML Menu project then select the Project->Properties menu option. Under Common Properties->Framework and References and note that the DirectXScreen project is set as a reference.

    Dn166882.DirectXScreenReferences(en-us,WIN.10).png

Managing views in the DirectX and XAML with a view controller template

The RenderObject class switches between each view and swap chain pair. To track the view state, the template has a class with view state change events.

Here is the code from the ViewStateChangeNotifier.h file.

C++
Copy 

namespace DirectXScreen
{

enum class ViewState {
	ViewStateSCBP,
	ViewStateCoreWindow,
};

// Stores arguments for view state change events.
ref class ViewStateChangeEventArgs sealed
{
internal:
	ViewStateChangeEventArgs( _In_ ViewState state ) : m_viewState(state) {	};

	property ViewState viewState {
		ViewState	get()						{ return m_viewState;  };
		void		set( _In_ ViewState state)	{ m_viewState = state; };
	}

private:
	ViewStateChangeEventArgs();
	ViewState m_viewState;
};

delegate void ViewStateChangeEventHandler (
	_In_ ViewStateChangeEventArgs^ args
	);

delegate void SCBPChangeEventHandler (
	_In_ Windows::UI::Xaml::Controls::SwapChainBackgroundPanel^ panel
	);

// Provides event-based communication for view state changes. These notifications allow
// DirectX rendering objects to switch to a new swap chain, and render a frame, before
// the target view is actually drawn.
ref class ViewStateChangeNotifier sealed
{
internal:
	ViewStateChangeNotifier() {};

	void FireViewStateChangeEvent( _In_ ViewStateChangeEventArgs^ args )
	{
		ViewStateChange(args);
	};
	
	void FireSCBPChangeEvent( _In_ Windows::UI::Xaml::Controls::SwapChainBackgroundPanel^ panel )
	{
		SCBPChange(panel);
	};

	event ViewStateChangeEventHandler^	ViewStateChange;
	event SCBPChangeEventHandler^		SCBPChange;
};

}

The RenderObject class registers event handlers for the ViewStateChange, SetSCBP, and SetAppBar events so you can switch to the correct view, render to the SwapChainBackgroundPanel while in the XAML view, and show the app bar in response to edge gestures.

Next steps

Now that you have a starting point, add to it to build your game.

If you are porting an existing game, see the following topics.

If you are creating a new DirectX game, see the following topics.

 

 

Build date: 3/22/2013

Did you find this helpful?
(1500 characters remaining)
© 2013 Microsoft. All rights reserved.