天行健 君子當自強而不息

初始化DXUT

使用DXUT框架之前，首先需要初始化DXUT，初始化DXUT可以通過函數DXUTInit()完成：

Initializes DXUT.

 HRESULT DXUTInit( 
   BOOL   bParseCommandLine  , 
   BOOL   bShowMsgBoxOnError  , 
   WCHAR *   strExtraCommandLineParams  , 
   bool   bThreadSafeDXUT 
 ) ;

Parameters

bParseCommandLine

[in] If TRUE, DXUT checks for command-line arguments. The application performs the following actions based upon the entered command-line arguments.

Command-line Argument	Action
-forceapi:#	Forces the application to use the specified Direct3D API version. Fails if the application doesn't support this API or if no device is found.
-adapter:#	Forces the application to use this adapter ordinal. Fails if the adapter ordinal does not exist.
-output:#	Applies to Direct3D 10 only. Forces the application to use a particular output on the adapter. Fails if the output does not exist.
-windowed	Forces the application to start in windowed mode.
-fullscreen	Forces the application to start in full-screen mode.
-forcehal	Forces the application to use a HAL device type. Fails if a HAL device does not exist.
-forceref	Forces the application to use a reference device type. Fails if a reference device does not exist.
-forcehwvp	Applies to Direct3D 9 only. Forces the application to use hardware vertex processing. Fails if the device does not support this mode.
-forcepurehwvp	Applies to Direct3D 9 only. Forces the application to use pure hardware vertex processing. Fails if the device does not support this mode.
-forceswvp	Applies to Direct3D 9 only. Forces the application to use software vertex processing.
-forcevsync:#	If # is 0, then vertical sync is disabled. Otherwise, it is enabled.
-width:#	Forces the application to use the window width #. For full-screen mode, DXUT picks the closest possible supported mode.
-height:#	Forces the application to use the window height #. For full-screen mode, DXUT picks the closest possible supported mode.
-startx:#	For windowed mode, forces the application to use the x-coordinate of the window position to the value of #.
-starty:#	For windowed mode, forces the application to use the y-coordinate of the window position to the value of #.
-constantframetime	Forces the application to into a mode where DXUT reports that a constant amount of time has passed between each frame, where # is the time/frame in seconds. This is useful for such scenarios as rendering an movie that can not render in real time
-quitafterframe:#	Forces the application to quit after frame #.
-noerrormsgboxes	Prevents the display of message boxes generated by DXUT, allowing the application to be run without user interaction.
-nostats	Prevents the display of device and frame statistics by always returning blank strings for DXUTGetDeviceStats and DXUTGetFrameStats.
-automation	This is a simple hint to other components that automation is active. The DXUT GUI uses this to enable UI navigation with keyboard by default.

Command-line arguments take precedence over options set by the application when a Direct3D device is first created, but they are ignored afterward to allow the user to interactively change the settings. The default value of this parameter is TRUE.

bShowMsgBoxOnError

[in] If TRUE, DXUT displays a message box if there is an error condition. The default value of this parameter is TRUE.

strExtraCommandLineParams

[in] A string of extra command parameters that will be parsed in addition to the actual command line. It is recommended that be used sparingly. Most the command line options above can be implemented in the application's ModifyDeviceSettings callback or set by using one of DXUT functions. The default value is NULL.

bThreadSafeDXUT

[in] Controls if DXUT enters a critical section when retrieving or modify internal DXUT state. The default value is false.

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

If this function has not been called before DXUTCreateWindow or DXUTSetWindow, DXUT will automatically call this function using the default parameter values.

通常在WinMain()函數中調用DXUTInit()函數進行DXUT初始化工作，如果程序員沒有調用DXUTInit()函數，則DXUT框架會自動使用默認參數調用該函數。

如果第一個參數 bParseCommandLine 設置為TRUE，則DXUT框架就會使用命令行參數，例如通過下面的命令運行上面的AppFrame.exe：

AppFrame.exe -windowed -width:640 -height:480

DXUT框架會盡量使用上面命令行中設置的窗口寬度和高度。

創建一個窗口

在應用程序中使用Windows API函數創建窗口是一個比較復雜的過程，如果操作有誤，就會導致bug。盡管這對于一個Direct3D程序員來說可能并不起眼，但在每個應用程序中卻都是必須的。而DXUT框架通過函數DXUTCreateWindow()簡化了這個過程，該函數的聲明如下：

Creates the window for the application.

 HRESULT DXUTCreateWindow( 
   CONST const WCHAR *   strWindowTitle  , 
   HINSTANCE   hInstance  , 
   HICON   hIcon  , 
   HMENU   hMenu  , 
   INT   x  , 
   INT   y 
 ) ;

Parameters

strWindowTitle

[in] Title bar caption for the window. The default value is L"Direct3D Window".

hInstance

[in] Handle of the application's instance, or NULL to retrieve the handle of the current module. The default value is NULL.

hIcon

[in] Handle to the application's icon, or NULL to use the first icon embedded in the application's executable. The default value is NULL.

hMenu

[in] Handle to the application's menu resource, or NULL to indicate no menu. The default value is NULL.

x

[in] Horizontal coordinate of the window's upper left corner, in screen coordinates. Using a value of CW_USEDEFAULT allows Windows to choose an appropriate location. The default value is CW_USEDEFAULT.

y

[in] Vertical coordinate of the window's upper left corner, in screen coordinates. Using a value of CW_USEDEFAULT allows Windows to choose an appropriate location. The default value is CW_USEDEFAULT.

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 creates a new window for the application; alternately, the application can handle window creation and pass the desired window handle to DXUT by using the DXUTSetWindow function. If neither DXUTCreateWindow nor DXUTSetWindow has been called before calling a device creation method, DXUT will call DXUTCreateWindow using the default parameter values. The window width and height are set later using the device settings.

