DXUT框架與錯誤處理

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

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

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

框架中錯誤的處理對應(yīng)Direct3D API中如何設(shè)計錯誤的處理，對于各種各樣的錯誤，如丟失媒體（missing media），應(yīng)用程序能通知用戶并終止。對于每一幀都將調(diào)用的大多數(shù)API函數(shù)，錯誤僅在調(diào)試時向開發(fā)人員顯示一個錯誤消息框來處理，而在發(fā)布時這些錯誤都被忽略了。框架用在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

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

選擇最可行的設(shè)備

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

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.

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