Create a DirectX game project from a template

  • Article

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

The DirectX game learning templates can help you learn DirectX 11 and learn how to create a Windows Store game. This topic describes the templates and how to use them.

Tip  Get the full code here: DirectX game learning templates.

 

Note  The templates and classes are primarily for instructional and learning purposes. If you are planning to ship a game, review them and then make updates that best support your game, rather than incorporating them directly. They are designed to help you get started in an interactive environment, but should not replace custom controls and audio processing that best fit your shipping game product.

 

Prerequisites

To create the project you need to:

Choosing a template

The DirectX game learning templates come in two flavors: the DirectX game template, which renders directly to an app window, and the DirectX game (XAML) template, which renders inside a XAML control. Which template you choose depends on the performance and what technologies you want to use.

XAML and CoreWindow

The DirectX game learning templates .VSIX file installs both a XAML and non-XAML version. Both versions share many of the same features. The main difference is that the DirectX game (XAML) template uses a SwapChainPanel so you can use XAML UI controls. This can make adding user interface elements easier, but using the XAML template may result in lower performance.

Template structure

The DirectX game learning template has a set of support classes for display, sound, and input.

Class Description
DeviceResources Controls the DirectX device for the sample.
InputManager Processes touch, mouse, keyboard, and XInput into a common set of game input values.
SoundPlayer Plays sounds from a file.
OverlayManager Displays a set of Direct2D overlays that are drawn over the Direct3D content. Implement the abstract base class Overlay to add overlays to the manager.

 

The learning template also has Direct2D overlay classes that display debug information (input and framerate) and provide a virtual analog controller for touch input.

Class Description
SampleDebugTextRenderer Displays the frame rate and info about processed game input.
SampleVirtualControllerRenderer Displays a virtual analog controller that player 1 operates by touch.

 

Finally, the learning template has the Sample3DSceneRenderer class, which displays a spinning cube using Direct3D. You replace this class with rendering code for your game.

Helper classes

DeviceResources class

The DeviceResources class controls the DirectX devices for the project. It creates the Direct3D and Direct2D devices and the DXGI swap chain for displaying the content to the screen. If hardware overlay support exists, an additional foreground layer swap chain is created by the DeviceResources class and automatically used as the Direct2D drawing surface.

An instance of the DeviceResources class is declared by the main app class as a std::shared_ptr and is available for use by each of the classes in the app. Access DeviceResources whenever you need to create or use resources on the Direct3D device. This is demonstrated in the cube renderer for Direct3D, and in the overlays for Direct2D.

Note  If the device does not support hardware overlays, rendering with multiple swap chains will not be efficient. Instead, the DeviceResources class renders the UI on the same swap chain as real-time game content. Additionally, XAML does not support hardware overlays. DeviceResources recognizes these circumstances and falls back to a single swap chain.

 

For more information about hardware scaling and overlays, see the Swap chain scaling and overlays topic.

InputManager class

The InputManager class handles XInput, touch, mouse, and keyboard input. It resolves input from all of these sources into meaningful input for a game. It supports up to 4 XBox controllers via USB and provides the input for the on-screen virtual analog stick and buttons.

For each input event received since the previous frame, the input manager returns PlayerInputData structures with the following info:

  • The ID of the player.
  • The action initiated by the player as a PLAYER_ACTION_TYPES enumeration. The values in this enumeration can be redefined or added to.
  • The coordinate data for touch, mouse, and controller events.
  • The normalized input value. This is either 0 or 1 for digital events, or between 0 and 1 for analog events – for example, a gas pedal control.
  • A flag indicating if the action is a touch event.

The SampleVirtualControllerRenderer displays the touch screen controls and is an example of how to consume data from the InputManager. See the SampleVirtualControllerRenderer section for more info.

SoundPlayer class

The SoundPlayer class is a basic XAudio2 audio player. It allows you to play a single sound file and a single music file at any given time. The music is played as a background voice, so it will mute if the user plays their own music. The SoundPlayer has the following methods for playing sounds.

  • PlaySound
  • PlayMusic

Each method takes a file name to play. If a sound is already playing, it will stop and play the new sound. Use this to start adding sound events to your game, or to learn more about XAudio2 for use with your own game audio implementation.

OverlayManager class

The OverlayManager class holds a std::vector of Overlay class objects. It forwards update, render, and resource method calls to each of these objects. The SetOverlays method allows you to set the vector of overlays to render. The overlays are rendered over the top of each other in the order they are stored in the vector.

Overlay class

The Overlay class is an abstract class for Direct2D overlays. It has the following methods.

  • CreateDeviceDependentResources()
  • ReleaseDeviceDependentResources()
  • Update(DX::StepTimer const& timer)
  • Render()

The OverlayManager class calls these methods on each overlay class in the vector. You must implement a class derived from the Overlay class and implement these methods o add your own overlay to the overlay manager. You may want to overload a method, such as the Update method. For an example of this, see the SampleVirtualControllerRenderer class, which has an additional Update method that takes a PlayerInput parameter.

Overlay classes

The DirectX game learning template includes 2 overlay classes, the SampleDebugTextRenderer class and the SampleVirtualControllerRenderer class.

Both of these classes take input data from the InputManager class. Both demonstrate how to consume Direct2D from DeviceResources, and both include features that can aid game development.

SampleDebugTextRenderer class

The SampleDebugTextRenderer class displays the frame rate and the resolved input data for each frame. The Update(std::vector<PlayerInputData>* playerInputs, unsigned int playersAttached) overload method loops through all input data from the InputManager and displays the input values for each active PLAYER_ACTION_TYPE. This information is not meant to be displayed in a production game, but looking at this data in real-time can be helpful when tracking down rendering bottlenecks or incorrect player input.

SampleVirtualControllerRenderer class

The SampleVirtualControllerRenderer class displays a virtual analog stick and buttons on the screen for touch input. The InputManager class handles the actual touch input, including validation of touch regions and CoreWindow events; the SampleVirtualControllerRenderer class renders the stick and buttons according to touch region definitions and the per-frame input data it receives.

The code here, from the Update method, stores the PlayerAction data to be used to render the virtual controller in the Render method.

    for (unsigned int i = 0; i < playerInput->size(); i++)
    {
        PlayerInputData playerAction = (*playerInput)[i];

        if (!playerAction.IsTouchAction)
            continue;

        if (m_touchControls.count(playerAction.PlayerAction))
        {
            switch (m_touchControls[playerAction.PlayerAction].Region.RegionType)
            {
            case TOUCH_CONTROL_REGION_TYPES::TOUCH_CONTROL_REGION_ANALOG_STICK:
                m_touchControls[playerAction.PlayerAction].PointerThrowX = playerAction.PointerThrowX;
                m_touchControls[playerAction.PlayerAction].PointerThrowY = playerAction.PointerThrowY;
                m_touchControls[playerAction.PlayerAction].PointerRawX = playerAction.PointerRawX;
                m_touchControls[playerAction.PlayerAction].PointerRawY = playerAction.PointerRawY;
                break;

            case TOUCH_CONTROL_REGION_TYPES::TOUCH_CONTROL_REGION_BUTTON:
                m_touchControls[playerAction.PlayerAction].ButtonPressed = true;

            default:
                break;
            }
        }
    }

This code here saves the touch pointer position only if the PlayerAction is a touch action.

Sample3DSceneRenderer class

The Sample3DSceneRenderer class renders a spinning 3D cube. Study how this class consumes DeviceResources, study the Direct3D 11 pixel pipeline, then replace this class with your own Direct3D content.

Next steps

Now that you have a starting point, add to it to build your game development knowledge and Windows Store game development skills.

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

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