All parameters are optional.

If both x and y are CW_USEDEFAULT and a windowed non-primary Direct3D device is created, the window will automatically be moved to the adapter's monitor to ensure maximum performance.

DXUT框架創建的窗口的句柄可以通過DXUTGetHWND()函數來獲取。

如果應用程序要對上面創建的窗口消息做出反應，那么需要使用DXUTSetCallbackMsgProc()來設置一個窗口消息處理函數，該函數聲明如下：

Sets the window message callback function.

 VOID DXUTSetCallbackMsgProc( 
   LPDXUTCALLBACKMSGPROC   pCallbackMsgProc  , 
   void*   pUserContext 
 ) ;

Parameters

pCallbackMsgProc

[in] Pointer to a LPDXUTCALLBACKMSGPROC callback function. If supplied, DXUT will call this function when it receives window messages. If NULL, DXUT will not notify the application about window messages.

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

The LPDXUTCALLBACKMSGPROC callback function allows the application to respond to any Windows messages as it sees fit.

With the use of the LPDXUTCALLBACKMSGPROC pbNoFurtherProcessing parameter, the application can contol the DXUT's level of involvement in processing window messages. If the application sets the pbNoFurtherProcessing parameter to TRUE in the call to LPDXUTCALLBACKMSGPROC , DXUT will not process the message and will immediately return with the value returned by LPDXUTCALLBACKMSGPROC . If the application sets pbNoFurtherProcessing to FALSE, DXUT will handle window management events.

參數 pCallbackMsgProc 指向一個消息處理回調函數，該回調函數聲明如下：

Application-defined function that processes messages from DXUT message pump.

 LRESULT LPDXUTCALLBACKMSGPROC( 
   HWND   hWnd  , 
   UINT   uMsg  , 
   WPARAM   wParam  , 
   LPARAM   lParam  , 
   bool *   pbNoFurtherProcessing  , 
   void*   pUserContext 
 ) ;

Parameters

hWnd

[in] Handle to the window.

uMsg

[in] Specifies the message. See WindowProc for details.

wParam

[in] Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

lParam

[in] Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

pbNoFurtherProcessing

[out] If TRUE, prevents DXUT from futher handling the message.

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

Returns zero if the function has processed window messages successfully; otherwise, returns a nonzero value.

Remarks

This function and its parameters are similar to to the Windows WindowProc function.

With the use of the pbNoFurtherProcessing parameter, the application can control DXUT's level of involvement in processing window messages. If the application sets pbNoFurtherProcessing to TRUE in the call to LPDXUTCALLBACKMSGPROC , DXUT will not process the message and will immediately return with the value returned by LPDXUTCALLBACKMSGPROC . If the application sets pbNoFurtherProcessing to FALSE, DXUT will handle window management events.

在這個回調函數中，因為所有的重要消息都被該框架處理了，所以應用程序可以無需對任何消息做出響應。如果想禁用DXUT框架的消息處理，應用程序可以將 pbNoFurtherProcessing 設為TRUE。但是，使用這個設置時要格外小心，因為它有可能使框架不能正確運行。

使用自己的窗口

如果想要應用程序創建自己的窗口并同DXUT框架一起使用，那么可以創建一個窗口，然后使用函數DXUTSetWindow()為DXUT框架設置自己創建的窗口，該函數聲明如下：

Sets a previously created window for use by DXUT.

 HRESULT DXUTSetWindow( 
   HWND   hWndFocus  , 
   HWND   hWndDeviceFullScreen  , 
   HWND   hWndDeviceWindowed  , 
   BOOL   bHandleMessages 
 ) ;

Parameters

hWndFocus

[in] Handle of the Direct3D focus window. Must not be NULL.

hWndDeviceFullScreen

[in] Handle of the Direct3D device window when in full-screen mode. Must not be NULL.

hWndDeviceWindowed

[in] Handle of the Direct3D device window when in windowed mode. Must not be NULL.

bHandleMessages

[in] If TRUE, DXUT will handle and respond to messages for the window. If FALSE, DXUT will not handle messages for the window, giving the application full responsibility for responding to messages. The default value is TRUE.

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 relies on an existing window object created by the application. Alternately, the application can call DXUTCreateWindow to have DXUT create a window. If neither DXUTCreateWindow nor DXUTSetWindow has been called before calling a device creation method, DXUT will automatically call DXUTCreateWindow using the default parameter values.

The same Window handle may be used for more than one parameter.

這個函數使用了3個窗口句柄參數，但它們通常都設置為同一個窗口句柄。

如果框架創建了窗口，窗口消息將被自動處理，而要讓DXUT框架使用自己創建的窗口，除了為DXUT框架設置窗口之外，還需要向DXUT框架通知窗口接收到的消息，才能使DXUT框架正常運行。應用程序可通過函數DXUTStaticWndProc()將窗口消息從窗口回調函數WindowProc 的內部傳遞給框架，函數DXUTStaticWndProc()的聲明如下：

Processes messages sent to a window.

 LRESULT_CALLBACK DXUTStaticWndProc( 
   HWND   hWnd  , 
   UINT   uMsg  , 
   WPARAM   wParam  , 
   LPARAM   lParam 
 ) ;

Parameters

hWnd

[in] Handle to the window.

uMsg

[in] Specifies the message.

wParam

[in] Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

lParam

[in] Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

Return Values

If the function has processed window messages successfully, returns zero; otherwise, returns a nonzero value.

Remarks

This method does not normally need to be called. It is useful only when the application use DXUTSetWindow with bHandleMessages set to FALSE but still wants DXUT to assist with handling Windows messages. If this is the case, this function can be called from inside the application's window procedure, or it can be used directly as the window procedure.