Export (0) Print
Expand All

API Migration Guide: Managed DirectX 1.1 to XNA Framework

This migration guide is intended to aid the transition from Managed DirectX 1.1 to the XNA Framework. There are a number of differences to note when migrating to the XNA Framework. These changes are intentional, 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.

One major architectural difference is the overall scope of XNA Framework 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 run-time 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. Microsoft.Xna.Framework.dll and Microsoft.Xna.Framework.Game.dll correspond to elements from DirectX APIs that are useful for game runtimes.

XNA Game Studio also contains an extensible XNA Framework Content Pipeline designed to simplify importing, processing, and building game content. A complete representation of the XNA Framework Content Pipeline is outside the scope of this document, but there are several important MDX 1.1 features that are parelleled by XNA Framework Content Pipeline features.

For some developers, porting to the XNA Framework is a less than ideal solution. For one, the XNA Framework API has a significant number of naming differences from the native DirectX APIs. Developers employing MDX tool chains to build content for native games may be more comfortable with the MDX conventions. Additionally, the XNA Framework does not have support for run time processing of meshes. This may make the current XNA Framework unsuitable for tools that require run-time import or modification of mesh data.

Getting Started

There are two ways to port a game from MDX to the XNA Framework:

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

Creating a new XNA Framework game is the recommended porting path. The XNA Game Studio 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, the XNA Framework 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 Framework Application Model class library as a reference. The Application Model assembly is Microsoft.Xna.Framework.Game.dll and it can be referenced in the same manner as 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 advantage of the XNA Framework is that it is compatible with WinForms applications, yet it does not depend on any WinForms or System.Drawing types. 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 GraphicsDeviceManager, which simplifies device creation and management.

Graphics

XNA Framework 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 is also important to note that there is no distinction now between a D3D and a D3DX class. The XNA Framework abstracts the Graphics API to omit any non=intuitive differentiation in the Graphics namespaces.

Another major difference in XNA Framework Graphics is the differentiation of "in-game" and "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 Framework concentrates only on the in-game portions of the API, so some 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 Framework Content Pipeline.

MDX 1.1XNA Framework

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.1XNA Framework

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.

MDX 1.1XNA Framework

Microsoft.DirectX.Direct3D.SwapChain

No XNA Framework equivalent

Swap chains do not exist in the XNA Framework. This was done to improve cross-platform compatibility in the majority of XNA Game Studio rendering scenarios.

Graphics Device Setup

MDX 1.1XNA Framework

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 GraphicsAdapter class. The GraphicsAdapter class has an Adapters property, which is a collection of all the adapters on the current machine.

This 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.1XNA Framework
Microsoft.DirectX.Direct3D.Device

Microsoft.Xna.Framework.Graphics.GraphicsDevice

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

MDX 1.1XNA Framework

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 SetStreamFrequency method 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 VertexStreamCollection 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 this C# code.

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

Device.SetTexture

Device.GetTexture

GraphicsDevice.Textures[]

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

// Set texture stage 0 to myTexture.
device.Textures[0]= myTexture;
MDX 1.1XNA Framework

Device.SetSamplerState

Device.SamplerState[]

GraphicsDevice.SamplerStates[]

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

MDX 1.1XNA Framework

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.1XNA Framework

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.1XNA Framework

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.1XNA Framework

Device.ClipStatus

Device.RenderState.UseWBuffer

Device.RenderState.UpdateSurface

Device.RenderState.BeginScene

Device.RenderState.EndScene

No XNA Framework equivalent

These properties and methods have been removed from the XNA Framework due to limited hardware support, lack of widespread adoption, and Xbox 360 compatibility. ResourceUsage.Dynamic resources should be used for default pool textures that require surface updates. BeginScene and EndScene calls are not required by XNA Framework and have been omitted.

Formats

MDX 1.1XNA Framework

Microsoft.DirectX.Direct3D.Format

Microsoft.Xna.Graphics.SurfaceFormat

The MDX Format type has been renamed SurfaceFormat for clarity.

MDX 1.1XNA Framework

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.VertexData

No XNA Framework equivalent

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

Effects

MDX 1.1XNA Framework

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 between the MDX 1.1 implementation and the XNA Framework version. One minor change is that compiled effects were originally accessed though the GraphicsStream type. In the XNA Framework, CompiledEffect takes the place of the MDX 1.1 GraphicsStream.

Another feature of XNA Framework is a complete replacement for the EffectHandle interface. 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 Effect functions 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 it was 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.1XNA Framework

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 FrameworkColor structure contains all of the colors represented in System.Drawing.Color.

Sprites

MDX 1.1XNA Framework

Microsoft.DirectX.Direct3DX.Sprite

Microsoft.Xna.Framework.Graphics.SpriteBatch

The D3DX Sprite interface has been redesigned for the XNA Framework 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.1XNA Framework

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 Framework shader interfaces remain largely unchanged from their MDX and Direct3D 9 counterparts.

