Microsoft DirectX 9.0

Converting to DirectX 9.0

The following features were changed in Microsoft?DirectX?9.0. If you are using these features, see the changes listed below to help you port your application to DirectX 9.0.

BaseVertexIndex Changes

In DirectX 8.x, SetIndices required a pointer to the index buffer and a BaseVertexIndex for the starting position in the vertex buffer. An application batching different objects into the vertex buffer had to switch the index buffer (or make a call to SetIndices) before calling DrawIndexedPrimitive.

In DirectX 9.0, the starting position in the vertex buffer, BaseVertexIndex, has been moved to IDirect3DDevice9::DrawIndexedPrimitive.

    HRESULT IDirect3DDevice9::DrawIndexedPrimitive( 
        D3DPRIMITIVETYPE PrimType, 
        INT BaseVertexIndex, 
        UINT minIndex, 
        UINT NumVertices, 
        UINT startIndex, 
        UINT primCount ); 

    HRESULT SetIndices( 
        IDirect3DIndexBuffer9* pIndexData ); 

CreateImageSurface Changes

CreateImageSurface was renamed IDirect3DDevice9::CreateOffscreenPlainSurface. An additional parameter, D3DPOOL, was added.

HRESULT CreateOffscreenPlainSurface(
    UINT    Width,
    UINT    Height,
    D3DFORMAT Format,
    D3DPOOL Pool,
    IDirect3DSurface9** pReturnedSurfaceInterface);

D3DPOOL_SCRATCH will return a surface that has identical characteristics to a surface created by the former CreateImageSurface.

D3DPOOL_DEFAULT is the appropriate pool for use with IDirect3DDevice9::StretchRect and IDirect3DDevice9::ColorFill.


Applications now have to explicitly ask for the Microsoft Windows?Hardware Qualification Level, because the response takes relatively long (a few seconds). D3DENUM_NO_WHQL_LEVEL has been removed and D3DENUM_WHQL_LEVEL has been added. For more information, see the WHQLLevel member of D3DADAPTER_IDENTIFIER9.

EnumAdapterModes Changes

The IDirect3D9::EnumAdapterModes now takes a D3DFORMAT.

HRESULT IDirect3D9::EnumAdapterModes( 
       UINT Adapter, 
       D3DFORMAT Format, 
       UINT Mode, 
       D3DDISPLAYMODE *pMode); 

The additional format parameter supports an expanding set of display modes. To protect applications from enumerating formats that were not invented when the application shipped, the application must tell Microsoft Direct3D?the format for which display modes should be enumerated. The resulting array of display modes will differ only by width, height, and refresh rate.

The application specifies a pixel format and the enumeration is restricted to those display modes that exactly match the format. Allowed formats are D3DFMT_X8R8G8B8, D3DFMT_A8R8G8B8, D3DFMT_A2B10G10R10, D3DFMT_X1R5G5B5, D3DFMT_A1R5G5B5, and D3DFMT_R5G6B5.

Enumeration is equivalent for alpha and nonalpha versions of the same format. The returned FORMAT member of D3DDISPLAYMODE will always be filled with the same format supplied by the application.

This method treats 565 and 555 as equivalent, and returns the correct version in the Format. The difference comes into play only when the application locks the back buffer, and there is an explicit flag that the application must set in order to accomplish this.

Get/SetStreamSource Changes

One parameter has been added to the IDirect3DDevice9::GetStreamSource and IDirect3DDevice9::SetStreamSource methods. The offset parameter is the number of bytes between the beginning of the stream and the beginning of the vertex data. It is measured in bytes. This enables the pipeline to support stream offsets. To find out if the device supports stream offsets, see the D3DDEVCAPS2_STREAMOFFSET constant in D3DDEVCAPS2.

