Game development with SharpDX Toolkit: Content loading and drawing a sprite

Now that we know the bare minimum on how to configure a SharpDX Toolkit project from scratch, it’s time to reveal more about what kind of game we are going to develop: a Flappy Bird clone. You can love or hate it, but you have to admit that it’s a good candidate to learn the basics of game development: 2D drawing, input, playing sounds and collision detection.

In this tutorial, we are going to focus on how to load our first texture and draw it with the SpriteBatch class. So go ahead and clone or download the source code of the previous article if you don’t have it, because we are going to extend it.

The ContentManager class

Much like XNA, SharpDX Toolkit has a ContentManager class for managing the assets (content files for textures, sounds, etc.) that a game has. It has a generic method, Load, which receives a string with the path of the asset file and returns an object of the specified type that represents the asset loaded into memory, throwing different kinds of exceptions if any error happens (asset not found, format not supported…).

The ContentManager also acts as a cache system, since it saves references to assets already loaded and returns them without having to re-read the data if they are requested. After all, if two game objects of the same type (for example, an enemy) are instantiated, they will end sharing the same texture when being drawn.

Like in XNA, the Game class already has a ContentManager property named Content, just for convenience. But one new feature is the addition of the Unload function, which allows us to unload individual asset files instead of having to dispose of all of them.

Loading a texture

It’s time to get our hands dirty with code. First, download the free Tappy Plane asset pack made by the awesome Kenney. Open the ZIP file and extract one of the PNG images of a plane of your liking.

Next, add a Content folder to the game project from the Solution Explorer window. Copy the plane texture inside it (we will be renaming it to “Plane.png”) and, in the Properties window that shows when selecting it, change its Build Action to ToolkitTexture. If this new option doesn’t show, close the solution and reopen it so the new build actions added by SharpDX Toolkit are reloaded.

Back to our Game class, we need to define a field of type Texture2D (careful! Use the one inside the SharpDX.Toolkit.Graphics namespace, and NOT the one inside SharpDX.Direct3D11) to hold the reference of our texture used for drawing. Now we can proceed to load it, but first we have to define the default directory of our existing ContentManager, so it knows where to look for assets when loading them. This can be done in the constructor, just by setting the property Content.RootDirectory.

public CrazyPlanesGame()
{
    deviceManager = new GraphicsDeviceManager(this);
    deviceManager.PreferredBackBufferWidth = 480;
    deviceManager.PreferredBackBufferHeight = 800;
    this.Content.RootDirectory = “Content”;
}


Now, our Game class has a specific function where we can put our content loading code. It’s got the descriptive name LoadContent, and you can override it and safely call any asset loading code from there since it’s executed just after the graphics device is initialized but before any actual drawing is performed. This way, any Direct3D internal objects needed for loading and sending the data to the GPU are already available.

So, let’s just call Content.Load passing the path to our plane texture relative to the Content directory. Also note that like in XNA you don’t need to specify the extension of the asset since all of them are compiled to an optimized format stored in a container file with the extension .tkb. The only downside to this approach is that you can’t have two assets with the same name (even if they have different extensions, like a PNG texture and an OBJ model) in the same directory.

protected override void LoadContent()
{
    this.planeTexture = this.Content.Load<Texture2D>(“Plane”);
    base.LoadContent();
}


Now you can try running your project to check that everything is fine. The Content.Load line will throw an AssetNotFoundException if it has any problems finding the asset file, and a NotSupportedException in case anything goes wrong when trying to load it.

Drawing with SpriteBatch

When drawing 2D elements to the screen we have a very helpful class that will take care of a lot of boilerplate (creating the vertex/index buffers, loading the shaders…) for us. It’s the SpriteBatch, and by instantiating a copy of it we can draw our textures to the screen just by specifying the position in pixels and the texture to draw. For future reference, the representation of a texture object (or a part of it) on screen is called a sprite, so the SpriteBatch class is named that way since it groups commands for drawing sprites into batches and then executes them for better performance.

So let’s go ahead and declare a field for holding our SpriteBatch. To initialize it we need for the graphics device to be available like when loading content, but to keep our code cleaner the Game class provides another function where we can create all our non-asset data: Initialize.

protected override void Initialize()
{
    this.spriteBatch = new SpriteBatch(this.GraphicsDevice);
    base.Initialize();
}


Now let’s get back to the Draw function that we added in the previous tutorial, and draw our sprite after clearing the screen. When you want to draw something with SpriteBatch, you must first call its Begin method so it enters into a valid state; after this, feel free to make any Draw or DrawString (for drawing text) calls you want. When finished, make sure you call End so the commands you entered are sent to the GPU and drawn on screen. Failing to follow this sequence will likely raise an InvalidOperationException.

