DXUT框架與錯誤處理

Direct3D API的設計使程序能比較容易地處理各種錯誤，盡管大多數Direct3D API函數返回HTRSULT值，但只有一部分函數返回設備錯誤，如D3DERR_DEVICELOST或D3DERR_DRIVERINTERNALERROR。但是通常的Direct3D應用程序使用多種API函數，當傳遞的參數不合要求時，將返回D3DERR_INVALIDCALL。

當開發Direct3D應用程序時，應該檢查所有的API調用是否成功，如果出現一個沒有預測到的失敗調用，應用程序應立即給出通知或記錄該錯誤。使用這種方法，開發人員能很快發現哪些API函數的調用是不正確的。一個正確調用Direct3D API函數的應用程序應能安全地忽略大多數Direct3D API函數的失敗調用，除了一些關鍵性的API函數，如Present()或TestCooperativeLevel()，這些函數返回的錯誤應用程序不能忽略。

通過僅處理最重要的Direct3D錯誤，可以提高運行速度并使應用程序代碼更健壯，因為代碼中需要處理錯誤的地方并不多。對于為數不多的幾個API函數的失敗調用，必須予以適當處理。

框架中錯誤的處理對應Direct3D API中如何設計錯誤的處理，對于各種各樣的錯誤，如丟失媒體（missing media），應用程序能通知用戶并終止。對于每一幀都將調用的大多數API函數，錯誤僅在調試時向開發人員顯示一個錯誤消息框來處理，而在發布時這些錯誤都被忽略了。框架用在DXUT.h中定義的幾個宏來完成這一操作：

#if defined(DEBUG) || defined(_DEBUG)
#ifndef V
#define V(x) { hr = (x); if( FAILED(hr) ) { DXUTTrace( __FILE__, (DWORD)__LINE__, hr, L#x, true ); } }
#endif
#ifndef V_RETURN
#define V_RETURN(x) { hr = (x); if( FAILED(hr) ) { return DXUTTrace( __FILE__, (DWORD)__LINE__, hr, L#x, true ); } }
#endif
#else
#ifndef V
#define V(x) { hr = (x); }
#endif
#ifndef V_RETURN
#define V_RETURN(x) { hr = (x); if( FAILED(hr) ) { return hr; } }
#endif
#endif

當使用vs.net時，如果想跳到出錯代碼所在的行，只需簡單地雙擊調試輸出窗口中輸出的錯誤信息行即可。

選擇最可行的設備

DXUT使用高度靈活的方法從枚舉集合中選擇最好的設備，這個設備枚舉和分級系統可以通過調用函數DXUTFindValidDeviceSettings()獨立于框架使用，該函數的聲明如下：

Finds valid device settings to be used to create a new device.

HRESULT DXUTFindValidDeviceSettings(
  DXUTDeviceSettings * pOut,
  DXUTDeviceSettings * pIn,
  DXUTMatchOptions * pMatchOptions
);

Parameters

pOut

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

pIn

[in] Pointer to a DXUTDeviceSettings structure that contains desired settings for the new device. The default value is NULL.

pMatchOptions

[in] Pointer to a DXUTMatchOptions structure that contains flags describing how to use the device settings when choosing valid output device settings. Optimal device settings will be created based upon the match values in DXUTMatchOptions. If NULL, the function acts as if all members of this structure were DXUTMT_IGNORE_INPUT, meaning that the function will return valid device settings as close as possible to default device settings. See Remarks. The default value is NULL.

Return Values

If the function succeeds, the return value is S_OK. If the function fails, the return value can be one of the error codes in DXUTERR.

Remarks

This function attempts to find valid device settings based upon the input device settings, given by pIn. For each device setting, a match option in the DXUTDeviceSettings structure specifies how the function makes decisions. The function works for both Direct3D 9 and Direct3D 10 device settings.

This function is internally by DXUT used when toggling between full screen and windowed modes, when selecting between HAL and REF device types, and inside DXUTCreateDevice.

DXUTMatchOptions

Describes match options for finding valid device settings using the DXUTFindValidDeviceSettings function. Each member of this structure corresponds to a setting described by the DXUTDeviceSettings structure.

Default values are used when a member is set to DXUTMT_IGNORE_INPUT. See Remarks.

typedef struct DXUTMatchOptions {
    DXUT_MATCH_TYPE eAPIVersion;
    DXUT_MATCH_TYPE eAdapterOrdinal;
    DXUT_MATCH_TYPE eOutput;
    DXUT_MATCH_TYPE eDeviceType;
    DXUT_MATCH_TYPE eWindowed;
    DXUT_MATCH_TYPE eAdapterFormat;
    DXUT_MATCH_TYPE eVertexProcessing;
    DXUT_MATCH_TYPE eResolution;
    DXUT_MATCH_TYPE eBackBufferFormat;
    DXUT_MATCH_TYPE eBackBufferCount;
    DXUT_MATCH_TYPE eMultiSample;
    DXUT_MATCH_TYPE eSwapEffect;
    DXUT_MATCH_TYPE eDepthFormat;
    DXUT_MATCH_TYPE eStencilFormat;
    DXUT_MATCH_TYPE ePresentFlags;
    DXUT_MATCH_TYPE eRefreshRate;
    DXUT_MATCH_TYPE ePresentInterval;
} DXUTMatchOptions, *LPDXUTMatchOptions;

