API Migration Guide:
Managed DirectX 1.1 to XNA Framework (Beta)

Microsoft Game Technology Group
August 2006

Overview

This guide is intended to aid the transition of Managed DirectX 1.1 developers moving to the XNA Framework Beta 1. There are a number of differences to recognize when migrating to the XNA Framework. These changes are deliberate, and were based on the following design principles for the XNA Framework.

• Embrace the creator community on Microsoft platforms (Windows and Xbox 360 in the initial release)
• Simplify the process of writing games
• Provide education solutions for academia
• Be familiar to experienced MDX or native DirectX developers

A major architectural difference is the overall scope of XNA versus MDX. While MDX had a 1-to-1 correspondence with many of the core technologies of DirectX, the XNA Framework focuses on an intersection of core DirectX functionality with other game-development technologies.

Another key difference between MDX 1.1 and the XNA Framework is the way the interfaces are packaged. The basic runtime functionality for the XNA Framework is contained in two assemblies.

• Microsoft.Xna.Framework.dll
• Microsoft.Xna.Framework.Game.dll

It is no longer necessary, for example, to reference a separate assembly to add audio support to a project. However, a higher-level differentiation has been made between execution-time and design-time components. The DLLs above correspond to elements from DirectX APIs that are useful for game runtimes.

The XNA Framework will also contain an extensible content pipeline designed to simplify importing, processing, and building game content. The XNA Content Pipeline assemblies are not available in XNA Game Studio Express Beta 1, but will ship with the final XNA Game Studio Express product.

Getting Started

To port a game from MDX to the XNA games framework, you can take one of two paths.

• Reference XNA Framework class libraries in an existing MDX-based project.
• Create a new XNA Windows game and port functionality piecewise from MDX-based sources.

One problem with the first path is that XNA Game Studio Express is supported only through Visual C# Express. This means that project files created with Visual Studio can be incompatible with the XNA Framework. You must create a new Visual C# Express project and import the code files into the new project. After you've installed XNA Game Studio Express alongside Visual C# Express, the XNA Framework DLLs will be available in the Add Referencesdialog box in Visual Studio.

Creating a new XNA Framework game is the recommended porting path. The XNA Game Studio Express Windows Game template automatically sets up the required references. You can then migrate code files into the new project.

Application Model

Managed DirectX 1.1 and the MDX 2.0 Beta both have functionality for interaction with WinForms. However, XNA has been designed for an unprecedented level of platform independence and cannot rely on WinForms for development on Windows and Xbox 360. Therefore, a common set of functionality has been provided in the form of the Application Model. It is important to note that this is not a one-for-one replacement to WinForms, MFC, or Win32; it is intended as a framework specific to game development on Windows and Xbox 360.

To include the application model in a project, you must add the XNA Application Model class library as a reference. The Application Model assembly is Microsoft.Xna.Framework.Game.dll and can be referenced like the XNA Framework assembly.

WinForms to Game

The Game assembly is also a standard partial replacement for the DirectX Managed Utility Toolkit (DXMUT) library previously available as part of the DirectX SDK sample source code. The Application Model does not cover all facets of DXMUT, but it does provide a broad replacement for its boilerplate features.

The XNA Framework is still compatible with WinForms applications, but it does not depend on any WinForms or System.Drawingtypes. For applications that already use WinForms, converting to Game is not necessary unless you are moving to a cross-platform architecture. Additionally, using the Game interface will add support for the GraphicsComponent, which simplifies device creation and management.

Graphics

XNA Graphics has received a major API overhaul from MDX 1.1, but like MDX, XNA Framework Graphics uses core Direct3D 9 graphics technology. The key interface changes are in the device, effects, D3DX types, and resources. It's also important to note that there is no distinction now between a D3D and a D3DX class. XNA abstracts the Graphics API to omit any unintuitive differentiation in the Graphics namespaces.

Another major difference in XNA Framework Graphics is the differentiation of in-game versus content-creation functions. In the native DirectX COM API, for example, there is no interface-level distinction between functions that should be used in-game versus those that should be reserved for content creation and processing. The XNA Games Framework concentrates only on the in-game portions of the API, so many Direct3D 9 features may appear to have gone missing. In actuality, functionality specific to content generation has been moved to its own API and utility set known as the XNA Content Pipeline. The XNA Content Pipeline is not available during Beta 1 of XNA Game Studio Express.

