Migrating from Beta 1 to Beta 2

Article
02/27/2007

This document outlines a few of the major changes in XNA Game Studio Express from Beta 1 to Beta 2 and explains how to migrate Beta 1 code to new Beta 2 projects.

Beta 1 project files

With the addition of the Content Pipeline to Beta 2 of XNA Game Studio Express, the project file format used in Beta 1 is incompatible with Beta 2. If you try to open a Beta 1 project with the Beta 2 version of XNA Game Studio Express, you will see the following error: "The project file was saved with an incompatible version of XNA Game Studio Express or the project file has become corrupted". Beta 1 users will have to create new Beta 2 projects and import their code and resources from their Beta 1 solutions.

To migrate a Beta 1 project to Beta 2

To create a new project, from the File menu, click New Project. Then click Windows Game, name your new project, and click OK.
To add classes from your old project to your new project, from the Project menu, click Add Existing Item. Then navigate to your Beta 1 project, select the class or classes to import, and click OK.
To add resources from your old project to your new project, click Add Existing Item, and then click Content Pipeline Files from the Files of type: drop-down box. You can select models, textures, effects and sounds to add to your project. See "Importing a resource into the Content Pipeline" below for more information.
Migrate code from your old project's Game1 class to your new project's Game1 class, including your Update and Draw methods. Use LoadGraphicsContent to load automatic and manual resources (note: "automatic" was called "managed" in Beta 1).
The Game Designer from Beta 1 does not exist in Beta 2. Use the Game constructor to set properties on the GraphicsDeviceManager (formerly GraphicsComponent).
Some code changes will be required before your Beta 1 code will compile properly in Beta 2. See "Framework Changes" below for a list of some of those changes.

Content Pipeline

Beta 2 of XNA Game Studio Express features the Content Pipeline for managing textures, meshes, and effects. Using Add Existing Item to add a resource to your project automatically links it with the Content Pipeline.

To import a resource into the Content Pipeline

To add resources to your project, click Add Existing Item, and then click Content Pipeline Files from the Files of type: drop-down box. You can select models, textures, effects and sounds to add to your project.
When the resource is part of your project, highlighting the resource will reveal Content Pipeline settings in the Properties window. The Content Importer and Content Processor are chosen automatically. The Asset Name is the friendly name assigned to the content. It is the name used when calling ContentManager.Load().
In code, use the ContentManager class to load resources. In new projects, the Game1 class has a content member representing the Content Manager. For example:
```
Texture2D SpriteTexture = content.Load <Texture2D>( "Sprite" );
```

Framework Changes

When you try to compile your Beta 1 code in a Beta 2 project, you will notice a few major changes to the XNA Framework in Beta 2. They are:

Framework changes from Beta 1 to Beta 2

StorageContainer is no longer used to create, delete, or open files. Use the System.IO.File class to perform operations using the new StorageContainer.Path property. For more information see Storage Overview .
CompiledEffect.GetShaderCode() is now CompiledEffect.GetEffectCode().
SpriteSortOptions has become SpriteSortMode, and SpriteStateOptions has become SaveStateMode.
Effect.Begin() takes a SaveStateMode instead of an EffectStateOptions. For EffectStateOptions.Default, use Begin() with no parameter.
VertexStream.VertexBuffer and VertexStream.VertexStride no longer exist; use VertexStream.SetSource() to set those values.
Update and Draw now pass a gameTime parameter. Use gameTime.ElapsedGameTime.TotalSeconds where you used ElapsedTime.TotalSeconds previously.
In Draw, you no longer need to call EnsureDevice, BeginScene, EndScene, or Present.
LoadGraphicsContent is called automatically when the graphics device is reset or recreated. If loadAllContent is true, Automatic resources (such as textures) should be loaded. Manual resources must be loaded in each call to LoadGraphicsContent and unloaded in each call to UnloadGraphicsContent.
The GraphicsComponent class is now the GraphicsDeviceManager class.

Component Model Changes

The component model has changed significantly from Beta 1 to Beta 2.

Component changes from Beta 1 to Beta 2

Game is no longer a component.
Componets aren't used in the designer anymore; they're regular classes.
Components implement one or more component interfaces now, IGameComponent, IUpdateable, and IDrawable. IGameComponent defines the Initialize method, IUpdateable defines the Update method, and IDrawable defines the Draw method.
There are two base classes that implement the game component interfaces, GameComponent and DrawableGameComponent. GameComponent implements IGameComponent and IUpdateable, while DrawableGameComponent implements all three interfaces.
Components can be created by implementing the interfaces or deriving from one of the component base classes.
Components automatically have their Draw, Update, and Initialize methods called for them now.

Xbox 360 Programming Considerations

XNA Game Studio Express Beta 2 allows users to create projects for their Xbox 360 and run those products on their retail Xbox 360 consoles. Running code on an Xbox 360 requires a separate project file. Windows projects cannot deploy to the Xbox 360. To set up XNA Game Studio Express to use your Xbox 360, see Developing Xbox 360 Games.

When programming for the Xbox 360, there are a few items to consider.

Programming considerations for the Xbox 360

The graphics back buffer that your project creates on the Xbox 360 is not necessarily the same size as the final resolution on the television connected to the Xbox 360. The Xbox 360 automatically scales output to the television resolution selected by the user in the System Blade. If the aspect ratio of the back buffer is different than the aspect ratio of the television, the Xbox 360 will automatically add "black bars" (letterboxing) if the user's display is not widescreen.
On the Xbox 360, games should respect the title safe region of the television display. This is typically the inner 80- to 90-percent of the television display. Critical text should not be displayed outside the title safe region. Games should also take care to ensure that any displayed text is readable on a standard definition television.
Only files that are included as part of the Xbox 360 project will be deployed to the console, and therefore only those files are available to File methods (for example, File.Open).