Members

eAPIVersion

Match type for the API version.

eAdapterOrdinal

Match type for the display adapter ordinal.

eOutput

Match type for the adapter output ordinal.

eDeviceType

Match type for the enumerated type of the device. If set to DXUTMT_IGNORE_INPUT, then the default value is D3DDEVTYPE_HAL.

eWindowed

Match type for the windowed or full-screen mode. if set to DXUTMT_IGNORE_INPUT, then the default value is windowed mode (TRUE).

eAdapterFormat

Match type for the adapter surface format. If set to DXUTMT_IGNORE_INPUT, then the default value is the desktop display mode, or D3DFMT_X8R8G8B8 if the desktop display mode is less than 32 bits.

eVertexProcessing

Match type for the vertex processing flags D3DCREATE_HARDWARE_VERTEXPROCESSING, D3DCREATE_MIXED_VERTEXPROCESSING, or D3DCREATE_SOFTWARE_VERTEXPROCESSING. if set to DXUTMT_IGNORE_INPUT, then the default value is D3DCREATE_HARDWARE_VERTEXPROCESSING.

eResolution

Match type for the display mode resolution. if set to DXUTMT_IGNORE_INPUT, then the default value is 640 x 480 pixels for windowed mode, or the desktop resolution for full-screen mode.

eBackBufferFormat

Match type for the back buffer format. if BackBufferFormat is set to DXUTMT_IGNORE_INPUT, then the default value is to match the adapter format.

eBackBufferCount

Match type for the number of back buffers. if BackBufferCount is set to DXUTMT_IGNORE_INPUT, then the default value is 2 for triple buffering.

eMultiSample

Match type for the quality level. if set to DXUTMT_IGNORE_INPUT, then the default value is to disable multisampling (MultiSampleQuality = 0).

eSwapEffect

Match type for the swap effect. if set to DXUTMT_IGNORE_INPUT, then the default value is D3DSWAPEFFECT_DISCARD.

eDepthFormat

Match type for the depth format of the automatic depth-stencil surface that the device will create. If both eDepthFormat and eStencilFormat are set to DXUTMT_IGNORE_INPUT, then the default value is D3DFMT_D16 if the backbuffer format is 16 bits or less, or D3DFMT_D32 otherwise.

eStencilFormat

Match type for the stencil format of the automatic depth-stencil surface that the device will create. if both eDepthFormat and eStencilFormat are set to DXUTMT_IGNORE_INPUT, then the default value is D3DFMT_D16 if the backbuffer format is 16 bits or less, or D3DFMT_D32 otherwise.

ePresentFlags

Match type for the presentation parameters flags. if set to DXUTMT_IGNORE_INPUT, then the default value is D3DPRESENTFLAG_DISCARD_DEPTHSTENCIL.

eRefreshRate

Match type for the rate at which the display adapter refreshes the screen. If set to DXUTMT_IGNORE_INPUT, then the default value is 0, indicating windowed mode.

ePresentInterval

Match type for the presentation interval. if set to DXUTMT_IGNORE_INPUT, then the default value is D3DPRESENT_INTERVAL_IMMEDIATE for windowed mode, or D3DPRESENT_INTERVAL_DEFAULT for full-screen mode.

Remarks

For each member of this structure, match options are specified using the constant values of the DXUT_MATCH_TYPE enumeration, as in the following code example.

matchOptions.eResolution = DXUTMT_CLOSEST_TO_INPUT;

To use default device settings instead, use the DXUTMT_IGNORE_INPUT flag as follows:

matchOptions.eResolution = DXUTMT_IGNORE_INPUT;

DXUT_MATCH_TYPE

Describes how to match input device settings when creating a new device with a function.

typedef enum DXUT_MATCH_TYPE
{
    DXUTMT_IGNORE_INPUT = 0,
    DXUTMT_PRESERVE_INPUT,
    DXUTMT_CLOSEST_TO_INPUT,
} DXUT_MATCH_TYPE, *LPDXUT_MATCH_TYPE;

Constants

DXUTMT_IGNORE_INPUT

Ignore the device setting input, and return a device setting as close as possible to a default device setting.

DXUTMT_PRESERVE_INPUT

Return without changing the device setting that was given as input to the function.

DXUTMT_CLOSEST_TO_INPUT

Return a device setting as close as possible to the device setting that was given as input to the function.

假設想要獲取一個硬件抽象層設備，其后臺緩沖區格式是D3DFMT_A2B10G10R10，如果系統中的硬件抽象層設備不支持這種后臺緩沖區格式，但有一個安裝好的參考設備支持，那么該函數可以使用該參考設備或根據硬件抽象層設備改變后臺緩沖區格式，這都將通過枚舉類型DXUT_MATCH_TYPE來控制如何采用設備格式。