XNA Book Files

CH04 - 2D Graphics

groundh0g — Sat, 19 Jan 2008 00:15:45 GMT

CH05 - 2D Graphics, Advanced

groundh0g — Sat, 19 Jan 2008 00:13:58 GMT

This ZIP archive contains source code from the book, XNA Game Studio Express: Developing Games for Windows and the Xbox 360, by Joseph Hall. The following paragraphs describe the changes that have been made to the code since it was first released with the book.

Dynamically Modifying Resources

The ResourceUsage enumeration has been removed from the XNA Framework as of version 2.0. It has been replaced with the more specific BufferUsage and TextureUsage enumerations. Any methods that expected ResourceUsage as a parameter have been updated to use one of these new flavors.

For example, the following line from Chapter 5 created a texture to store our screen data in XNA 1.0 and XNA 1.0 Refresh as we built the image, pixel by pixel.

    // we need to manage this texture ourselves, whenever
    // resources are reloaded, we set the member variable
    // to null, then recreate it here, just before use
    m_texWorkingBuffer = new Texture2D(
        device,
        SCREEN_WIDTH, SCREEN_HEIGHT,
        1,
        ResourceUsage.AutoGenerateMipMap,
        SurfaceFormat.Color,
        ResourceManagementMode.Automatic);

In XNA 2.0, we can create the same self-managed texture by using the following statement.

    // we need to manage this texture ourselves, whenever
    // resources are reloaded, we set the member variable
    // to null, then recreate it here, just before use
    m_texWorkingBuffer = new Texture2D(
        GraphicsDevice,
        SCREEN_WIDTH, SCREEN_HEIGHT,
        1,
        TextureUsage.AutoGenerateMipMap,
        SurfaceFormat.Color);

Notice that the ResourceUsage parameter has been replaced with a TextureUsage, and that the ResourceManagementMode parameter has been removed entirely.

See "Capturing the Screen" for another concrete example of this change.

Dynamically Modifying Resources (Bug?)

There seems to be a (seemingly rare) side effect of the recent changes to the APIs that allow us to dynamically inspect and modify resources. In certain scenarios, a call to GetData or SetData for a resource may generate an exception that reads, "The operation was aborted. You may not modify a resource that has been set on a device, or after it has been used within a tiling bracket."

From the exception text, it seems that the resource is still locked by the Framework when your code is trying to access it's contents. This is not the expected behavior, and a bug has been reported to the XNA team. In a post to the XNA forums (http://forums.xna.com/thread/35536.aspx), XNA team member, Shawn Hargreaves, suggested a work-around that seems to resolve this issue for Chapter 5 -- set the GraphicDevice's reference to the resource to null before calling GetData or SetData on the resource. This will remove the lock that the device has on the resource, allowing you to use it.

There are three places in the source code for Chapter 5 that call SetData. All three statements exhibited the described behavior when the code was executed on my laptop. Adding the following statement before each resolved this issue.

    GraphicsDevice.Textures[0] = null;

NOTE: For more complicated game logic, the reference to your resource may not be stored at index zero.

I haven't done any testing to see if code that was compiled against XNA 1.0 or XNA 1.0 Refresh exhibits this behavior when run under the XNA 2.0 runtime. This fix should work in that scenario as well, though.

Capturing the Screen

The ResolveBackBuffer method of the GraphicsDevice class no longer accepts a Texture2D as a target for pixel data. You must now pass an instance of the ResolveTexture2D class to this method. Creating a new ResolveTexture2D is very similar to creating a self-managed Texture2D. The biggest differences are that you don't need to specify the ResourceUsage or ResourceManagementMode enumerations in the constructor.

For example, the following line from Chapter 5 created a texture to receive our screen data in XNA 1.0 and XNA 1.0 Refresh.

    // create a texture to capture the back buffer
    Texture2D tex = new Texture2D(
        device,
        SCREEN_WIDTH,
        SCREEN_HEIGHT,
        1,
        ResourceUsage.ResolveTarget, // the magic option
        SurfaceFormat.Color,
        ResourceManagementMode.Manual);

