Direct3D 9 to Direct3D 10 Considerations (Direct3D 10)

The following page provides a basic outline of key differences between Direct3D 9 and Direct3D 10. The outline below provides some insight to assist developers with Direct3D 9 experience to explore and relate to Direct3D 10.

Although the info in this topic compares Direct3D 9 with Direct3D 10, because Direct3D 11 builds on the improvements made in Direct3D 10 and 10.1, you also need this info to migrate from Direct3D 9 to Direct3D 11. For info about moving beyond Direct3D 10 to Direct3D 11, see Migrating to Direct3D 11.

• Overview of the Major Structural Changes in Direct3D 10
  • Removal of Fixed Function
  • Device Object Creation Time Validation
• Engine Abstractions / Separation
  • Direct Removal of Direct3D 9 Dependencies
• Tricks for Quickly Resolving Application Build Issues
  • Overriding Direct3D 9 Types
  • Resolving Link Issues
  • Simulating Device CAPs
• Driving the Direct3D 10 API
  • Resource Creation
  • Views
  • Static versus Dynamic Resource Access
  • Direct3D 10 Effects
  • HLSL without Effects
  • Shader Compilation
  • Creation of Shader Resources
  • Shader Reflection Layer Interface
  • Input Assembler Layouts - Vertex Shader / Input Stream Linkage
  • Impact of Shader Dead Code Removal
  • Vertex Shader Input Structure Example
  • State Object Creation
• Porting Textures
  • File Formats Supported
  • Mapping Texture Formats
• Porting Shaders
  • Direct3D 10 Shaders are Authored in HLSL
  • Shader Signatures and Linkage
  • HLSL Shader Stage linkages
  • Constant Buffers
  • User clip planes in HLSL on feature level 9 and higher
• Additional Direct3D 10 Differences to Watch For
  • Integers as Input
  • Mouse Cursors
  • Mapping Texels to Pixels in Direct3D 10
  • Reference Counting Behavior Changes
  • Test Cooperative Level
  • StretchRect
• Additional Direct3D 10.1 Differences
• Related topics

Overview of the Major Structural Changes in Direct3D 10

• Removal of Fixed Function
• Device Object Creation Time Validation

The process of rendering using the Direct3D 10 device is structurally similar to Direct3D 9.

• Set a vertex stream source
• Set input layout in Direct3D 10 (set vertex stream declaration in Direct3D 9)
• Declare primitive topology
• Set textures
• Set state objects
• Set shaders
• Draw

The Draw call ties the operations together; the ordering of calls prior to the Draw call is arbitrary. The major differences in the Direct3D 10 API design are as follows:

• Removal of Fixed Function
• Removal of CAPS bits - Direct3D 10's base feature set is guaranteed
• Stricter management of: resource access, device state, shader constants, shader linkage (inputs and outputs to shaders) between stages
• API entry point name changes reflect the use of virtual GPU memory (Map() instead of Lock()).
• A debug layer can be added to the device at creation time
• The primitive topology is now an explicit state (separated from the Draw call)
• Explicit shader constants are now stored in constant buffers
• Shader authoring is done entirely in HLSL. The HLSL compiler now resides in the primary Direct3D 10 DLL.
• New programmable stage - the geometry shader
• Removal of BeginScene()/EndScene()
• Common 2D, focus and adapter-management functionality implemented in a new component: DXGI

Removal of Fixed Function

It is sometimes surprising that even in a Direct3D 9 engine that fully exploits the programmable pipeline, there remains a number of areas that depend on the fixed-function (FF) pipeline. The most common areas are usually related to screen-space aligned rendering for UI. It is for this reason that you are likely to need to build a FF emulation shader or set of shaders which provide the necessary replacement behaviors.

This documentation contains a white paper containing replacement shader sources for the most common FF behaviors (see Fixed Function EMU Sample). Some fixed-function pixel behavior including alpha test has been moved into shaders.

Device Object Creation Time Validation

