DXUT框架剖析（3）

初始化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.