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.

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3D.Light
Microsoft.DirectX.Direct3D.Material
Microsoft.DirectX.Direct3D.VertexFormat

 

No XNA Framework equivalent

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 1.1 XNA

 

Microsoft.DirectX.Direct3D.GraphicsStream

 

No XNA Framework equivalent

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3D.Manager

 

Microsoft.Xna.Framework.Graphics.GraphicsAdapter

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3D.Device

 

Microsoft.Xna.Framework.Graphics.GraphicsDevice

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.

MDX 1.1 XNA

 

Device.SetStreamSource
Device.SetStreamFrequency
Device.GetStreamSource
Device.GetStreamSourceFrequency

 

GraphicsDevice.Vertices[]

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;

MDX 1.1 XNA

 

Device.SetTexture
Device.GetTexture

 

GraphicsDevice.Textures[]

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;

MDX 1.1 XNA

 

Device.SetSamplerState
Device.SamplerState[]

 

GraphicsDevice.SamplerStates[]

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.

MDX 1.1 XNA

 

Device.SetRenderState
Device.RenderState

 

GraphicsDevice.RenderState

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

MDX 1.1 XNA

 

Device.Lights
Device.Material
Device.Transform
Device.VertexFormat
Device.RenderState.Ambient
Device.RenderState.Lighting
Device.RenderState.LocalViewer
Device.RenderState.EmissiveMaterialSource
Device.RenderState.ShadeMode
Device.RenderState.SpecularEnable
Device.RenderState.TweenFactor

 

No XNA Framework equivalent

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.

MDX 1.1 XNA

 

Device.DrawRectanglePatch
Device.DrawTrianglePatch
Device.NPatchMode
Device.RenderState.AdaptiveTessellateW
Device.RenderState.AdaptiveTessellateX
Device.RenderState.AdaptiveTessellateY
Device.RenderState.AdaptiveTessellateZ
Device.RenderState.MaxTessellationValue
Device.RenderState.MinTessellationValue
Device.RenderState.PatchEdgeStyle
Device.RenderState.PositionDegree
Device.RenderState.NormalizeNormals

 

No XNA Framework equivalent

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

MDX 1.1 XNA

 

Device.ClipStatus
Device.RenderState.UseWBuffer

 

No XNA Framework equivalent

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

Formats

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3D.Format

 

Microsoft.Xna.Graphics.SurfaceFormat

The MDX Format type has been renamed SurfaceFormatfor clarity.

MDX 1.1 XNA

 

Format.Unknown

 

SurfaceFormat.Unknown

 

Format.R8G8B8

 

SurfaceFormat.Bgr24

 

Format.A8R8G8B8

 

SurfaceFormat.Color

 

Format.X8R8G8B8

 

SurfaceFormat.Bgr32

 

Format.R5G6B5

 

SurfaceFormat.Bgr565

 

Format.X1R5G5B5

 

SurfaceFormat.Bgr555

 

Format.A1R5G5B5

 

SurfaceFormat.Bgra5551

 

Format.A4R4G4B4

 

SurfaceFormat.Bgra4444

 

Format.R3G3B2

 

SurfaceFormat.Bgr233

 

Format.A8

 

SurfaceFormat.Alpha8

 

Format.A8R3G3B2

 

SurfaceFormat.Bgra2338

 

Format.X4R4G4B4

 

SurfaceFormat.Bgr444

 

Format.A2B10G10R10

 

SurfaceFormat.Rgba1010102

 

Format.A8B8G8R8

 

SurfaceFormat.Rgba32

 

Format.X8B8G8R8

 

SurfaceFormat.Rgb32

 

Format.G16R16

 

SurfaceFormat.Rg32

 

Format.A2R10G10B10

 

SurfaceFormat.Bgra1010102

 

Format.A16B16G16R16

 

SurfaceFormat.Rgba64

 

Format.A8P8

 

SurfaceFormat.PaletteAlpha16

 

Format.P8

 

SurfaceFormat.Palette8

 

Format.L8

 

SurfaceFormat.Luminance8

 

Format.A8L8

 

SurfaceFormat.LuminanceAlpha16

 

Format.A4L4

 

SurfaceFormat.LuminanceAlpha8

 

Format.V8U8

 

SurfaceFormat.NormalizedByte2

 

Format.L6V5U5

 

SurfaceFormat.NormalizedLuminance16

 

Format.X8L8V8U8

 

SurfaceFormat.NormalizedLuminance32

 

Format.Q8W8V8U8

 

SurfaceFormat.NormalizedByte4

 

Format.V16U16

 

SurfaceFormat.NormalizedShort2

 

