Edit

IDirect3D9::CheckDepthStencilMatch method (d3d9.h)

  • Article

Determines whether a depth-stencil format is compatible with a render-target format in a particular display mode.

Syntax

HRESULT CheckDepthStencilMatch(
  [in] UINT       Adapter,
  [in] D3DDEVTYPE DeviceType,
  [in] D3DFORMAT  AdapterFormat,
  [in] D3DFORMAT  RenderTargetFormat,
  [in] D3DFORMAT  DepthStencilFormat
);

Parameters

[in] Adapter

Type: UINT

Ordinal number denoting the display adapter to query. D3DADAPTER_DEFAULT is always the primary display adapter.

[in] DeviceType

Type: D3DDEVTYPE

Member of the D3DDEVTYPE enumerated type, identifying the device type.

[in] AdapterFormat

Type: D3DFORMAT

Member of the D3DFORMAT enumerated type, identifying the format of the display mode into which the adapter will be placed.

[in] RenderTargetFormat

Type: D3DFORMAT

Member of the D3DFORMAT enumerated type, identifying the format of the render-target surface to be tested.

[in] DepthStencilFormat

Type: D3DFORMAT

Member of the D3DFORMAT enumerated type, identifying the format of the depth-stencil surface to be tested.

Return value

Type: HRESULT

If the depth-stencil format is compatible with the render-target format in the display mode, this method returns D3D_OK. D3DERR_INVALIDCALL can be returned if one or more of the parameters is invalid. If a depth-stencil format is not compatible with the render target in the display mode, then this method returns D3DERR_NOTAVAILABLE.

Remarks

This method is provided to enable applications to work with hardware requiring that certain depth formats can only work with certain render-target formats.

The behavior of this method has been changed for DirectX 8.1. This method now pays attention to the D24x8 and D32 depth-stencil formats. The previous version assumed that these formats would always be usable with 32- or 16-bit render targets. This method will now return D3D_OK for these formats only if the device is capable of mixed-depth operations.

The following code fragment shows how you could use CheckDeviceFormat to validate a depth stencil format.


BOOL IsDepthFormatOk(D3DFORMAT DepthFormat, 
                          D3DFORMAT AdapterFormat, 
                          D3DFORMAT BackBufferFormat)
{
    
    // Verify that the depth format exists
    HRESULT hr = pD3D->CheckDeviceFormat(D3DADAPTER_DEFAULT,
                                         D3DDEVTYPE_HAL,
                                         AdapterFormat,
                                         D3DUSAGE_DEPTHSTENCIL,
                                         D3DRTYPE_SURFACE,
                                         DepthFormat);
    
    if(FAILED(hr)) return FALSE;
    
    // Verify that the depth format is compatible
    hr = pD3D->CheckDepthStencilMatch(D3DADAPTER_DEFAULT,
                                      D3DDEVTYPE_HAL,
                                      AdapterFormat,
                                      BackBufferFormat,
                                      DepthFormat);
    
    return SUCCEEDED(hr);
    
}

The preceding call will return FALSE if DepthFormat cannot be used in conjunction with AdapterFormat and BackBufferFormat.

Requirements

Requirement Value
Target Platform Windows
Header d3d9.h (include D3D9.h)
Library D3D9.lib

See also

IDirect3D9