IDirect3D9::CheckDeviceFormat Method

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.

Syntax

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 options for the surface. Usage options are any combination of D3DUSAGE and D3DUSAGE_QUERY constants (only a subset of the D3DUSAGE constants are valid for CheckDeviceFormat, see the table on the D3DUSAGE page).

RType

[in] Resource type requested for use with the queried format. Member of D3DRESOURCETYPE.

CheckFormat

[in] Format of the surfaces which may be used, as defined by Usage. Member of D3DFORMAT.

Return Value

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

An application can discover support for autogeneration on a particular format by calling IDirect3D9::CheckDeviceFormat with D3DUSAGE_AUTOGENMIPMAP. The request to automatically generate mipmaps is considered a hint. Therefore, this method can return DDOK_NOAUTOGEN, which is a valid success code, if the only thing that fails is the mipmap generation. If the mipmap automatic generation fails, the application will get a non-mipmapped texture. For more information, see Automatic Generation of Mipmaps.

To check for an off-screen plain surface format, specify Usage = 0 and RType = RTYPE_SURFACE.

A typical use of IDirect3D9::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 IDirect3D9::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,
                                          CheckFormat);

    return SUCCEEDED( hr );
}

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

Another typical use of IDirect3D9::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 IDirect3D9::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,
                                          CheckFormat);

    return SUCCEEDED( hr );
}

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