Perhaps the most radical departure from Direct3D 9 is the removal of fixed-function pipeline features from the XNA Framework. The long-term trend in the real-time graphics industry has been to move away from fixed-function graphics to the more flexible programmable model. The Xbox 360 does not have a fixed-function pipeline, so shader-based rendering is essential to creating cross-platform games.

The lack of fixed-function rendering in the XNA Framework requires some level of reorganization to port fixed-function rendering engines to the programmable pipeline. Keep in mind that several fixed-function-only classes have been removed altogether and that you must implement a shader-based solution.

MDX supported a variety of direct-memory-access operations through the custom GraphicsStream type. Direct memory access is not a feature of the XNA Framework, and data access has been restricted to specific type-safe classes, generic accessors, and arrays. The new access patterns are not only easier to implement, but in many scenarios they are much faster.

Graphics Device Setup

The static MDX Manager class has been largely reworked into a more organized set of interfaces based on the GraphicsAdapterclass. The GraphicsAdapter class has an Adapters property, which is a collection of all the adapters on the current machine. The following code example shows how to check a texture format to ensure that it is valid.

// Check whether device 0 supports A8R8G8B8 in hardware.
if ( GraphicsAdapter.Adapters[0].CheckDeviceFormat( DeviceType.Hardware,
   SurfaceFormat.Color, ResourceUsage.None, QueryUsage.None,
   ResourceType.Texture2D, Format.A8R8G8B8 ) )
{
    // A8R8G8B8 is supported in hardware.
}
else
{
    // A8R8B8G8 is not supported in this hardware.
}

Likewise, all of the useful Manager functions have a similar mapping to methods available from the MDX Manager class.

Graphics Device

GraphicsDevice behaves similarly to its MDX 1.1 counterpart, minus the fixed-function features in XNA. Most of the methods have been carried over to the new GraphicsDevice, but some have different parameters or overloads.

The MDX SetStreamSource function was used to enable a vertex buffer on a specific stream with a specific stride. In addition, the SetStreamFrequencymethod could be used on Shader Model 3.0–compliant hardware to change a specific vertex stream's frequency, enabling performance-boosting techniques such as hardware instancing.

The new access pattern makes intended functionality more discoverable. The supplied index indicates the stream being used. The VertexStreamobject returned from this indexer contains properties for the current vertex buffer, stride size, offset, and frequency of vertices on that stream. For example, to set an 8-byte stride size of vertex stream 0, you could use the following line of C# code:

// Set vertex stride for stream 0 to 8 bytes.
device.Vertices[0].VertexStride = 8;

Like streams, textures have been abstracted into their own collection representing the different samplers available on the device. The Texturesproperty is quite straightforward to use:

// Set texture stage 0 to myTexture.
device.Textures[0]= myTexture;

This functionality was already available in MDX 1.1. The only difference is that the SetSamplerState method has been removed. The Samplersproperty is a straightforward way of setting and reading all of the possible sampler states for a given stage. As in MDX1.1, the usage pattern requires an indexer corresponding to the sampler being accessed.

The RenderState property was already available in MDX 1.1, but the superfluous SetRenderState method has been removed for GraphicsDevice.

Fixed-function pipeline methods have been removed from the XNA Framework, so many MDX Device methods and properties do not have an XNA Framework counterpart.

Due to limited hardware support and lack of widespread adoption, patch-based drawing methods have been removed from the XNA Framework.

These render states have been removed from the XNA Framework due to limited hardware support, lack of widespread adoption, and Xbox 360 compatibility.

Formats

The MDX Format type has been renamed SurfaceFormatfor clarity.

The full list is included here, as this is one area where the naming convention changed dramatically. The XNA formats have identical layouts to their MDX counterparts.

Effects

The Effect interface has changed significantly from the MDX 1.1 implementation to the XNA Framework version. One minor change is that compiled effects were originally accessed though the GraphicsStreamtype. In the XNA Framework, CompiledEffect takes the place of the MDX 1.1 GraphicsStream.

A new feature of XNA Framework is a complete replacement for the EffectHandleinterface. The XNA Framework implements type-safe replacements to effect handles, which no longer have to be treated as "blobs" of formless data. Effect handles have been abstracted into the types of data or code they represent. The end result is that many potential pitfalls inherited from the native Effectfunctions are eliminated in the XNA Framework.