In XNA 2.0, we just replace the self-managed texture with a ResolveTexture2D texture, and pass that to the ResolveBackBuffer method.

    // create a texture to capture the back buffer
    ResolveTexture2D tex = new ResolveTexture2D(
        GraphicsDevice,
        SCREEN_WIDTH,
        SCREEN_HEIGHT,
        1,
        SurfaceFormat.Color);

Notice how similar the code is.

New Game1 Member Variables

The Microsoft.Xna.Framework.Game class now has a SpriteBatch member variable, named "spriteBatch". We don't need to add one, so you can replace any reference in the text to "m_batch" with the provided member variable, "spriteBatch". Of course, this means that you'll want to remove this auto-generated SpriteBatch logic for game projects in which you won't be using any sprites (which is the case with the example 3D code in Chapter 06).

The Game class now provides a member variable (called "Content") which exposes the ContentManager class. We don't need to manage our own reference to the content manager now, so you can replace any reference in the text to "content" with the provided member variable, "Content" (notice the change in capitalization).

The Game class also provides a member variable (called "GraphicsDevice") which exposes the GraphicsDevice object which represents the active graphics device. You can replace any reference in the text to "graphics.GraphicsDevice" with the provided member variable, "GraphicsDevice". You'll see this change in the auto-generated Game1 class when you create a new XNA 2.0 game. The spriteBatch member variable is initialized using "new SpriteBatch(GraphicsDevice);" rather than the previous "new SpriteBatch(graphics.GraphicsDevice);".

LoadContent vs. LoadGraphicsContent