The Direct3D 10 pipeline has been redesigned from the ground up in hardware and software with a primary intention to reduce CPU overhead (at Draw time). To reduce costs, all types of device data have been assigned an object with explicit creation methods provided by the device itself. This enables strict data validation at object creation time instead of during the Draw call as it often does with Direct3D 9.

Engine Abstractions / Separation

Applications, including Games, that wish to support both Direct3D 9 and Direct3D 10 need to have the rendering layers abstracted from the rest of the code base. There are many ways to achieve this but key to all of them is the design of the abstraction layer for the lower-level Direct3D device. All systems should communicate to the hardware through the common layer which is designed to provide GPU resource and low-level type management.

Direct Removal of Direct3D 9 Dependencies

When porting large, previously tested code bases, it is important to minimize the amount of code changes to those which are absolutely necessary to preserve previously tested behaviors in the code. Best practices include clearly documenting where items change using comments. It's often useful to have a commenting standard for this work which enables quick navigation through the code base.

The following is an example list of standard single line / start block comments which could be used for this work.

For multiple lines of source you should use the C style /* */ comments too but add the relevant start / end comments around these areas.

Tricks for Quickly Resolving Application Build Issues

• Overriding Direct3D 9 Types
• Resolving Link Issues
• Simulating Device CAPs

Overriding Direct3D 9 Types

It may be useful to insert a high level header file containing type definitions / overrides for Direct3D 9 base types which are no longer supported by the Direct3D 10 headers. This will help you minimize the amount of changes in the code and interfaces where there is a direct mapping from a Direct3D 9 type to the newly defined Direct3D 10 type. This approach is also useful for keeping code behaviors together in one source file. In this case, it is a good idea to define version neutral / generally named types which describe common constructs used for rendering yet span both Direct3D 9 and Direct3D 10 APIs. For example:

#if defined(D3D9)
typedef IDirect3DIndexBuffer9   IDirect3DIndexBuffer;
typedef IDirect3DVertexBuffer9  IDirect3DVertexBuffer;
#else //D3D10
typedef ID3D10Buffer            IDirect3DIndexBuffer;
typedef ID3D10Buffer            IDirect3DVertexBuffer
#endif

Other Direct3D 10 specific examples of this include:

typedef ID3D10TextureCube   IDirect3DCubeTexture;
typedef ID3D10Texture3D     IDirect3DVolumeTexture;
typedef D3D10_VIEWPORT      D3DVIEWPORT;
typedef ID3D10VertexShader  IDirect3DVertexShader;
typedef ID3D10PixelShader   IDirect3DPixelShader;

Resolving Link Issues

It is advisable to develop Direct3D 10 and Windows Vista applications using the latest version of Microsoft Visual Studio. However, it is possible to build a Windows Vista application which depends on Direct3D 10 using the earlier 2003 version of Visual Studio. Direct3D 10 is a Windows Vista platform component which has dependencies (as with the Server 2003 SP1 platform SDK) on the following lib: BufferOverflowU.lib is needed to solve any buffer_security check linker issues.

Simulating Device CAPs

Many applications contain areas of code which depend on device CAPS data being available. Work around this by overriding device enumeration and forcing device CAPS to sensible values. Plan to re-visit areas where there are dependencies on CAPS later for full removal of CAPS where possible.

Driving the Direct3D 10 API

This section focuses on the behavior changes caused by the Direct3D 10 API.

• Resource Creation
• Views
• Static versus Dynamic Resource Access
• Direct3D 10 Effects
• HLSL without Effects
• Shader Compilation
• Creation of Shader Resources
• Shader Reflection Layer Interface
• Input Assembler Layouts - Vertex Shader / Input Stream Linkage
• Impact of Shader Dead Code Removal
• Vertex Shader Input Structure Example
• State Object Creation

Resource Creation

The Direct3D 10 API has designed resources as generic buffer types which have specific bind flags according to the planned usage. This design point was chosen to facilitate near ubiquitous access of resources in the Pipeline for scenarios such as rendering to a vertex buffer then instantly drawing the results without interrupting the CPU. The following example demonstrates allocation of vertex buffers and index buffer where you can see that the resource description only differs by the GPU resource bind flags.