We want to draw our plane perfectly centered, so we will need to access the GraphicsDevice.BackBuffer properties named Width and Height. These store the dimensions of our back buffer, in other words, the texture where everything is drawn to before the GPU presents it on screen. But since the default origin for positioning a sprite drawn with SpriteBatch is the top left corner, we have to take into account the size of the plane texture too:

Vector2 planePosition = new Vector2(
    (this.GraphicsDevice.BackBuffer.Width / 2.0f) – (this.planeTexture.Width / 2.0f),
    (this.GraphicsDevice.BackBuffer.Height / 2.0f) – (this.planeTexture.Height / 2.0f));


Having everything we need, let’s draw our sprite. The third parameter for SpriteBatch.Draw is a SharpDX.Color that will be applied as a tint to the sprite; in our case we want to see the texture as is, so we specify it to be white.

this.spriteBatch.Begin();
this.spriteBatch.Draw(this.planeTexture, planePosition, Color.White);
this.spriteBatch.End();


Now you can run the project and see that the plane sprite finally shows! However, there are weird pixels around its borders. This is due to SharpDX Toolkit using premultiplied alpha blending (transparency), much like XNA did, but the sprite doesn’t! Thankfully this can be easily changed by modifying the call to SpriteBatch.Begin and changing its BlendState parameter:

this.spriteBatch.Begin(SpriteSortMode.Deferred, this.GraphicsDevice.BlendStates.NonPremultiplied);

Plane texture with wrong alpha on the left, correct one on the right.

Now the sprite displays adequately! And with this ends this tutorial. Feel free to fiddle with the source code and try loading more textures, playing with the different overloads of the SpriteBatch.Draw function or even making the plane move in preparation for the next one.

Source code

You can find the source code for this tutorial and the following ones in this GitHub repository, inside the Chapter2 folder.

Game development with SharpDX Toolkit: Creating a base project

Since the announcement that Microsoft wasn’t going to update XNA anymore, lots of frameworks have tried to fill the void it left as a friendly way of being introduced to game development. Perhaps the most well known of them is MonoGame, which started as a way to expand XNA compatibility to non-Windows platforms by using managed OpenGL and the Xamarin products. Other alternatives based on C# are Unity, OpenTK and SharpDX, but they have totally different APIs or are just graphical libraries with a more low level approach.

But time passed and the people behind SharpDX launched their own solution: SharpDX Toolkit, a higher-level library that mimicked XNA. While the namespaces are named differently, almost all classes have matching names and even their structure is identical. With this, you can bring the power of DirectX 11 to desktop, Windows Store and Windows Phone games while maintaining the philosophy that XNA introduced.

Starting with this post, there will be a (hopefully regular!) series of tutorials on how to use SharpDX Toolkit for game development. They will be intertwined with the regular, more low level Direct2D and Direct3D posts using bare SharpDX.

Creating a new Windows desktop project

This time we are going to focus on game development for the desktop platform, and in future tutorials we will be porting the existing code to Windows Store and Windows Phone Universal Apps. So, open Visual Studio and go to select the New > Project… menu option. Inside the New Project window, select the template Templates > Visual C# > Windows Desktop > Empty Project. Give it a name and a location and click OK.

Create new project window

This will give us an empty project that by default is meant for console applications; this means that a console window will pop up when our app runs! You can change this by right clicking your project file from the Solution Explorer window and selecting Properties > Application > Output Type: Windows Application. However, you can keep it this way if you want to print debug messages via Console.Write.

Now, let’s add the references to the SharpDX Toolkit assemblies that we are going to need. Instead of downloading the package and manually adding it (which you can do if you want), we are going to take advantage of NuGet to download and reference the latest version of the libraries. So right click again your project file and select Manage NuGet Packages…. In this new window search for SharpDX.Toolkit and install only the SharpDX.Toolkit.Game package; every other library (including vanilla SharpDX) will be automatically added since it’s marked as a dependency.

Installing SharpDX Toolkig packages from NuGet window

Adding the game class

Let’s get started with the Game class. Add a new source file and define a class inside it (we will call it CrazyPlanesGame) that inherits from SharpDX.Toolkit.Game. Like in XNA, this class will be used to abstract the game loop and run the update and draw logic when it is needed.