The LoadGraphicsContent and UnloadGraphicsContent methods of the Microsoft.Xna.Framework.Game class (technically, they're members of the DrawableGameComponent class, from which Game is derived) have been replaced with the LoadContent and UnloadContent methods. The old content management methods still work, but the compiler will generate deprecation warnings for them, and there's a good chance that the old methods will be removed from future releases of the XNA Framework.

Content Folder

All content is now stored under the Content folder of your project. Prefix any content subdirectory names in the code with "Content\". For example, most of the book's examples store game media in the "media" subdirectory, which is located just off the root directory of the project. An image named "myImage.png" within that subdirectory would have been refered to as "media\myImage" in XNA 1.0 and XNA 1.0 Refresh. In XNA 2.0, that same resource would be refered to as "Content\media\myImage".

The Content folder actually represents a subproject called "Content" which manages the building, converting, and importing of media for your game. Any media that is accessed via the ContentManager class should live here. This includes items such as textures, models, and XACT projects. Any game-specific content data that you manage manually, such as level data and persisted game data, is not housed within the Content directory.

Intuitive File Names

I used longer, more descriptive filenames for the solution files, project files, and directory names. The new names make it much easier to locate the source code for a specific chapter. This may cause issues if you do your development in a deeply-nested subdirectory, like the default Visual Studio project folder of "C:\Documents and Settings\{username}\My Documents\Visual Studio 2005\Projects\".

I suggest creating a folder off the root of the drive from which you wish to develop your XNA games. I use "C:\projects\" on my laptop, and "E:\projects\" on my desktop.

ZIP Anatomy

All of the ZIP files which host the book's source code use a parallel directory structure. I expect the user to download the ZIP files into a common directory, then extract the files from each ZIP directly into that directory, preserving the ZIP file's internal directory structure. For example, if you download PT1_CH04.zip, PT1_CH07.zip, and PT2_18.zip into the "C:\projects\" directory on your local PC, and then extract the files to that same folder, you should have the following directory structure on your local drive.

   C:\projects\Part 1 - Introduction\CH04 - Graphics 2D\
   C:\projects\Part 1 - Introduction\CH07 - Input GamePad\
   C:\projects\Part 2 - Genre Studies\CH18 - Board Games\

CH06 - 3D Graphics

groundh0g — Sat, 19 Jan 2008 00:01:38 GMT

CH07 - GamePad Input

groundh0g — Sat, 19 Jan 2008 00:00:31 GMT

CH08 - Keyboard Input

groundh0g — Fri, 18 Jan 2008 23:59:45 GMT

CH09 - Mouse Input

groundh0g — Fri, 18 Jan 2008 23:58:07 GMT

CH10 - Audio

groundh0g — Fri, 18 Jan 2008 23:56:41 GMT

This ZIP archive contains source code from the book, XNA Game Studio Express: Developing Games for Windows and the Xbox 360, by Joseph Hall. The following paragraphs describe the changes that have been made to the code since it was first released with the book.

Hefty File Warning

The source media for this project bloats the size of the download to nearly 48MB. If you're not terribly interested in seeing how poorly I applied the XNA Framework's audio APIs to this example, feel free to save me from bandwidth overages by not downloading this ZIP file. Of course, if you're going to actually use the code, please feel free to click the link. I'll try not to make you feel guilty. And I won't complain. Much.

New Version of XACT

In addition to numerous changes and additions to the XNA Framework, the XNA 2.0 release also brings a new version of the XACT utility. Upgrading your existing XACT projects is as easy as opening them in the new version of the tool, and clicking "Save".

You'll need to put your XACT project files (the *.xap files) in the Content folder off your project's root directory. As with the earlier versions of XNA, you'll also want to store your source media in the same relative location as your XAP file. That means that your WAV files will live in the Content directory as well. The Content Pipeline doesn't process WAV files directly, though. So you'll need to tag your XACT source media with a "Build Action" of "None", and a "Copy to Output Directory" of "Do not copy".

You may be asking why you should bother to include the source media in your project at all. After all, the Content Pipeline only needs the XAP file to kick off the content build. As long as the source media lives on the file system in a path that the XACT project can access, the build will work just fine without "polluting" the project with unbuildable (as far as Visual Studio is concerned, at least) files.

The short answer is that you don't (as far as I know) have to include the files in your project. The main reason that I suggest including them in the project is to make life easier when you're working with a team that takes advantage of source control. The new XNA release supports all flavors of Visual Studio 2005, and all but the Express version support version control. When you open a project for the first time from source control, Visual Studio will download all the files that are associated with the project -- including the "don't build me" files.

Of course, you could also build the XNA-friendly files within XACT, and import them into your project as normal "copy me when you build the project" content as well.

Changes to the Source Code

Since I moved the XACT project file into the Content directory, I also had to update the code that references the output of the XACT project. The original code to load audio content for this chapter's game looked like the following snippet.

    // initialize our sound objects
    m_audio = new AudioEngine("example.xgs");
    m_wave = new WaveBank(m_audio, "example.xwb");
    m_sound = new SoundBank(m_audio, "example.xsb");

During the conversion, I changed those lines to the following logic.

    // initialize our sound objects
    m_audio = new AudioEngine(@"Content\example.xgs");
    m_wave = new WaveBank(m_audio, @"Content\example.xwb");
    m_sound = new SoundBank(m_audio, @"Content\example.xsb");

So, with all the breaking changes that were made to XNA in this release, why didn't the XNA team switch to a model where audio content is loaded just like any other media content -- something like 'm_audio = Content.Load<AudioEngine>(@"Content\example.xgs");'? Beats me.

New Game1 Member Variables

The Microsoft.Xna.Framework.Game class now has a SpriteBatch member variable, named "spriteBatch". We don't need to add one, so you can replace any reference in the text to "m_batch" with the provided member variable, "spriteBatch". Of course, this means that you'll want to remove this auto-generated SpriteBatch logic for game projects in which you won't be using any sprites (which is the case with the example 3D code in Chapter 06).

The Game class now provides a member variable (called "Content") which exposes the ContentManager class. We don't need to manage our own reference to the content manager now, so you can replace any reference in the text to "content" with the provided member variable, "Content" (notice the change in capitalization).

The Game class also provides a member variable (called "GraphicsDevice") which exposes the GraphicsDevice object which represents the active graphics device. You can replace any reference in the text to "graphics.GraphicsDevice" with the provided member variable, "GraphicsDevice". You'll see this change in the auto-generated Game1 class when you create a new XNA 2.0 game. The spriteBatch member variable is initialized using "new SpriteBatch(GraphicsDevice);" rather than the previous "new SpriteBatch(graphics.GraphicsDevice);".

LoadContent vs. LoadGraphicsContent

The LoadGraphicsContent and UnloadGraphicsContent methods of the Microsoft.Xna.Framework.Game class (technically, they're members of the DrawableGameComponent class, from which Game is derived) have been replaced with the LoadContent and UnloadContent methods. The old content management methods still work, but the compiler will generate deprecation warnings for them, and there's a good chance that the old methods will be removed from future releases of the XNA Framework.

Content Folder

All content is now stored under the Content folder of your project. Prefix any content subdirectory names in the code with "Content\". For example, most of the book's examples store game media in the "media" subdirectory, which is located just off the root directory of the project. An image named "myImage.png" within that subdirectory would have been refered to as "media\myImage" in XNA 1.0 and XNA 1.0 Refresh. In XNA 2.0, that same resource would be refered to as "Content\media\myImage".

The Content folder actually represents a subproject called "Content" which manages the building, converting, and importing of media for your game. Any media that is accessed via the ContentManager class should live here. This includes items such as textures, models, and XACT projects. Any game-specific content data that you manage manually, such as level data and persisted game data, is not housed within the Content directory.

Intuitive File Names

I used longer, more descriptive filenames for the solution files, project files, and directory names. The new names make it much easier to locate the source code for a specific chapter. This may cause issues if you do your development in a deeply-nested subdirectory, like the default Visual Studio project folder of "C:\Documents and Settings\{username}\My Documents\Visual Studio 2005\Projects\".

I suggest creating a folder off the root of the drive from which you wish to develop your XNA games. I use "C:\projects\" on my laptop, and "E:\projects\" on my desktop.

ZIP Anatomy

All of the ZIP files which host the book's source code use a parallel directory structure. I expect the user to download the ZIP files into a common directory, then extract the files from each ZIP directly into that directory, preserving the ZIP file's internal directory structure. For example, if you download PT1_CH04.zip, PT1_CH07.zip, and PT2_18.zip into the "C:\projects\" directory on your local PC, and then extract the files to that same folder, you should have the following directory structure on your local drive.

   C:\projects\Part 1 - Introduction\CH04 - Graphics 2D\
   C:\projects\Part 1 - Introduction\CH07 - Input GamePad\
   C:\projects\Part 2 - Genre Studies\CH18 - Board Games\

CH11 - Storage

groundh0g — Fri, 18 Jan 2008 23:47:28 GMT

This ZIP archive contains source code from the book, XNA Game Studio Express: Developing Games for Windows and the Xbox 360, by Joseph Hall. The following paragraphs describe the changes that have been made to the code since it was first released with the book.

Storage Device Selection Guide

The Microsoft.Xna.Framework.Storage.StorageDevice is still the interface for accessing persistent storage media, but it no longer exposes the BeginShowStorageDeviceGuide or EndShowStorageDeviceGuide static methods. The class in XNA 2.0 which provides access to the file system (and prompts the user to select a storage device on the Xbox 360) is Microsoft.Xna.Framework.GamerServices.StorageDevice.Guide. It exposes two static methods that replace the ones that were removed from the StorageDevice class. They are named BeginShowStorageDeviceSelector and EndShowStorageDeviceSelector.

So, code that looked like this in XNA 1.0 and XNA 1.0 Refresh ...

    // show the storage guide on Xbox, has no
    // effect on Windows
    m_resultStorage = StorageDevice
        .BeginShowStorageDeviceGuide(null, null);

    // get a reference to the selected device
    m_storage = StorageDevice
        .EndShowStorageDeviceGuide(m_resultStorage);

... looks like this in XNA 2.0.

    // show the storage guide on Xbox, has no
    // effect on Windows
    m_resultStorage =
        Guide.BeginShowStorageDeviceSelector(null, null);

    // get a reference to the selected device
    m_storage =
        Guide.EndShowStorageDeviceSelector(m_resultStorage);

Notice the similarities. Other than the change of namespace and hosting class, your code should work just like it did in the XNA 1.0 days.

NOTE: The synchronized (i.e. blocking) method of storage device selection (ShowStorageDeviceGuide), which only worked on Windows without headaches, has been removed from the XNA Framework altogether. Only asynchronous storage device selection is supported in XNA 2.0.

The GameStorage and GameData classes in Chapter 11 (the chapter on the Storage APIs) don't require any changes at all. Those supporting classes don't reference the affected XNA Framework interfaces.

New Game1 Member Variables

The Microsoft.Xna.Framework.Game class now has a SpriteBatch member variable, named "spriteBatch". We don't need to add one, so you can replace any reference in the text to "m_batch" with the provided member variable, "spriteBatch". Of course, this means that you'll want to remove this auto-generated SpriteBatch logic for game projects in which you won't be using any sprites (which is the case with the example 3D code in Chapter 06).

The Game class now provides a member variable (called "Content") which exposes the ContentManager class. We don't need to manage our own reference to the content manager now, so you can replace any reference in the text to "content" with the provided member variable, "Content" (notice the change in capitalization).

The Game class also provides a member variable (called "GraphicsDevice") which exposes the GraphicsDevice object which represents the active graphics device. You can replace any reference in the text to "graphics.GraphicsDevice" with the provided member variable, "GraphicsDevice". You'll see this change in the auto-generated Game1 class when you create a new XNA 2.0 game. The spriteBatch member variable is initialized using "new SpriteBatch(GraphicsDevice);" rather than the previous "new SpriteBatch(graphics.GraphicsDevice);".

LoadContent vs. LoadGraphicsContent

The LoadGraphicsContent and UnloadGraphicsContent methods of the Microsoft.Xna.Framework.Game class (technically, they're members of the DrawableGameComponent class, from which Game is derived) have been replaced with the LoadContent and UnloadContent methods. The old content management methods still work, but the compiler will generate deprecation warnings for them, and there's a good chance that the old methods will be removed from future releases of the XNA Framework.

Content Folder

All content is now stored under the Content folder of your project. Prefix any content subdirectory names in the code with "Content\". For example, most of the book's examples store game media in the "media" subdirectory, which is located just off the root directory of the project. An image named "myImage.png" within that subdirectory would have been refered to as "media\myImage" in XNA 1.0 and XNA 1.0 Refresh. In XNA 2.0, that same resource would be refered to as "Content\media\myImage".

The Content folder actually represents a subproject called "Content" which manages the building, converting, and importing of media for your game. Any media that is accessed via the ContentManager class should live here. This includes items such as textures, models, and XACT projects. Any game-specific content data that you manage manually, such as level data and persisted game data, is not housed within the Content directory.

Intuitive File Names

I used longer, more descriptive filenames for the solution files, project files, and directory names. The new names make it much easier to locate the source code for a specific chapter. This may cause issues if you do your development in a deeply-nested subdirectory, like the default Visual Studio project folder of "C:\Documents and Settings\{username}\My Documents\Visual Studio 2005\Projects\".

I suggest creating a folder off the root of the drive from which you wish to develop your XNA games. I use "C:\projects\" on my laptop, and "E:\projects\" on my desktop.

ZIP Anatomy

All of the ZIP files which host the book's source code use a parallel directory structure. I expect the user to download the ZIP files into a common directory, then extract the files from each ZIP directly into that directory, preserving the ZIP file's internal directory structure. For example, if you download PT1_CH04.zip, PT1_CH07.zip, and PT2_18.zip into the "C:\projects\" directory on your local PC, and then extract the files to that same folder, you should have the following directory structure on your local drive.

   C:\projects\Part 1 - Introduction\CH04 - Graphics 2D\
   C:\projects\Part 1 - Introduction\CH07 - Input GamePad\
   C:\projects\Part 2 - Genre Studies\CH18 - Board Games\

CH13 - Ping Pong

groundh0g — Fri, 18 Jan 2008 23:38:19 GMT

CH14 - BrickBreaker

groundh0g — Fri, 18 Jan 2008 23:36:54 GMT

CH15 - Puzzle Games

groundh0g — Fri, 18 Jan 2008 23:34:54 GMT

CH16 - Top-Down Scroller

groundh0g — Fri, 18 Jan 2008 23:33:56 GMT

CH17 - Solitare

groundh0g — Fri, 18 Jan 2008 23:32:03 GMT

CH18 - Board Games

groundh0g — Fri, 18 Jan 2008 23:30:32 GMT

CH19 - Keyboard-Aware GamePad

groundh0g — Fri, 18 Jan 2008 23:29:04 GMT