IDirect3D8::CheckDepthStencilMatch

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

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

Parameters

Adapter

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

DeviceType

[in] Member of the D3DDEVTYPE enumerated type, identifying the device type.

AdapterFormat

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

RenderTargetFormat

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

DepthStencilFormat

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

Return Values

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 allows applications to work with hardware that requires certain depth formats for a given render target format. The following code fragment shows how to use CheckDeviceFormat to validate a depth stencil format.

The behavior of this method has been changed for Microsoft® 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 useable 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

  Header: Declared in D3d8.h.
  Import Library: Use D3d8.lib.