Next, we need to perform a little initialization before the game class runs properly. Add a private member field of type GraphicsDeviceManager and instantiate it inside the constructor of CrazyPlanesGame. This will take care of initializing the graphics device (Direct3D device, context and application window) and will raise the proper events during the application life cycle. For now we will only modify its PreferredBackBufferWidth and PreferredBackBufferHeight properties because we want a portrait window for our game, although you can change other properties, like running the window in full screen mode or specifying a custom colour format for the back buffer.

internal class CrazyPlanesGame : Game
{
    private GraphicsDeviceManager deviceManager;

    public CrazyPlanesGame()
    {
        deviceManager = new GraphicsDeviceManager(this);
        deviceManager.PreferredBackBufferWidth = 480;
        deviceManager.PreferredBackBufferHeight = 800;
    }
}


Creating our GraphicsDeviceManager is mandatory; not doing so will throw an InvalidOperationException with the error message No GraphicsDeviceManager found when the game starts running.

Now, and to properly run, our game needs an entry point so the operating system knows what code should be called first. In C# this is achieved by declaring a class with a static function named Main of type void. Inside it, we will need to instantiate a copy of our CrazyPlanesGame and call its Run method. In addition, the Main function must be marked with the STAThread attribute because internally SharpDX uses Windows Forms to create the game window and this is one of its requisites.

public static class Program
{
    [STAThread]
    public static void Main()
    {
        using (CrazyPlanesGame game = new CrazyPlanesGame())
        {
            game.Run();
        }
    }
}

At last, go back to the CrazyPlanesGame class and override the Draw method. This will allow us to insert our own drawing code, which for now will be just clearing the screen to a cornflower blue colour:

protected override void Draw(GameTime gameTime)
{
    GraphicsDevice.Clear(Color.CornflowerBlue);

    base.Draw(gameTime);
}


Now you can run the project and take a look at the results of our coding session.

Our first SharpDX Toolkit game window

Source code

Unlike previously, the code for this series of tutorials will be all hosted in the same repository, with each solution inside its own folder. Here it is on GitHub, and you can find the one for this article inside the folder named Chapter1.

Proper lifecycle management of SharpDX resources in C#/XAML Universal Apps

In the last tutorial we learned how to properly use SharpDX in our XAML apps so we can get the power of DirectX without having to touch native C++ code. However, it was a very superficial introduction for demonstrative purposes that didn’t take into account anything more than single page applications. Using that code in real-world applications would introduce lots of problems (memory leaks, bad performance, crashes) that we are going to learn how to fix in this article. So, we are going to learn how to extend that code so it behaves better when our application has page navigation, gets snapped or is suspended/reactivated.

Now that we are focusing on integrating SharpDX with XAML applications, we have to take into account proper finalization of the created resources when navigating away from pages that contain SwapChainPanel/SwapChainBackgroundPanel controls.

Start by adding a new Page to the shared project. Add a button in MainPage to navigate to the new page, and another one there to make the frame go back in the navigation stack so we don’t end with an infinite navigation loop. If you run the project you will see that it works correctly; however, there is a small problem that can only be spotted by running the Performance and Diagnostics tool with the Memory Usage option selected:

leak


There is a memory leak in the application, because when we are navigating away from the page, we aren’t disposing any of the SharpDX resources we have created for rendering. And since they are wrappers over native objects, they will hardly be automatically reclaimed by the garbage collector.

But this has a very easy solution. Since we subscribed to the Loaded event of the SwapChainPanel for creating everything, we can subscribe to the Unloaded one and perform the opposite operations:

private void SwapChainPanel_Unloaded(object sender, RoutedEventArgs e)
{
    CompositionTarget.Rendering -= CompositionTarget_Rendering;    using (DXGI.ISwapChainPanelNative nativeObject = ComObject.As<DXGI.ISwapChainPanelNative>(this.SwapChainPanel))
    {
        nativeObject.SwapChain = null;
    }

    Utilities.Dispose(ref this.backBufferView);
    Utilities.Dispose(ref this.backBufferTexture);
    Utilities.Dispose(ref this.swapChain);
    Utilities.Dispose(ref this.deviceContext);
    Utilities.Dispose(ref this.device);
}


If we run again the memory diagnostics tool, we can verify that all allocated memory is properly being released when navigating away from the page:

leak_fixed


Window resizing

UPDATE: SourceSize isn’t the most appropriate approach to use when the application is being snapped, since it’s thought for uniformly scaling the swap chain to smaller sizes in less powerful hardware; using it this way will stretch the output image when drawing with Direct 3D. In this case, setting a different viewport will be enough.