MDX 1.1XNA Framework

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 ShaderLoader interface would return a GraphicsStream object that could be used to create a vertex or pixel shader. In the XNA Framework, the ShaderCompiler returns a type-safe CompiledShader, from which you can retrieve input and output semantics.

Meshes and Animation

MDX 1.1XNA Framework

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 XNA Framework specifies the type Model, which is the run time component of mesh data imported and processed by the XNA Framework Content Pipeline. The XNA Game Studio documentation includes more information about Model and importing meshes with the XNA Framework Content Pipeline.

Dynamic run-time D3DX Mesh loading is not available in the XNA Framework, so an MDX application using D3DX mesh functions, animation controllers, of x-file mesh loading will require game-specific implementation of this 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. 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 the individual 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.1XNA Framework

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

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.1XNA Framework

Texture.Lock

Texture.Unlock

Texture2D.SetData

Texture2D.GetData

CubeTexture.Lock

CubeTexture.Unlock

TextureCube.SetData

TextureCube.GetData

VolumeTexture.Lock

VolumeTexture.Unlock

Texture3D.SetData

Texture3D.GetData

Like all resources, textures no longer have Lock or Unlock methods. Data is written and read by using the SetData and GetData functions described in the Graphics Resources section. The following code snippet is an example usage of the SetData and GetData methods with textures.


  // Create a 256 x 256 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, ResourceManagementMode.Automatic );
  tex.SetData<uint>( imageData );

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

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.

MDX 1.1XNA Framework

Microsoft.DirectX.Direct3D.Device.GetRendertargetData

Microsoft.Xna.Framework.GraphicsDevice.GetRenderTarget/a>

No MDX equivilent

Microsoft.Xna.Framework.Graphics.RenderTarget

Microsoft.Xna.Framework.Graphics.RenderTarget2D

Microsoft.Xna.Framework.Graphics.RenderTargetCube

Render target data is now handled though a strongly-typed object called RenderTarget. The RenderTarget2D.GetTexture function creates a texture with the render target data. This has made the Usage.RenderTarget type obsolete, and it has been omitted in the XNA Framework.

Buffers

MDX 1.1XNA Framework

Microsoft.DirectX.Direct3D.VertexBuffer

Microsoft.Xna.Framework.Graphics.VertexBuffer

Microsoft.DirectX.Direct3D.IndexBuffer

Microsoft.Xna.Framework.Graphics.IndexBuffer

XNA Framework 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.1XNA Framework

VertexBuffer.Lock

VertexBuffer.Unlock

VertexBuffer.SetData

VertexBuffer.GetData

IndexBuffer.Lock

IndexBuffer.Unlock

IndexBuffer.SetData

IndexBuffer.GetData

Like all graphics resources, the Lock and Unlock methods 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.1XNA Framework

VertexBuffer.Description

VertexBuffer

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

Math

Nearly all of the basic math types familiar to the native D3DX libraries and MDX have been replicated in the XNA 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.1XNA Framework

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 Framework.

Matrix Math

MDX 1.1XNA Framework

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 Matrix methods 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.1XNA Framework

Matrix.LookAtLH

Matrix.PerspectiveLH

Matrix.PerspectiveFovLH

Matrix.PerspectiveOffCenterLH

Matrix.OrthoLH

Matrix.OrthoOffCenterLH

No XNA Framework equivalent

Matrix.LookAtRH

Matrix.CreateLookAt

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 your own left-handed view matrices. Ideally, all new development should be in right-handed coordinates to be compatible with documentation, XNA Framework Content Pipeline components, and XNA Framework drop-in components.

MDX 1.1XNA Framework

Matrix.TransformCoordinate

Vector3.Transform

Matrix.LookAtRH

Matrix.CreateLookAt

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

MDX 1.1XNA Framework

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.1XNA Framework

Microsoft.DirectX.Quaternion

Microsoft.Xna.Framework.Quaternion

Quaternion math is unchanged from its MDX 1.1 implementation.

Audio

Audio in XNA Framework is based on the more advanced 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 run-time 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 major 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 Game Studio (XACT) is the same tool that is 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 http://msdn.microsoft.com/directx/sdk/.

After you have built an audio project, audio playback is a simple matter as far as coding goes. 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 a simple concept: 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.1XNA Framework

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.1XNA Framework

No MDX equivalent

Microsoft.Xna.Framework.Input.GamePad

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

This 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 game pads 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 beneath the surface. Some game ports may be fairly simple, 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 Game Studio.

Resources

XNA Creators Club Online
http://creators.xna.com/
XNA Game Studio Portal
http://www.microsoft.com/xna/
DirectX Developer Portal
http://msdn.microsoft.com/directx/
XNA Game Studio Team Blog
http://blogs.msdn.com/xna/
Microsoft Cross-Platform Audio Creation Tool (XACT)
http://msdn2.microsoft.com/en-us/library/bb174772.aspx

Community Additions

ADD
Show:
© 2014 Microsoft