The new effect handles do not necessarily entail a major departure from the familiar MDX and native Direct3D 9 usage patterns. Some methods have been moved from Effect to its subcomponents where logical. The following code is a simplistic example of how to render using a multipass effect technique.

// Load a simple effect.
Effect myEffect = new Effect( device, "MyEffect.fx",
CompilerOptions.None, null );

// Set parameters.
myEffect.Parameters["g_mWorldViewProjection"].SetValue<Matrix>( Matrix.Identity );

// Render all passes.
myEffect.CurrentTechnique = myEffect.Techniques["T0"];
myEffect.Begin( EffectStateOptions.Default );
foreach( EffectPass pass in myEffect.CurrentTechnique.Passes )
{
    pass.Begin();
    // Draw primitives here....
    pass.End();
}
myEffect.End();

Effects in the XNA Framework behave more like a hierarchy than a loose collection of handles into a compiled effect file. Owner relationships have been established between Effect, EffectTechnique, and EffectPass. It follows then that the Effect.Techniques property returns a collection of techniques, which in turn define a collection of passes located in EffectTechnique.Passes.

Colors and Packed Vectors

System.Drawing is not an XNA Framework dependency, so the XNA Framework contains its own Color structure. The XNA Colorstructure contains all of the colors represented in System.Drawing.Color.

Sprites

The D3DX Sprite interface has been redesigned for XNA into the SpriteBatch class. It contains functionality similar to D3DX Sprite, but is designed to be more user-friendly to 2D and 3D developers alike.

Some functional changes are in the order of operations and the center of Z-rotation for 2D sprites. Sprites always rotate and scale around their center using SpriteBatch. Therefore, SpriteBatch transforms are applied per each SpriteBatch.Draw() call instead of per group of sprites.

Shaders

The basic XNA shader interfaces remain largely unchanged from their MDX and Direct3D 9 counterparts.

The MDX ShaderLoader interface has been replaced by a run-time ShaderCompiler interface in the XNA Framework. In MDX 1.1, the ShaderLoaderinterface would return a GraphicsStream object that could be used to create a vertex or pixel shader. In XNA, the ShaderCompiler returns a type-safe CompiledShader, from which you can retrieve input and output semantics.

Meshes and Animation

The traditional D3DX Mesh type has been removed from the XNA Framework. Several mesh-support types, such as animation controllers also do not have an equivalent in the XNA Framework. For Beta 1, an MDX game using the D3DX mesh functions, animation controllers, or x-file mesh loading will require game-specific implementation of this functionality.

The shipping XNA Game Studio Express product will contain the XNA Content Pipeline, which will add an end-to-end replacement for offline mesh operations as well as game runtime mesh functionality.

Graphics Resources

All graphics resources have undergone a revision to their primary data-access pattern. The Lock and Unlock methods of all resources have been removed in the XNA Framework and have been replaced with SetData/ GetData semantics. SetData and GetData behave quite differently from the Lock / Unlock pattern. Using Lock / Unlock, a given resource could have had read-only, write-only, or read-write properties during a lock. Those ambiguities have been completely cleared up by establishing discreet read and write operations for a resource. That does not mean that the call will always succeed. For example, attempting to set or get data on a ResourcePool.Default, ResourceUsage.None texture would cause an exception. However, there shouldn't be any confusion as to whether data is being written or read during a given function call.

The GetData / SetData functions use generic method parameters to indicate the type of the elements within the array. The type provided to the generic parameter indicates the type of theindividual elements in the array.

To use SetData or GetData, it is assumed that you previously allocated a data buffer for use. This is especially important for GetData, which, instead of returning a newly allocated array, fills an array provided as a parameter to GetData. You must manage the allocation of managed arrays used to read from and write to resources. Resources backed by arrays can help reduce managed heap allocation overhead, as long as the arrays are not constantly re-created.

Textures and Surfaces

Nearly all of the textures and surfaces have different names than they do in native Direct3D 9 and MDX 1.1. The new names are similar to the naming conventions used in Direct3D 10 and are intended to reduce ambiguity about the dimensions of a texture.

Additionally, the ImageData information class and other relevant texture data have been moved to the texture itself to remove ambiguities relating to its usage.

Like all resources, textures no longer have Lock / Unlockmethods. Data is written and read by using the SetData and GetDatafunctions described in the Graphics Resourcessection. The following code snippet is an example usage of the SetDataand GetData methods with textures.

