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

object.CheckDeviceFormat( _ 
    Adapter As Long, _ 
    DeviceType As  CONST_D3DDEVTYPE, _ 
    AdapterFormat As CONST_D3DFORMAT, _ 
    Usage As Long, _ 
    RType As CONST_D3DRESOURCETYPE, _ 
    CheckFormat As CONST_D3DFORMAT) As Long

Parts

object

Object expression that resolves to a Direct3D8 object.

Adapter

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

Member of the CONST_D3DDEVTYPE enumeration, identifying the device type.

AdapterFormat

Member of the CONST_D3DFORMAT enumeration, identifying the format of the display mode into which the adapter will be placed.

Usage

Requested usage for a surface of the CheckFormat. One or more of the following flags defined by the CONST_D3DUSAGEFLAGS enumeration 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

A member of the CONST_D3DRESOURCETYPE enumeration, specifying the resource type requested for use with the queried format.

CheckFormat

Member of the CONST_D3DFORMAT enumeration. Indicates the format of the surfaces that 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.

Error Codes

Err.Number is not set for this method.

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. Another typical use of CheckDeviceFormat would be to verify if textures existing in particular surface formats can be rendered, given the current display mode.

Function DoesDepthFormatExist(DepthFormat As CONST_D3DFORMAT, AdapterFormat As CONST_D3DFORMAT) As Boolean

   Dim Check As Long
   Dim D3D As Direct3D8

   'we assume the D3D object has been created and initialized
   Check = D3D.CheckDeviceFormat(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, AdapterFormat, _ 
                                 D3DUSAGE_DEPTHSTENCIL, D3DRTYPE_SURFACE, DepthFormat)
   If (Check >= 0) Then
       DoesDepthFormatExist= 1
   Else
      DoesDepthFormatExist= 0
   End If

End Function

The preceding function call returns 0 (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.

Function IsTextureFormatOk(TextureFormat As D3DFORMAT ,AdapterFormat As D3DFORMAT ) As Boolean
   Dim Check As Long
   Dim D3D As Direct3D8
   
   Check = D3D.CheckDeviceFormat( D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, AdapterFormat, _ 
                                  0, D3DRTYPE_TEXTURE, TextureFormat)

   If (Check >= 0) Then
      IsTextureFormatOk = 1
   Else
      IsTextureFormatOk = 0
   End If

End Function

The preceding call returns 0 (False) if TextureFormat cannot be used to render textures while the adapter surface format is AdapterFormat.