Edit

Share via

IDirect3D9::CheckDeviceFormat method (d3d9.h)

  • Article

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(
  [in] UINT            Adapter,
  [in] D3DDEVTYPE      DeviceType,
  [in] D3DFORMAT       AdapterFormat,
  [in] DWORD           Usage,
  [in] D3DRESOURCETYPE RType,
  [in] D3DFORMAT       CheckFormat
);

Parameters

[in] Adapter

Type: UINT

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.

[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] Usage

Type: DWORD

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).

[in] RType

Type: D3DRESOURCETYPE

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

[in] CheckFormat

Type: D3DFORMAT

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

Return value

Type: HRESULT

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.

D3DERR_NOTAVAILABLE is returned if the format is not acceptable to the device for this usage.

Remarks

Here are some examples using CheckDeviceFormat to check for hardware support of:

  • An off-screen plain surface format - Specify Usage = 0 and RType = D3DRTYPE_SURFACE.
  • A depth-stencil format - The following snippet tests for the passed in 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 );
}

    See Selecting a Device (Direct3D 9) for more detail on the enumeration process.

  • Can this texture be rendered in a particular format - Given the current display mode, this example shows how to verify that the texture format is compatible with the specific back-buffer format: 
    
BOOL IsTextureFormatOk( D3DFORMAT TextureFormat, D3DFORMAT AdapterFormat ) 
{
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          0,
                                          D3DRTYPE_TEXTURE,
                                          TextureFormat);
    
    return SUCCEEDED( hr );
}
  • Alpha blending in a pixel shader - Set Usage to D3DUSAGE_QUERY_POSTPIXELSHADER_BLENDING. Expect this to fail for all floating-point render targets.
  • Autogeneration of mipmaps - Set Usage to D3DUSAGE_AUTOGENMIPMAP. If the mipmap automatic generation fails, the application will get a non-mipmapped texture. Calling this method is considered a hint, so this method can return D3DOK_NOAUTOGEN (a valid success code) if the only thing that fails is the mipmap generation. For more information about mipmap generation, see Automatic Generation of Mipmaps (Direct3D 9).
When migrating code from Direct3D 9 to Direct3D 10, the Direct3D 10 equivalent to CheckDeviceFormat is CheckFormatSupport.

Requirements

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

See also

IDirect3D9