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 Express 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 Express game and port functionality piece-by-piece from MDX-based sources.
One problem with the first way (reference XNA Framework class libraries in an existing MDX-based project) is that XNA Game Studio Express is supported only through Visual C# 2005 Express Edition. 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 have installed XNA Game Studio Express alongside Visual C# Express, the XNA Framework DLLs will be available in the Add References dialog 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, 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.1 | XNA 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.1 | XNA 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.1 | XNA 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 Express rendering scenarios.
Graphics Device Setup
| MDX 1.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3D.Manager |
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.1 | XNA Framework |
|---|---|
| Microsoft.DirectX.Direct3D.Device |
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.1 | XNA Framework |
|---|---|
Device.SetStreamSource Device.SetStreamFrequency Device.GetStreamSource Device.GetStreamSourceFrequency |
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.1 | XNA Framework |
|---|---|
Device.SetTexture Device.GetTexture |
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.1 | XNA Framework |
|---|---|
Device.SetSamplerState Device.SamplerState[] |
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.1 | XNA Framework |
|---|---|
Device.SetRenderState Device.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 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.1 | XNA 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.1 | XNA 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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3D.Format |
The MDX Format type has been renamed SurfaceFormat for clarity.
| MDX 1.1 | XNA Framework |
|---|---|
Format.Unknown |
|
Format.R8G8B8 |
|
Format.A8R8G8B8 |
|
Format.X8R8G8B8 |
|
Format.R5G6B5 |
|
Format.X1R5G5B5 |
|
Format.A1R5G5B5 |
|
Format.A4R4G4B4 |
|
Format.R3G3B2 |
|
Format.A8 |
|
Format.A8R3G3B2 |
|
Format.X4R4G4B4 |
|
Format.A2B10G10R10 |
|
Format.A8B8G8R8 |
|
Format.X8B8G8R8 |
|
Format.G16R16 |
|
Format.A2R10G10B10 |
|
Format.A16B16G16R16 |
|
Format.A8P8 |
|
Format.P8 |
|
Format.L8 |
|
Format.A8L8 |
|
Format.A4L4 |
|
Format.V8U8 |
|
Format.L6V5U5 |
|
Format.X8L8V8U8 |
|
Format.Q8W8V8U8 |
|
Format.V16U16 |
|
Format.A2W10V10U10 |
|
Format.D16Lockable |
|
Format.D32 |
|
Format.D15S1 |
|
Format.D24S8 |
|
Format.D24X8 |
|
Format.D24X4S4 |
|
Format.D16 |
|
Format.L16 |
|
Format.D32SingleLockable |
|
Format.D24SingleS8 |
|
Format.Q16W16V16U16 |
|
Format.R16F |
|
Format.G16R16F |
|
Format.A16B16G16R16F |
|
Format.R32F |
|
Format.G32R32F |
|
Format.A32B32G32R32F |
|
Format.CxV8U8 |
|
Format.Multi2Argb8 |
|
Format.Dxt1 |
|
Format.Dxt2 |
|
Format.Dxt3 |
|
Format.Dxt4 |
|
Format.Dxt5 |
|
Format.Yuy2 |
|
Format.G8R8G8B8 |
|
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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3DX.Effect Microsoft.DirectX.Direct3DX.EffectCompiler Microsoft.DirectX.Direct3DX.BaseEffect |
|
Microsoft.DirectX.Direct3DX.EffectHandle |
Microsoft.Xna.Framework.Graphics.EffectAnnotation Microsoft.Xna.Framework.Graphics.EffectFunction Microsoft.Xna.Framework.Graphics.EffectParameter |
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.1 | XNA Framework |
|---|---|
System.Drawing.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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3DX.Sprite |
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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3D.VertexShader |
|
Microsoft.DirectX.Direct3D.PixelShader |
|
Microsoft.DirectX.Direct3D.VertexDeclaration |
|
Microsoft.DirectX.Direct3D.ConstantTable Microsoft.DirectX.Direct3D.ConstantTableDescription |
|
Microsoft.DirectX.Direct3D.ConstantDescription |
Microsoft.Xna.Framework.Graphics.ShaderConstant |
Microsoft.DirectX.Direct3D.Semantic |
The basic XNA Framework shader interfaces remain largely unchanged from their MDX and Direct3D 9 counterparts.
| MDX 1.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3DX.ShaderLoader |
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.1 | XNA 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 Express 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. For example, attempting to set or get data on a ResourceManagementMode.Manual, 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 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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3D.BaseTexture Microsoft.DirectX.Direct3D.ImageData |
|
Microsoft.DirectX.Direct3D.Texture |
|
Microsoft.DirectX.Direct3D.VolumeTexture |
|
Microsoft.DirectX.Direct3D.CubeTexture |
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 Framework |
|---|---|
Texture.Lock Texture.Unlock |
|
CubeTexture.Lock CubeTexture.Unlock |
|
VolumeTexture.Lock VolumeTexture.Unlock |
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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3DX.TextureLoader.FromFile |
|
Microsoft.DirectX.Direct3DX.TextureLoader.FromCubeFile |
|
Microsoft.DirectX.Direct3DX.TextureLoader.FromVolumeFile |
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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3D.Device.GetRendertargetData |
|
No MDX equivilent |
Microsoft.Xna.Framework.Graphics.RenderTarget |
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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Direct3D.VertexBuffer |
|
Microsoft.DirectX.Direct3D.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.1 | XNA Framework |
|---|---|
VertexBuffer.Lock VertexBuffer.Unlock |
|
IndexBuffer.Lock IndexBuffer.Unlock |
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.1 | XNA Framework |
|---|---|
VertexBuffer.Description |
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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.Vector2 |
|
Microsoft.DirectX.Vector3 |
|
Microsoft.DirectX.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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.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.1 | XNA Framework |
|---|---|
Matrix.LookAtLH Matrix.PerspectiveLH Matrix.PerspectiveFovLH Matrix.PerspectiveOffCenterLH Matrix.OrthoLH Matrix.OrthoOffCenterLH |
No XNA Framework equivalent |
Matrix.LookAtRH |
|
Matrix.PerspectiveRH |
|
Matrix.PerspectiveFovRH |
|
Matrix.PerspectiveOffCenterRH |
|
Matrix.OrthoRH |
|
Matrix.OrthoOffCenterRH |
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.1 | XNA Framework |
|---|---|
Matrix.TransformCoordinate |
Vector3.Transform |
Matrix.LookAtRH |
Some matrix method names have been altered to be more consistent with the rest of the XNA Framework.
| MDX 1.1 | XNA 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.1 | XNA Framework |
|---|---|
Microsoft.DirectX.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 Express (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 https://msdn.microsoft.com/directx/sdk/.
Audio Playback
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.1 | XNA Framework |
|---|---|
No MDX equivalent |
|
No MDX equivalent |
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 Framework |
|---|---|
No MDX equivalent |
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 Express.
Resources
- XNA Creators Club Online
https://creators.xna.com/ - XNA Game Studio Express Portal
https://www.microsoft.com/xna/ - DirectX Developer Portal
https://msdn.microsoft.com/directx/ - XNA Game Studio Express Team Blog
https://blogs.msdn.com/xna/ - Microsoft Cross-Platform Audio Creation Tool (XACT)
https://msdn2.microsoft.com/en-us/library/bb174772.aspx