The Direct3D 10 API has provided texture helper methods for explicitly creating texture type resources but as you can imagine, these are really helper functions.

• CreateTexture2D()
• CreateTextureCube()
• CreateTexture3D()

When targeting Direct3D 10, you are likely to want to allocate more items during resource creation time than you are used to with Direct3D 9. This will become most apparent with the creation of Render Target buffers and Textures where you need to also create a view for accessing the buffer and setting the resource on the device.

Tutorial 1: Direct3D 10 Basics

Views

A view is a specifically typed, interface to data stored in a pixel buffer. A resource can have several views allocated on it at once and this feature is highlighted in the Single Pass Render to Cubemap sample contained in this SDK.

Programmers Guide page on Resource Access

CubeMap Sample

Static versus Dynamic Resource Access

For best performance, applications should partition their data use in terms of the static vs dynamic nature of the data. Direct3D 10 has been designed to take advantage of this approach and as such, the access rules for resources have been significantly tightened up over Direct3D 9. For static resources you should ideally populate the resource with its data during creation time. If your engine has been designed around the Create, Lock, Fill, Unlock design point of Direct3D 9, you may defer population from Create time by using a staging resource and the UpdateSubResource method on the resource interface.

Direct3D 10 Effects

Use of the Direct3D 10 Effects system is outside the scope of this article. The system has been written to take full advantage of the architectural benefits that Direct3D 10 provides. See the Effects (Direct3D 10) section for more detail on its use.

HLSL without Effects

The Direct3D 10 Shader pipeline may be driven without the use of the Direct3D 10 Effects system. Note that in this instance, all constant buffer, shader, sampler and texture binding must be managed by the application itself. See the sample link and following sections of this document for more detail:

HLSL without Effects sample

Shader Compilation

The Direct3D 10 HLSL compiler brings enhancements to the HLSL language definition and therefore has the ability to operate in 2 modes. For complete support of Direct3D 9 style intrinsic functions and semantics, compilation should be invoked using the COMPATIBILITY MODE flag which can be specified on a per compile basis.

The shader model 4.0 specific HLSL language semantics and intrinsic functions for Direct3D 10 can be found at HLSL. Major changes in syntax from Direct3D 9 HLSL to take the most notice of are in the area of texture access. The new syntax is the only form supported by the compiler outside of compatibility mode.

Creation of Shader Resources

The creation of compiled shader instances outside of the Direct3D 10 Effects system is done in a very similar manner to Direct3D 9 however, in Direct3D 10, it is important to keep the Shader Input signature around for later use. The signature is returned by default as part of the shader blob but may be extracted to reduce the memory requirements if needed. For more details, see Using Shaders in Direct3D 10.

Shader Reflection Layer Interface

The shader reflection layer is the interface by which information about the shader requirements may be obtained. This is particularly useful when creating Input Assembly linkages (see below) where you may need to traverse the shader input requirements to ensure you are supplying the correct input structure to the shader. You can create an instance of the reflection layer interface at the same time as creating an instance of a compiled shader.

The shader reflection layer replaces D3DX9 methods that provide similar functionality. For example IsParameterUsed is replaced by the GetDesc method.

Input Assembler Layouts - Vertex Shader / Input Stream Linkage

The Input Assembler (IA) replaces the Direct3D 9 style Vertex Stream Declaration and it's description structure is very similar in form. The main difference that the IA brings is that the IA layout object created must directly map to a specific format of shader input signature. The mapping object created to link the input stream to shader may be used across any number of shaders where the shader input signature matches that of the shader used to create the Input Layout.

To best drive the pipeline with static data, you should consider the permutations of input stream format to possible shader input signatures and create the IA layout object instances as early as is possible and reuse them where possible.

Impact of Shader Dead Code Removal