HRESULT GetStreamSource(
    UINT StreamNumber,
    IDirect3DVertexBuffer9 **ppStreamData,
    UINT *pOffsetInBytes,
    UINT *pStride


Another parameter, a handle, has been added to several methods. They are currently unused and should be set to NULL. The methods affected include:


Multisampling Quality Changes

Previously, there was only the D3DMULTISAMPLE_TYPE enumeration. DirectX 9.0 retains this enumeration and adds the idea of a quality level for each element of the enumeration. The quality level indicates a tradeoff between visual quality and performance by indicating the number of maskable samples (in the sense of D3DRS_MULTISAMPLEMASK).

An application should choose how many maskable samples it requires, and then consult the pQualityLevels value returned by IDirect3D9::CheckDeviceMultiSampleType. If nonzero, this value indicates the number of quality levels the application can pass to the various creation functions (CreateRenderTarget, etc.) through the new MultiSampleQuality argument.

Drivers expose all their multisample schemes as quality levels at D3DMULTISAMPLE_ONE, so if your application doesn't need to mask samples, you can enumerate all available multisampling schemes through this one type. The D3DPRASTERCAPS_STRETCHBLTMULTISAMPLE caps bit has been retired. This bit used to mean that the multisampling method did not support write masks, and could not be toggled on and off between BeginScene and EndScene. Such nonmaskable methods are now exposed through D3DMULTISAMPLE_ONE.

A new caps bit, D3DPRASTERCAPS_MULTISAMPLE_TOGGLABLE, indicates that a device is capable of toggling multisampling on and off altogether, in between BeginScene and EndScene (using the D3DRS_MULTISAMPLEANTIALIAS render state). Any device that doesn't set this flag cannot disable or enable multisampling inside BeginScene/EndScene.

HRESULT CheckDeviceMultiSampleType( 
       UINT Adapter, 
       D3DDEVTYPE DeviceType, 
       D3DFORMAT SurfaceFormat, 
       BOOL Windowed, 
       D3DMULTISAMPLE_TYPE MultiSampleType, 
       DWORD * pQualityLevels);	

There is a different maximum for each number of maskable samples (for example, D3DMULTISAMPLE_4_SAMPLES might have three levels of quality, while _2_SAMPLES might have only one). The number of quality levels is capped to at most eight levels of quality for each number of maskable samples (the driver is not allowed to express more). The quality ranges from zero to (*pQualityLevels-1).

IDirect3DDevice9::CreateRenderTarget and IDirect3DDevice9::CreateDepthStencilSurface were also extended to return the quality level. The quality level of paired methods must match, as well as the multisample type in DirectX 8.x.

ResourceManagerDiscardBytes Changes

ResourceManagerDiscardBytes has been replaced by IDirect3DDevice9::EvictManagedResources. It can evict all resources, both Direct3D and driver resources.

The resource manager is now consulted when a resource (whether managed or nonmanaged) fails creation because there is insufficient video memory. The manager will automatically be asked to free enough resources for the creation to succeed. In DirectX 8.0, this was not an automated process.

SetSoftwareVertexProcessing Changes

An application can create a mixed-mode device to use software and hardware vertex processing.

To switch between the two vertex processing modes in DirectX 8.x, call IDirect3DDevice8::SetRenderState with D3DRS_SOFTWAREVP. This has been replaced with IDirect3DDevice9::SetSoftwareVertexProcessing to ease problems caused by state blocks. This new method is not recorded by state blocks.

Texture Sampler Changes

In DirectX 9.0, there is support for up to 16 texture surfaces in one pass, using the pixel shader 2.0 model, yet the number of texture coordinates remains limited to 8. Some texture stage state is associated with surfaces, some with coordinate sets, some with vertex processing, and some with pixel processing. To manage these differences at compile time, the texture stage state application programming interface (API) is being broken into two. IDirect3DDevice9::SetTextureStageState will still be used for texture coordinate state such as wrap modes, and texture coordinate generation. In addition, IDirect3DDevice9::SetSamplerState will now be used for filtering, tiling, clamping, MIPLOD, etc. This will work for up to 16 samplers.

SetTextureStageState Changes

SetTextureStageState now sets the following states.

D3DTSS_TEXCOORDINDEX, which is a fixed function vertex processing state. If a programmable vertex shader is used, this state is ignored.

The number of texture samplers available to the application is determined by the pixel shader version.

SetSamplerState Changes

SetSamplerState sets the sampler state (including the one used in the tessellator unit to sample displacement maps). These have been renamed with a D3DSAMP_ prefix to enable compile time error detection when porting from DirectX 8.x. The states include D3DSAMP_ADDRESSU, D3DSAMP_ADDRESSV, D3DSAMP_ADDRESSW, D3DSAMP_BORDERCOLOR, D3DSAMP_MAGFILTER, D3DSAMP_MINFILTER, D3DSAMP_MIPFILTER, D3DSAMP_MIPMAPLODBIAS, D3DSAMP_MAXMIPLEVEL, and D3DSAMP_MAXANISOTROPY.

Vertex Declaration Changes

Vertex declarations are now decoupled from vertex shader creation. Vertex declarations now use a Component Object Model (COM) interface.

For DirectX 8.x, vertex declarations are tied to vertex shaders.

For DirectX 9.0, vertex declarations are decoupled from vertex shaders and they can be used with either the fixed function pipeline or with shaders.

Vsync, Intervals, and SwapEffects Changes

Several changes were made to give the user more control over monitor refresh rate, presentation rate, and front buffer vs back buffer drawing.

Windowed Mode

Full-Screen Mode

Timer resolution - the D3DPRESENT_INTERVAL_DEFAULT member of D3DPRESENT_PARAMETERS uses the default system timer resolution whereas the D3DPRESENT_INTERVAL_ONE member of D3DPRESENT_PARAMETERS calls timeBeginPeriod(1) to enhance system timer resolution. This improves the quality of vertical sync, but consumes slightly more processing time. Both parameters attempt to synchronize vertically.

© 2002 Microsoft Corporation. All rights reserved.