Format.A2W10V10U10

 

SurfaceFormat.NormalizedAlpha1010102

 

Format.D16Lockable

 

SurfaceFormat.Depth16Lockable

 

Format.D32

 

SurfaceFormat.Depth32

 

Format.D15S1

 

SurfaceFormat.Depth15Stencil1

 

Format.D24S8

 

SurfaceFormat.Depth24Stencil8

 

Format.D24X8

 

SurfaceFormat.Depth24

 

Format.D24X4S4

 

SurfaceFormat.Depth24Stencil4

 

Format.D16

 

SurfaceFormat.Depth16

 

Format.L16

 

SurfaceFormat.Luminance16

 

Format.D32SingleLockable

 

SurfaceFormat.Depth32SingleLockable

 

Format.D24SingleS8

 

SurfaceFormat.Depth24Stencil8Single

 

Format.Q16W16V16U16

 

SurfaceFormat.NormalizedShort4

 

Format.R16F

 

SurfaceFormat.HalfSingle

 

Format.G16R16F

 

SurfaceFormat.HalfVector2

 

Format.A16B16G16R16F

 

SurfaceFormat.HalfVector4

 

Format.R32F

 

SurfaceFormat.Single

 

Format.G32R32F

 

SurfaceFormat.Vector2

 

Format.A32B32G32R32F

 

SurfaceFormat.Vector4

 

Format.CxV8U8

 

SurfaceFormat.NormalizedByte2Computed

 

Format.Multi2Argb8

 

SurfaceFormat.Multi2Bgra32

 

Format.Dxt1

 

SurfaceFormat.Dxt1

 

Format.Dxt2

 

SurfaceFormat.Dxt2

 

Format.Dxt3

 

SurfaceFormat.Dxt3

 

Format.Dxt4

 

SurfaceFormat.Dxt4

 

Format.Dxt5

 

SurfaceFormat.Dxt5

 

Format.Yuy2

 

SurfaceFormat.VideoUyVy

 

Format.G8R8G8B8

 

SurfaceFormat.VideoRgBg

 

Format.R8G8B8G8

 

SurfaceFormat.VideoGrGb

 

Format.Uyvy

 

SurfaceFormat.VideoYuYv

 

Format.VertexData

 

No XNA Framework equivalent

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3DX.Effect
Microsoft.DirectX.Direct3DX.EffectCompiler
Microsoft.DirectX.Direct3DX.BaseEffect

 

Microsoft.Xna.Framework.Graphics.Effect

 

Microsoft.DirectX.Direct3DX.EffectHandle

 

Microsoft.Xna.Framework.Graphics.EffectAnnotation
Microsoft.Xna.Framework.Graphics.EffectFunction
Microsoft.Xna.Framework.Graphics.EffectParameter
Microsoft.Xna.Framework.Graphics.EffectPass
Microsoft.Xna.Framework.Graphics.EffectTechnique

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

MDX 1.1 XNA

 

System.Drawing.Color

 

Microsoft.Xna.Framework.Graphics.Color

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3DX.Sprite

 

Microsoft.Xna.Framework.Graphics.SpriteBatch

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3D.VertexShader

 

Microsoft.Xna.Framework.Graphics.VertexShader

 

Microsoft.DirectX.Direct3D.PixelShader

 

Microsoft.Xna.Framework.Graphics.PixelShader

 

Microsoft.DirectX.Direct3D.VertexDeclaration

 

Microsoft.Xna.Framework.Graphics.VertexDeclaration

 

Microsoft.DirectX.Direct3D.ConstantTable
Microsoft.DirectX.Direct3D.ConstantTableDescription

 

Microsoft.Xna.Framework.Graphics.ShaderConstantTable

 

Microsoft.DirectX.Direct3D.ConstantDescription

 

Microsoft.Xna.Framework.Graphics.ShaderConstant

 

Microsoft.DirectX.Direct3D.Semantic

 

Microsoft.Xna.Framework.Graphics.ShaderSemantic

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3DX.ShaderLoader

 

Microsoft.Xna.Framework.Graphics.ShaderCompiler
Microsoft.Xna.Framework.Graphics.CompiledShader

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3DX.Mesh
Microsoft.DirectX.Direct3DX.BaseMesh
Microsoft.DirectX.Direct3DX.SkinMesh
Microsoft.DirectX.Direct3DX.Frame
Microsoft.DirectX.Direct3DX.BoneCombination
Microsoft.DirectX.Direct3DX.BoneInfluences
Microsoft.DirectX.Direct3DX.AttributeRange
Microsoft.DirectX.Direct3DX.AttributeWeight
Microsoft.DirectX.Direct3DX.AllocateHierarchy
Microsoft.DirectX.Direct3DX.AnimationController
Microsoft.DirectX.Direct3DX.AnimationRootFrame

 