// Create a 256x256 image in memory.
uint[] imageData = new uint[256 * 256];

// At this point, fill the array with data....

// Fill the texture with the image data.
Texture2D tex = new Texture2D( device, 256, 256, 1, ResourceUsage.None,
   SurfaceFormat.Color, ResourcePool.Managed );
tex.SetData<uint>( imageData );

// Get the image data from the surface.
uint[] imageDataOutput = new uint[256 * 256];
tex.GetData<uint>( imageDataOutput );

The XNA Framework does not contain a dedicated static texture loading interface separate from the texture classes themselves. Instead, the static FromFile methods are part of each texture type to simplify loading texture resources directly from an image file.

Buffers

XNA Index buffers have remained largely unchanged from their MDX counterparts. With fixed-function methods removed, there is no longer a need to provide a vertex buffer's Flexible Vertex Format (FVF) when creating the buffer.

Like all graphics resources, the Lock and Unlockmethods have been replaced by dedicated GetData and SetData calls for reading and writing data respectively. The following code shows an example usage of the new methods to write and read from a vertex buffer.

// Create a set of position vertices.
Vector3[] positionVerts = new Vector3[3];
positionVerts[0] = new Vector3( 0.0f, 0.0f, 0.0f );
positionVerts[1] = new Vector3( 1.0f, 0.0f, 0.0f );
positionVerts[2] = new Vector3( 1.0f, 1.0f, 0.0f );

// Create a vertex buffer and set the data to the position data
// in the positionVerts array.
VertexBuffer vb = new VertexBuffer( device, typeof( Vector3 ), 3,
    ResourceUsage.None, ResourcePool.Managed );
vb.SetData<Vector3>( positionVerts );

// Allocate a new array and fill it with data using GetData.
Vector3[] positionVertsOutput = new Vector3[3];
vb.GetData<Vector3>( positionVertsOutput );

Relevant VertexBuffer description information has been moved to the VertexBuffer class rather than a separate Descriptionproperty.

Math

Nearly all of the basic math types familiar to the native D3DX libraries and MDX have been replicated in the XNA Games Framework. There have been numerous additions to the XNA Framework math types and methods to reduce the amount of boilerplate math code that you have to rewrite for each new game. The biggest breaking change has been the removal of left-handed-coordinate-system math functions in favor of unifying on a right-handed coordinate system. This simplifies the Math API and omits functionality that causes a large amount of confusion.

Vector Math

Vector math is mostly unchanged from its MDX 1.1 implementation. However, several uncommon methods from MDX 1.1 are not available in XNA.

Matrix Math

There are several public and static name changes in the new matrix structure. The most common change is that the static Matrixmethods that create new matrices have been prefixed with the word "Create". Additionally, matrices have a new set of properties that allow rapid access to directional vectors from an orientation matrix.

Right-handed coordinate systems are the default coordinate systems in XNA Framework matrix math. The left-handed matrix methods are not available in the XNA Framework, but you can still create left-handed view matrices by hand. Ideally, all new development should be in right-handed coordinates to be compatible with documentation, Content Pipeline components, and XNA drop-in components.

Some matrix method names have been moved to other types to be more consistent with the rest of the XNA Framework.

Many matrix methods were superfluous or simply elaborate overloads for functionality that can be achieved by multiplying matrices. These were removed to simplify the Math API and clarify math-intensive code.

Quaternion Math

Quaternion math is unchanged from its MDX 1.1 implementation.

Audio

Audio in XNA is based on the more modern XACT tools and functions available in the DirectX SDK. In terms of both interface and functionality, XACT is very different from the DirectSound API found in MDX. XACT is both a playback and an authoring system for game audio. It consists of two main components: the XACT API and the Microsoft Cross-Platform Audio Creation Tool (also called XACT).

XACT is more than a replacement for DirectSound. The runtime XACT functions are easier to use than their DirectSound counterparts. XACT manages the minute details of streaming, threading, and playing individual sounds. The specifics of the audio processing are "baked in" at content creation time, so the loading and playback of audio can be as efficient as possible.

Using the XACT audio system is a huge improvement over DirectSound because it enables cross-platform content creation for audio on Xbox 360 and Windows PC. The tool used to create audio resources for XNA (XACT) is the same used in the Xbox 360 SDK and the DirectX SDK.