The following section details a significant difference between Direct3D 9 and Direct3D 10 that is likely to require careful handling in your engine code. Shaders which contain conditional expressions often have certain code paths removed as part of the compilation process. In Direct3D 9, two kinds of inputs may be removed (marked for removal) when unused: signature inputs (like the example below) and constant inputs. If the end of the constant buffer contains unused entries, the size declaration in the shader will reflect the size of the constant buffer without the unused entries at the end. Both of these kinds of inputs remain in signatures or constant buffers Direct3D 10 with a special exception in the case of unused constant inputs at the end of a constant buffer. This may have an impact on the engine when handling large shaders and creating input layouts. Elements which are removed by dead code optimizations in the compiler must still be declared in the input structure. The following example demonstrates this:

Vertex Shader Input Structure Example

struct VS_INPUT
{
float4 pos: SV_Position;
float2 uv1 : Texcoord1;
float2 uv2 : Texcoord2; *
};

* Direct3D 9 dead code removal would remove the declaration in the shader due to conditional dead code removal

float4x4  g_WorldViewProjMtx;
static const bool g_bLightMapped = false; // define a compile time constant

VS_INPUT main(VS_INPUT i) 
{
    VS_INPUT o;
    o.pos = mul( i.pos, g_WorldViewProjMtx);
    o.uv1 = i.uv1;
    if ( g_bLightMapped )
    {
        o.uv2 = i.uv2;
    }
    return o;
}

Or, you could make it even more obvious that the constant is a compile time constant with the following declaration:

#define LIGHT_MAPPED false

In the above example, under Direct3D 9, the uv2 element would be removed due to dead code optimizations in the compiler. Under Direct3D 10, the dead code will still be removed but the shader input assembler layout requires the definition of the input data to exist. The shader reflection layer provides the means to handle this situation in a generic manner whereby you can traverse the shader input requirements and ensure that you provide a full description of the Input Stream to shader signature mapping.

Here's an example function to detect the existence of a semantic name/index in a function signature:

// Returns true if the SemanticName / SemanticIndex is used in the input signature.
// pReflector is a previously acquired shader reflection interface.
bool IsSignatureElementExpected(ID3D10ShaderReflection *pReflector, const LPCSTR SemanticName, UINT SemanticIndex)
{
    D3D10_SHADER_DESC               shaderDesc;
    D3D10_SIGNATURE_PARAMETER_DESC  paramDesc;

    Assert(pReflector);
    Assert(SemanticName);

    pReflector->GetDesc(&shaderDesc);

    for (UINT k=0; k<shaderDesc.InputParameters; k++)
    {
        pReflector->GetInputParameterDesc( k, &paramDesc);
        if (wcscmp( SemanticName, paramDesc.SemanticName)==0 && paramDesc.SemanticIndex == SemanticIndex) 
            return true;
    }

    return false;
}

State Object Creation

When porting engine code, it may help to initially use a default set of state objects and disable all Direct3D 9 device render state / texture state setting. This will cause rendering artifacts but is the quickest way to get things up and running. You can later construct a state object management system which can use a compound key to enable maximum reuse of the number of state objects being used.

Porting Textures

File Formats Supported

The D3DXxxCreateXXX and D3DXxxSaveXXX functions that create or save a texture from or to a graphics file (for example, D3DX10CreateTextureFromFile) support a different set of file formats in Direct3D 10 than they did in Direct3D 9:

For details, compare the Direct3D 9 D3DXIMAGE_FILEFORMAT enumerations with the D3DX10_IMAGE_FILE_FORMAT enumerations for Direct3D 10.

Mapping Texture Formats

The following table shows the mapping of texture formats from Direct3D 9 to Direct3D 10. Any content in formats not available in DXGI will need to be converted by utility routines.

¹DXGI 1.1, which is included in the Direct3D 11 runtime, includes BGRA formats. However, support for these formats is optional for Direct3D 10 and 10.1 devices with drivers that are implemented to the Windows Display Driver Model (WDDM) for Windows Vista (WDDM 1.0). Consider using DXGI_FORMAT_R8G8B8A8_UNORM instead. Alternatively, you can create your device with D3D10_CREATE_DEVICE_BGRA_SUPPORT to ensure that you only support computers with the Direct3D 11.0 runtime and a WDDM 1.1 driver or higher installed.

