DXUT框架剖析（5）

修改可用的设备

应用程序可以通过DXUTSetCallbackDeviceChanging()设置回调函数来修改Direct3D设备的创建设置：

Sets a callback function that allow the application to change the device settings before the device is created.

VOID DXUTSetCallbackDeviceChanging(
  LPDXUTCALLBACKMODIFYDEVICESETTINGS pCallbackModifyDeviceSettings,
  void* pUserContext
);

Parameters

pCallbackModifyDeviceSettings

[in] Pointer to a LPDXUTCALLBACKMODIFYDEVICESETTINGS callback function. If the callback function is supplied, it will be called before the Direct3D device is created. If NULL, DXUT will not notify the application about device changes.

pUserContext

[in] Pointer to a user-defined value which is passed to the callback function. Typically used by an application to pass a pointer to a data structure that provides context information for the callback function. The default value is NULL

Return Values

No return value.

Remarks

Before a device is created by DXUT, the LPDXUTCALLBACKMODIFYDEVICESETTINGS callback will be called to allow the application to examine or change the device settings before the device is created. This allows an application to modify the device creation settings as it sees fit.

This callback also allows applications to reject changing the device altogether. Returning false from inside this callback will notify DXUT to keep using the current device instead of changing to the new device.

LPDXUTCALLBACKMODIFYDEVICESETTINGS

Application-defined callback function, called by DXUT to allow changes in device settings before the device is created.

bool LPDXUTCALLBACKMODIFYDEVICESETTINGS(
  DXUTDeviceSettings * pDeviceSettings,
  void* pUserContext
);

Parameters

pDeviceSettings

[in] Pointer to a DXUTDeviceSettings structure that contains the settings for the new device.

pUserContext

[in] Pointer to a user-defined value which is passed to the callback function. Typically used by an application to pass a pointer to a data structure that provides context information for the callback function. The default value is NULL

Return Values

Program the application to return true to continue creating the device. If not, the application should return false to continue using the current device if one exists.

Remarks

Before a device is created by DXUT, the LPDXUTCALLBACKMODIFYDEVICESETTINGS callback will be called to allow the application to examine or change the device settings before the device is created. This allows an application to modify the device creation settings as it sees fit.

This callback also allows applications to reject changing the device altogether. Returning false from inside this callback will notify DXUT to keep using the current device instead of changing to the new device.

Anything in pDeviceSettings can be changed by the application. DXUT will not prevent the failure of device creation caused by changes to device settings.

DXUTDeviceSettings

A union of settings describing how to create the Direct3D 9 or Direct3D 10 device.

typedef struct DXUTDeviceSettings {
    DXUTDeviceVersion ver;
    union {
        DXUTD3D9DeviceSettings d3d9;
        DXUTD3D10DeviceSettings d3d10;
    };
} DXUTDeviceSettings, *LPDXUTDeviceSettings;

Members

ver

Indicates whether the settings structure is for a Direct3D 9 or Direct3D 10 device.

d3d9

Device settings for Direct3D 9 device. Only valid if ver is DXUT_D3D9_DEVICE.

d3d10

Device settings for Direct3D 10 device. Only valid if ver is DXUT_D3D10_DEVICE.

Remarks

The DXUTDeviceSettings can only describe a single device because the DXUTD3D9DeviceSettings and DXUTD3D10DeviceSettings member variables are unioned together. The DXUTDeviceVersion indicates which of these structures is valid.

DXUTD3D9DeviceSettings

Describes the settings used to create a Direct3D 9 device.

typedef struct DXUTD3D9DeviceSettings {
    UINT AdapterOrdinal;
    D3DDEVTYPE DeviceType;
    D3DFORMAT AdapterFormat;
    DWORD BehaviorFlags;
    D3DPRESENT_PARAMETERS pp;
} DXUTD3D9DeviceSettings, *LPDXUTD3D9DeviceSettings;

Members

AdapterOrdinal

Ordinal number that denotes the display adapter.

DeviceType

Enumerated type of the device.

AdapterFormat

Adapter surface format.

BehaviorFlags

Behavior flags. This member can be a combination of one or more of the D3DCREATE values.

pp

Presentation parameters structure.

DXUT fills this structure with valid values, and then passes the structure to the callback function where the application can modify it. Be sure to validate any changes your application makes in this callback function. Here is an example that changes the depth-stencil format.

bool CALLBACK ModifyDeviceSettings( 
    DXUTDeviceSettings* pDeviceSettings, 
    void* pUserContext )
{
    if( pDeviceSettings->ver == DXUT_D3D9_DEVICE )
    {
        IDirect3D9* pD3D = DXUTGetD3DObject();

        if( SUCCEEDED( pD3D->CheckDeviceFormat(
    	                   pDeviceSettings->d3d9.AdapterOrdinal, pDeviceSettings->d3d9.DeviceType,
    	                   pDeviceSettings->d3d9.AdapterFormat, D3DUSAGE_DEPTHSTENCIL,
    	                   D3DRTYPE_SURFACE, D3DFMT_D24S8 ) ) )
        {
            if( SUCCEEDED( pD3D->CheckDepthStencilMatch(
                               pDeviceSettings->d3d9.AdapterOrdinal, pDeviceSettings->d3d9.DeviceType,
                               pDeviceSettings->d3d9.AdapterFormat, pDeviceSettings->d3d9.pp.BackBufferFormat,
                               D3DFMT_D24S8 ) ) )
            {
                pDeviceSettings->d3d9.pp.AutoDepthStencilFormat = D3DFMT_D24S8;
            }
        }
    }
    
    return true;
}

如果应用程序需要的深度模板格式是D3DFMT_D24S8，那么程序需要确定设备支持它。

回调函数ModifyDeviceSettings()返回一个布尔值，如果应用程序返回TRUE，DXUT框架继续像在正常情况下那样进行设备创建。如果返回FALSE，框架不能改变设备，如果已有一个设备，则继续使用当前设备。如果框架提出的请求是改变到一个应用程序不能使用的设备，应用程序可以拒绝该请求。例如，在一个多显示器配置中，默认情况下在显示器之间拖动窗口将使框架改变设备。但如果应用程序不能使用其他设备，它就必须拒绝这种改变并继续使用当前设备。

降级到软件顶点处理

Be careful if your hardware supports pixel processing (transforms and lighting) but does not support vertex processing. One common mistake is to reject devices based on the vertex shader version in the (LPDXUTCALLBACKISD3D9DEVICEACCEPTABLE or LPDXUTCALLBACKISD3D10DEVICEACCEPTABLE) callback functions. The correct solution is to implement the checking in the ModifyDeviceSettings callback function as shown here.

bool CALLBACK ModifyDeviceSettings( DXUTDeviceSettings* pDeviceSettings, 
                                    void* pUserContext )
{
    if( pDeviceSettings->ver == DXUT_D3D9_DEVICE )
    {
        D3DCAPS9 caps;
        DXUTGetD3D9DeviceCaps( pDeviceSettings, &caps );
    
        // If device doesn't support HW T&L or doesn't support 1.1 vertex 
        // shaders in HW, then switch to SWVP.
        if( (pCaps->DevCaps & D3DDEVCAPS_HWTRANSFORMANDLIGHT) == 0 ||
             pCaps->VertexShaderVersion < D3DVS_VERSION(1,1) )
        {
            pDeviceSettings->d3d9.BehaviorFlags = D3DCREATE_SOFTWARE_VERTEXPROCESSING;
        }
    
        else
        {
            pDeviceSettings->d3d9.BehaviorFlags = D3DCREATE_HARDWARE_VERTEXPROCESSING;
        }
    }
    
    return true; 
}