Now we take into account when resizing happens so the swap chain dimensions match those of the control it is associated with. DirectX 11.2 introduced the new SourceSize property for DXGI.SwapChain2 objects, which lets you specify a region equal or smaller than the swap chain’s total size so you don’t have to always destroy and recreate it, only in the cases that a bigger one is needed.

Let’s subscribe to the SizeChanged event of the SwapChainPanel to accomplish this. But, this event can fire before the Loaded one if we don’t specify a default size for the control. To check that our swap chain is initialized and ready for resizing, we must declare a boolean flag (in our case it’s named isDXInitialized) and set it to true at the end of the SwapChainPanel_Loaded function. Now we can safely resize set the SourceSize property:

private void SwapChainPanel_SizeChanged(object sender, SizeChangedEventArgs e)
{
    if (isDXInitialized)
    {
        Size2 newSize = RenderSizeToPixelSize(e.NewSize);
        swapChain.SourceSize = newSize;
    }
}

This will work nicely in a number of cases but it’s far from perfect. Remember that I said that the specified region should be equal or smaller in size to the swap chain’s dimensions? If you make the control bigger at runtime or launch the application in snapped mode and resize it to full screen, you will receive a 0x887A0001 (DXGI_ERROR_INVALID_CALL) exception.

So, the logic outcome is to check the new size of the control and resize the swap chain if a bigger one is needed then set the SourceSize property, isn’t it?

private void SwapChainPanel_SizeChanged(object sender, SizeChangedEventArgs e)
{
    if (isDXInitialized)
    {
        Size2 newSize = RenderSizeToPixelSize(e.NewSize);        if (newSize.Width > swapChain.Description1.Width || newSize.Height > swapChain.Description1.Height)
        {
            swapChain.ResizeBuffers(swapChain.Description.BufferCount, (int)e.NewSize.Width, (int)e.NewSize.Height, swapChain.Description1.Format, swapChain.Description1.Flags);
        }

        swapChain.SourceSize = newSize;
    }
}


While technically true, it is still missing a minor detail: all resources linked to a swap chain must be destroyed before calling SwapChain2.ResizeBuffers. In our case it’s the render target and its associated resource view, so if you call the previous code as-is, you will receive the a dreaded DXGI_ERROR_INVALID_CALL exception again.

To fix this, we must destroy the associated resources, resize the swap chain and recreate them:

private void SwapChainPanel_SizeChanged(object sender, SizeChangedEventArgs e)
{
    if (isDXInitialized)
    {
        Size2 newSize = RenderSizeToPixelSize(e.NewSize);        if (newSize.Width > swapChain.Description1.Width || newSize.Height > swapChain.Description1.Height)
        {
            Utilities.Dispose(ref this.backBufferView);
            Utilities.Dispose(ref this.backBufferTexture);

            swapChain.ResizeBuffers(swapChain.Description.BufferCount, (int)e.NewSize.Width, (int)e.NewSize.Height, swapChain.Description1.Format, swapChain.Description1.Flags);

this.backBufferTexture = D3D11.Texture2D.FromSwapChain<D3D11.Texture2D>(this.swapChain, 0);
            this.backBufferView = new D3D11.RenderTargetView(this.device, this.backBufferTexture);
        }

        swapChain.SourceSize = newSize;
    }
}


 

Application suspension

At last, we are going to implement a new requisite when creating Windows Store apps that use DirectX: calling the DXGI.Device3.Trim method when the app goes into suspension. This function frees some internal buffers created by the graphics driver for faster performance and must be used to reduce the app’s memory footprint so there are less chances of it being terminated while suspended. The buffers will be transparently recreated when the app is reactivated, introducing only a minor execution delay.

So, let’s subscribe to the Suspending event of the current Application instance inside the SwapChainPanel_Loaded function, and unsubscribe inside SwapChainPanel_Unloaded to ensure proper finalization. Our new function will perform minimal processing, calling only DeviceContext.ClearState and Device3.Trim as per the guidelines. Since we aren’t storing an instance of DXGI.Device3, you can use QueryInterface on the current Direct3D 11.2 device or call GetDevice on the swap chain; remember to put it inside an using block or dispose it manually since both calls return a new object that needs to be freed:

private void Application_Suspending(object sender, Windows.ApplicationModel.SuspendingEventArgs e)
{
    if (isDXInitialized)
    {
        this.deviceContext.ClearState();        using (DXGI.Device3 dxgiDevice3 = this.swapChain.GetDevice<DXGI.Device3>())
        {
            dxgiDevice3.Trim();
        }
    }
}


Source code

As always, you can get the full soure code (Windows Store C#/XAML Universal App project, compatible with Visual Studio 2013 only) from GitHub.