No XNA Framework equivalent

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3D.BaseTexture
Microsoft.DirectX.Direct3D.ImageData

 

Microsoft.Xna.Framework.Graphics.Texture

 

Microsoft.DirectX.Direct3D.Texture

 

Microsoft.Xna.Framework.Graphics.Texture2D

 

Microsoft.DirectX.Direct3D.VolumeTexture

 

Microsoft.Xna.Framework.Graphics.Texture3D

 

Microsoft.DirectX.Direct3D.CubeTexture

 

Microsoft.Xna.Framework.Graphics.TextureCube

 

Microsoft.DirectX.Direct3D.Volume

 

Microsoft.Xna.Framework.Graphics.Texture3DVolume

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.

MDX 1.1 XNA

 

Texture.Lock
Texture.Unlock

 

Texture2D.SetData
Texture2D.GetData

 

CubeTexture.Lock
CubeTexture.Unlock

 

TextureCube.SetData
TextureCube.GetData

 

VolumeTexture.Lock
VolumeTexture.Unlock

 

Texture3D.SetData
Texture3D.GetData

 

Surface.Lock
Surface.Unlock

 

Surface.SetData
Surface.GetData

 

Volume.Lock
Volume.Unlock

 

Texture3DVolume.SetData
Texture3DVolume.GetData

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 );

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3DX.TextureLoader.FromFile

 

Texture2D.FromFile

 

Microsoft.DirectX.Direct3DX.TextureLoader.FromCubeFile

 

TextureCube.FromFile

 

Microsoft.DirectX.Direct3DX.TextureLoader.FromVolumeFile

 

Texture3D.FromFile

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

MDX 1.1 XNA

 

Microsoft.DirectX.Direct3D.VertexBuffer

 

Microsoft.Xna.Framework.Graphics.VertexBuffer

 

Microsoft.DirectX.Direct3D.IndexBuffer

 

Microsoft.Xna.Framework.Graphics.IndexBuffer

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.

MDX 1.1 XNA

 

VertexBuffer.Lock
VertexBuffer.Unlock

 

VertexBuffer.SetData
VertexBuffer.GetData

 

IndexBuffer.Lock
IndexBuffer.Unlock

 

IndexBuffer.SetData
IndexBuffer.GetData

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 );

MDX 1.1 XNA

 

VertexBuffer.Description

 

VertexBuffer

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

MDX 1.1 XNA

 

Microsoft.DirectX.Vector2

 

Microsoft.Xna.Framework.Vector2

 

Microsoft.DirectX.Vector3

 

Microsoft.Xna.Framework.Vector3

 

Microsoft.DirectX.Vector4

 

Microsoft.Xna.Framework.Vector4

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

MDX 1.1 XNA

 

Microsoft.DirectX.Matrix

 

Microsoft.Xna.Framework.Matrix

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.

MDX 1.1 XNA

 

Matrix.LookAtLH
Matrix.PerspectiveLH
Matrix.PerspectiveFovLH
Matrix.PerspectiveOffCenterLH
Matrix.OrthoLH
Matrix.OrthoOffCenterLH

 

No XNA Framework equivalent

 

Matrix.PerspectiveRH

 

Matrix.CreatePerspective

 

Matrix.PerspectiveFovRH

 

Matrix.CreatePerspectiveFieldOfView

 

Matrix.PerspectiveOffCenterRH

 

Matrix.CreatePerspectiveOffCenter

 

Matrix.OrthoRH

 

Matrix.CreateOrthographic

 

Matrix.OrthoOffCenterRH

 

Matrix.CreateOrthographicOffCenter

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.

MDX 1.1 XNA

 

Matrix.TransformCoordinate

 

Vector2.Transform
Vector3.Transform
Vector4.Transform

 

Matrix.LookAtRH

 

Matrix.CreateLookAt

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

MDX 1.1 XNA

 

Matrix.AfflineTransformation
Matrix.AfflineTransformation2D

 

No XNA Framework equivalent

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

MDX 1.1 XNA

 

Microsoft.DirectX.Quaternion

 

Microsoft.Xna.Framework.Quaternion

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.

MDX 1.1 XNA

 

No MDX equivalent

 

Microsoft.Xna.Framework.Input.Mouse

 

No MDX equivalent

 

Microsoft.Xna.Framework.Input.Keyboard

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.

MDX 1.1 XNA

 

No MDX equivalent

 

Microsoft.Xna.Framework.Input.GamePad

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