²DXGI 1.0 defined 5:6:5 and 5:5:5:1 formats, but they were not supported by the Direct3D 10.x or Direct3D 11.0 runtime. These formats are optionally supported with DXGI 1.2 in the DirectX 11.1 runtime, which is required for feature level 11.1 video adapters and WDDM 1.2 (display driver model starting with Windows 8) drivers and already supported on 10level9 feature levels.

³DXGI 1.2 introduced the 4:4:4:4 format. This format is optionally supported in the DirectX 11.1 runtime, which is required for feature level 11.1 video adapters and WDDM 1.2 drivers and already supported on 10level9 feature levels.

For uncompressed formats, DXGI has limited the support for arbitrary pixel format patterns; all uncompressed formats must be of type RGBA. This might require swizzling of existing assets pixel formats, which we recommend that you compute as an offline pre-process pass where possible.

Porting Shaders

Direct3D 10 Shaders are Authored in HLSL

Direct3D 10 limits the use of assembly language to that of debugging purposes only, therefore any hand written assembly shaders used in Direct3D 9 will need to be converted to HLSL.

Shader Signatures and Linkage

We discussed the requirements for Input Assembly linkage to Vertex shader input signatures earlier in this document (see above). Note that the Direct3D 10 runtime has also tightened the requirements for stage to stage linkage between shaders. This change will affect shader sources where the binding between stages may not have been fully described under Direct3D 9. For example:

VS_OUTPUT                       PS_INPUT
float4   pos : SV_POSITION;     float4 pos : SV_POSITION;
float4   uv1 : TEXCOORD1;       float4 uv1 : TEXCOORD1;
float4x3 tangentSp : TEXCOORD2; float4 tangent : TEXCOORD2; *
float4   Color : TEXCOORD6;     float4 color : TEXCOORD6;

* Broken VS - PS Linkage - even though the pixel shader may not be interested in the full matrix, the linkage must specify the full float4x3.

Note, the linkage semantics between stages must match exactly however, the target stages inputs may be a prefix of the values being output. In the example above, the pixel shader could have position and texcoord1 as the only inputs, but it could not have the position and texcoord2 as the only inputs due to the ordering constraints.

HLSL Shader Stage linkages

Linkage between shaders may occur at any of the following points in the pipeline:

• Input Assembler to Vertex Shader
• Vertex Shader to Pixel Shader
• Vertex Shader to Geometry Shader
• Vertex Shader to Stream Output
• Geometry Shader to Pixel Shader
• Geometry Shader to Stream Out

Constant Buffers

For ease of porting content from Direct3D 9 an initial approach to constant management outside of the Effects system might involve the creation of a single constant buffer containing all the required constants. It is important for performance to order constants into buffers by the expected frequency of update. This organization will reduce the amount of redundant constant sets to a minimum.

User clip planes in HLSL on feature level 9 and higher

Starting with Windows 8, you can use the clipplanes function attribute in an HLSL function declaration rather than SV_ClipDistance to make your shader work on feature level 9_x as well as feature level 10 and higher. For more info, see User clip planes on feature level 9 hardware.

Additional Direct3D 10 Differences to Watch For

Integers as Input

In Direct3D 9, there was no real hardware support for integer data types, however Direct3D 10 hardware supports explicit integer types. If you have floating-point data in your vertex buffer, then you must have a float input. Otherwise an integer type will be the bit pattern representation of the floating-point value. An integer type is not allowed for a pixel shader input unless the value is marked for no interpolation (see Interpolation Modifiers).

Mouse Cursors

On previous versions of Windows, the standard GDI mouse cursor routines did not operate correctly on all full-screen exclusive devices. The SetCursorProperties, ShowCursor, and SetCursorPosition APIs were added to handle these cases. Since Windows Vista's version of GDI fully understands DXGI surfaces, there is no need for this specialized mouse cursor API so there is no Direct3D 10 equivalent. Direct3D 10 applications should instead use the standard GDI mouse cursor routines for mouse cursors.