The Microsoft Cross-Platform Audio Creation Tool is documented in the DirectX SDK. For more information, see Microsoft DirectX Downloads.

Audio Playback

After you have built an audio project, audio playback is a simple matter in code. XACT organizes audio data into a global settings file, banks of wave data, and banks of sounds. Sound banks map audio "Cues" to sounds. Cues have a "play" function that works as you might expect. The following code snippet shows how to play a cue in just a few lines of XNA Framework code.

// Load the files built by XACT.
AudioEngine engine = new AudioEngine( "MyAudioSettings.xgs"
);
WaveBank wb = new WaveBank( engine, "MyWaveBank.xwb" );
SoundBank sb = new SoundBank( engine, "MySoundBank.xsb"
);

// Play the "Noisy" audio cue.
sb.GetCue( "Noisy" ).Play();

Input

XNA Framework input is designed around immediate state rather than buffered input events. This design fundamentally changes how input is handled between MDX and XNA Framework applications. Immediate input state polling is cleaner and more flexible than input events, but it requires some re-implementation to work in an existing game.

The key to using state-based input is straightforward: in-game actions that are triggered on changes in controller inputs require that the game store a previous controller state. For example, to "know" that a button has been pressed during a given frame, the game would have to store the fact that the button was in the released state during the previous frame.

Mouse and Keyboard

In MDX 1.1, you can obtain mouse and keyboard input from a variety of sources. DirectInput has its own mouse and keyboard interfaces supporting both immediate and buffered inputs. It is also typical to use WinForms events or even wndproc (message pump) overrides for input handling.

In the XNA Framework, mouse and keyboard inputs have been standardized into two interfaces. Unlike MDX or WinForms solutions, there is no setup whatsoever to be done with keyboard or mouse inputs. The following code example shows how to get inputs from a mouse and a keyboard.

MouseState mouse = Mouse.GetState();
KeyboardState keyboard = Keyboard.GetState();

if ( mouse.LeftButton == ButtonState.Pressed )
{
      // The left mouse button is down!
}
if ( keyboard.IsKeyDown( Keys.Space ) )
{
      // The SPACEBAR is down!
}

Xbox 360 Controller

The Xbox 360 Controller is accessed with DirectInput, but it is highly recommended that XNA Framework–based games take advantage of the classes provided in the namespace Microsoft.Xna.Framework.Input.

The Xbox 360 Controller for Windows uses the new XInput API, which is very streamlined compared to DirectInput. It supports only state-based input and, unlike DirectInput, does not automatically buffer input events. This means that you must poll input and update game state accordingly.

The following code shows how to poll an Xbox 360 Controller for input in just a few lines of code.

// Get the contoller state using the static GetState method.
GamePadState state = GamePad.GetState( PlayerIndex.One );

// Now check whether the controller is connected.
if ( state.IsConnected )
{
    // Check to see whether Button A is down.
    if ( state.Buttons.A == ButtonState.Pressed )
    {
        // Button A is pressed!
    }
}

As was the case for Keyboard and Mouse, there is no setup required: The first time GetState is called, the controller is set up and ready for use.

The Xbox 360 Controller also supports vibration. Unlike the complex setup required by DirectInput Force Feedback, vibration can be started or stopped in a single line of XNA Framework code!

// Turn on maximum vibration.
GamePad.SetVibration( PlayerIndex.One, 1.0f, 1.0f );

// Turn off vibration.
GamePad.SetVibration( PlayerIndex.One, 0f, 0f );

DirectInput Devices

DirectInput devices such as flight sticks, wheels, and older gamepads are not supported by the XNA Framework. Such devices are not compatible with the Xbox 360, and thus make poor candidates for cross-platform game support.

For games that require DirectInput device support, the MDX 1.1 DirectInput assembly is still the required means of accessing these controllers. DirectInput does not work across platforms and is not recommended for most XNA Framework projects.

Summary

While the XNA Framework may appear superficially similar to Managed DirectX or even native DirectX, the differences go well beneath the surface. Some game ports may be fairly straightforward, requiring mostly naming changes. Other games, particularly those relying on D3DX animation, complex DirectSound processing, or deeply integrated fixed-function pipeline features may require significant modification to be functional in XNA.

Resources

• XNA Game Studio Express Portal
• DirectX Developer Portal
• XNA Team Blog
• Microsoft Cross-Platform Audio Creation Tool (XACT)