IDirect3D8::CheckDeviceFormat

Determines whether a surface format is available as a specified resource type and can be used as a texture, depth-stencil buffer, or render target, or any combination of the three, on a device representing this adapter.

HRESULT CheckDeviceFormat(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DFORMAT AdapterFormat,
  DWORD Usage,
  D3DRESOURCETYPE RType,
  D3DFORMAT CheckFormat
);

Parameters

Adapter

[in] Ordinal number denoting the display adapter to query. D3DADAPTER_DEFAULT is always the primary display adapter. This method returns D3DERR_INVALIDCALL when this value equals or exceeds the number of display adapters in the system.

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.

Usage

[in] Requested usage for a surface of the CheckFormat. One or more of the following flags can be specified.

D3DUSAGE_DEPTHSTENCIL

Set to indicate that the surface can be used as a depth-stencil surface.

D3DUSAGE_RENDERTARGET

Set to indicate that the surface can be used as a render target. In cases where the RType parameter value unambiguously implies a specific usage, the application can leave the Usage parameter as 0.

RType

[in] A member of the D3DRESOURCETYPE enumerated type, specifying the resource type requested for use with the queried format.

CheckFormat

[in] Member of the D3DFORMAT enumerated type. Indicates the format of the surfaces which may be used, as defined by Usage.

Return Values

If the format is compatible with the specified device for the requested usage, this method returns D3D_OK.

D3DERR_INVALIDCALL is returned if Adapter equals or exceeds the number of display adapters in the system, or if DeviceType is unsupported. This method returns D3DERR_NOTAVAILABLE if the format is not acceptable to the device for this usage.

Remarks

A typical use of CheckDeviceFormat is to verify the existence of a particular depth-stencil surface format. See Selecting a Device for more detail on the enumeration process. The following code fragment shows how you could use CheckDeviceFormat to verify the existence of a depth-stencil format.

BOOL IsDepthFormatExisting( D3DFORMAT DepthFormat, D3DFORMAT AdapterFormat ) {
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          D3DUSAGE_DEPTHSTENCIL,
                                          D3DRTYPE_SURFACE,
                                          DepthFormat);

    return SUCCEEDED( hr );
}

The preceding call will return FALSE if DepthFormat does not exist on the system.

Another typical use of CheckDeviceFormat would be to verify if textures existing in particular surface formats can be rendered, given the current display mode. The following code fragment shows how you could use CheckDeviceFormat to verify that texture formats are compatible with specific back buffer formats.

BOOL IsTextureFormatOk( D3DFORMAT TextureFormat, D3DFORMAT AdapterFormat ) {
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          0,
                                          D3DRTYPE_TEXTURE,
                                          TextureFormat);

    return SUCCEEDED( hr );
}

The preceding call will return FALSE if TextureFormat cannot be used to render textures while the adapter surface format is AdapterFormat.

Requirements

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