Mapping Texels to Pixels in Direct3D 10

In Direct3D 9, texel centers and pixel centers were a half unit apart (see Directly Mapping Texels to Pixels (Direct3D 9)). In Direct3D 10, texel centers are already at half-units, so there is no need to shift vertex coordinates at all.

Rendering full-screen quads is more straight-forward with Direct3D 10. Full-screen quads should be defined in clipspace (-1,1) and simply passed through the vertex shader with no changes. This way, there is no need to reload your vertex buffer every time the screen resolution changes, and there's no extra work in the pixel shader to manipulate the texture coordinates.

Reference Counting Behavior Changes

Unlike previous Direct3D versions, the various Set functions will not hold a reference to the devices objects. This means that the application must ensure that it holds a reference on the object for as long as it would like that object to be bound to the pipeline. When the ref count of the object drops to zero, then the object will be unbound from the pipeline as it is destroyed. This style of reference holding is also known as weak-reference holding, so therefore each bind location on the Device object holds a weak-reference to the interface/ object. Unless explicitly mentioned otherwise, this behavior should be assumed for all Set methods. Whenever destruction of an object causes a bind point to be set to NULL out, the Debug Layer will issue a warning. Note, calls to device Get methods such as OMGetRenderTargets will increase the reference count of objects being returned.

Test Cooperative Level

The functionality of the Direct3D 9 API TestCooperativeLevel is analogous to setting the DXGI_PRESENT_TEST when calling Present.

StretchRect

A function similar to the Direct3D 9 IDirect3DDevice9::StretchRect method is not available in Direct3D 10 and 10.1. To copy resource surfaces, use ID3D10Device::CopySubresourceRegion. For resizing operations, render to a texture by using texture filtering. For converting MSAA surfaces to non-MSAA surfaces, use ID3D10Device::ResolveSubresource.

Additional Direct3D 10.1 Differences

Windows Vista with Service Pack 1 (SP1) included a minor update to Direct3D 10 and Direct3D 10.1, which exposed the following additional hardware features:

• MSAA per-sample shaders
• MSAA depth read-back
• Independent blend modes per render target
• Cube map arrays
• Render to block-compressed (BC) formats

The Direct3D 10.1 update added support for the following new interfaces, which are derived from existing interfaces:

• ID3D10Device1
• ID3D10BlendState1
• ID3D10ShaderResourceView1

The Direct3D 10.1 update also included the following additional structures:

• D3D10_RENDER_TARGET_BLEND_DESC1
• D3D10_BLEND_DESC1
• D3D10_SHADER_RESOURCE_VIEW_DESC1

The Direct3D 10.1 API includes a new concept named feature level. This concept means that you can use the Direct3D 10.1 API to drive Direct3D 10.0 (D3D10_FEATURE_LEVEL_10_0) or Direct3D 10.1 (D3D10_FEATURE_LEVEL_10_1) hardware. Because the Direct3D 10.1 API is derived from the Direct3D 10 interfaces, applications can create a Direct3D 10.1 device, then use it as a Direct3D 10.0 device except where new 10.1-specific features are needed (provided that the D3D10_FEATURE_LEVEL_10_1 feature-level is present and supports these features).

Windows 7 contained a minor update to the Direct3D 10.1 API that is included in the Direct3D 11 runtime. This update adds support for the following feature levels:

• D3D10_FEATURE_LEVEL_9_1
• D3D10_FEATURE_LEVEL_9_2
• D3D10_FEATURE_LEVEL_9_3

Windows 7 also added support to Direct3D 10.1 for Windows Advanced Rasterization Platform (WARP). You can specify a WARP driver by using D3D10_DRIVER_TYPE_WARP.

For more information about Direct3D 10.1, see Direct3D 10.1 Features and the D3D10_FEATURE_LEVEL1 enumeration.

Related topics

Programming Guide for Direct3D 10