Dxut Programming Guide (4): using devices through dxut

Use a device through dxut

The creation of DirectX devices has been improved in dxut. You can allow your applications to directly create devices, while other features provided by the framework are still available.
Create a device

Select the best device settings
Modify available device settings
Downgrading to software vertex Processing
Use your own device

Create a device

Typically, you will create a device using the standard direct3d Method
Hresult createdevice (
Uint adapter,
D3ddevtype devicetype,
Hwnd hfocuswindow,
DWORD behaviorflags,
D3dpresent_parameters * ppresentationparameters,
Idirect3ddevice9 ** ppreturneddeviceinterface
);
This method requires a valid adapter, device type (Hal or ref), window handle, behavior sign (software/hardware vertex processing and other driver flags), and presentation parameter (Presentation parameters ). in addition, the d3dpresent_parameter struct has a large number of Members specifying the backup buffer, multiple sampling settings, switching effect, window mode, deep template buffer, refreshing rate, presentation interval, and presentation flag.
Selecting valid settings for all these parameters is challenging. The framework simplifies the selection process through the dxutcreatedevice function.
Hresult dxutcreatedevice (
Uint adapterordinal = d3dadapter_default,
Bool bwindowed = true,
Int nsuggestedwidth = 640,
Int nsuggestedheight = 480,
Lpdxutcallbackisdeviceacceptable pcallbackisdeviceacceptable = NULL,
Lpdxutcallbackmodifydeviceset?pcallbackmodifydeviceset=null
);
The most basic usage is to use all the default parameter calls:
Dxutcreatedevice ();
Use the default settings to create a device that is available in most cases. The default settings are as follows:

Direct3d creation flag	Description	Default Value fromDxutcreatedevice
Adapterformat parameter of checkdeviceformat	Adapter surface format.	Desktop display mode, or d3dfmt_x8r8g8b8 If the desktop display mode is less than 32 bits.
Adapter parameterIdirect3d9: createdevice	Display Adapter ordinal.	D3dadapter_default
D3dpresent_parameters . Backbuffercount	Number of back buffers.	2, indicating triple buffering.
D3dpresent_parameters . Backbufferformat	Back buffer format.	Desktop display mode, orD3dfmt_x8r8g8b8 If the desktop display mode is less than 32 bits.
D3dpresent_parameters . Autodepthstencilformat	Depth format of the automatic depth-stencel surface that the device will create.	D3dfmt_d16 If the backbuffer format is 16 bits or less, orD3dfmt_d32 Otherwise.
The devicetype parameterIdirect3d9: createdevice	Enumerated type of the device.	D3ddevtype_hal if available, otherwise d3ddevtype_ref or failure code if neither is available.
D3dpresent_parameters . Multisamplequality	Quality level.	Multisamplequality = 0, indicating multisampling is disabled.
D3dpresent_parameters . Flags	Presentation parameters flags.	D3dpresentflag_discard_depthstencel
D3dpresent_parameters . Presentationinterval	Presentation interval.	D3dpresent_interval_immediate For each wed mode, orD3dpresent_interval_default For full-screen mode.
D3dpresent_parameters . Fullscreen_refreshrateinhz	Rate at which the display adapter refreshes the screen.	0, indicating has wed mode.
D3dpresent_parameters . Backbufferwidth and. backbufferheight	Display Mode resolution.	640x480 pixels for each wed mode, or the desktop resolution for full-screen mode.
D3dpresent_parameters . Autodepthstencilformat	Stencel format of the automatic depth-stencel surface that the device will create.	D3dfmt_d16 If the backbuffer format is 16 bits or less, orD3dfmt_d32 Otherwise.
D3dpresent_parameters . Swapeffect	Swap effect.	D3dswapeffect_discard
Behaviorflags parameterIdirect3d9: createdevice	Vertex processing flags.	D3dcreate_hardware_vertexprocessing If supported, otherwiseD3dcreate_software_vertexprocessing .
D3dpresent_parameters . Shortwed	Invalid wed or full-screen mode.	True, indicating has wed mode.
Hfocuswindow parameterCreatedevice	Handle to the created window (see using application windows with dxut ).	Hwndfocus parameter of dxutsetwindow
D3dpresent_parameters . Hdevicewindow	Handle to the device window.	Hwnddevicefullscreen or hwnddevicew.wed parametersDxutsetwindow
D3dpresent_parameters . Enableautodepthstencel	Depth-stencel buffer creation flag.	True.

Applications can pass parameters to createdevice to control more device creation, which is better than the default method. For example, you can use the nsuggestedwidth and nsuggestedheight parameters to change the window size.
Dxutcreatedevice (
D3dadapter_default,
False,
1024,
786,
Null,
Null,
Null
);
For more control, the application can use these two optional callback functions, lpdxutcallbackisdeviceacceptable and lpdxutcallbackmodifydevicesettings.

Select the best device settings

You can use the isdeviceacceptable callback function to help the framework select the best device settings for your application, as shown in the following code:
Bool callback isdeviceacceptable (
D3dcaps9 * pcaps,
D3dformat adapterformat,
D3dformat backbufferformat,
Bool bw.wed,
Void * pusercontext)
{
// Todo: Return true for acceptable settings and false otherwise.
Return true;
}
The callback function model is based on the lpdxutcallbackisdeviceacceptable prototype (This callback function is modeled on the prototype lpdxutcallbackisdeviceacceptable). The Framework calls this function once for a valid combination of the following five settings:
D3ddevtype devicetype;
Uint adapterordinal;
D3dformat adapterformat;
D3dformat backbufferformat;
Bool implements wed;
Note that the adapter serial number and device type are not directly passed in the callback function, but are members of the d3dcaps9 struct respectively.
Through this callback function, the application can reject any combinations that it does not support or does not want. For example, an application can use the following code to reject the 16bits backup buffer format and all devices that at least do not support the pixel shader ps_2_0:
Bool callback isdeviceacceptable (
D3dcaps9 * pcaps,
D3dformat adapterformat,
D3dformat backbufferformat,
Bool bw.wed)
{
If (pcaps-> pixelshaderversion <d3dps_version (2, 0 ))
Return false;
If (backbufferformat = d3dfmt_x1r5g5b5 | backbufferformat = d3dfmt_r5g6b5)
Return false;
Return true;
}

After calling the callback function for each unique combination, the Framework arranges the remaining available combinations and selects the best among them. The ranking is as follows:
D3ddevtype_hal to obtain hardware acceleration
If the application is displayed in full screen mode, the framework tends to use the adapter format that matches the desktop format, so that you can quickly switch between full screen and window. The exception is that if the desktop display mode is smaller than 32 bits, the framework tends to be d3dfmt_x8r8g8b8.
Matching the backup buffer format of the adapter format
After these high-ranking combinations are selected, to create a device, the behavior flag and rendering parameters are still required. For these settings, direct3d uses the default values in the preceding table.

Modify available device settings

The application can modify the available settings of the framework by using the second optional callback function. This function is modifydevicesettings:
Bool callback modifydevicesettings (
Dxutdevicesettings * pdevicesettings,
Const d3dcaps9 * pcaps)
{
// Todo: Include device creation requirements here.
// Returns the created device. returns false to keep the current setting.
Return true;
}
This function is based on the prototype lpdxutcallbackmodifydevicesettings. The dxutdevicesettings struct is defined by the framework:
Struct dxutdevicesettings
{
Uint adapterordinal;
D3ddevtype devicetype;
D3dformat adapterformat;
DWORD behaviorflags;
D3dpresent_parameters pp;
};

This struct contains all the things required to create a device. Except the window handle, it is assumed to be the handle of the window created before. The framework fills in the struct with valid data and allows the application to change the device creation options through the modifydevicesettings callback function.
In this callback function, the application can change the behavior flag and rendering parameters in the dxutdevicesettings struct, and even anything else in the struct. If the application does not change anything in the callback function, the device is successfully created. However, any changes to the device creation settings must be supported by the device. Otherwise, the device creation may fail.
For example, if an application requires a depth template buffer format of d3dfmt_d24s8, you must verify that the device supports the buffer format, as shown in the following code:
Bool callback modifydevicesettings (
Dxutdevicesettings * pdevicesettings,
Const d3dcaps9 * pcaps)
{
Idirect3d9 * pd3d = dxutgetd3dobject ();
If (succeeded (pd3d-> checkdeviceformat (
Pdevicesettings-> adapterordinal,
Pdevicesetetype-> devicetype,
Pdevicesettings-> adapterformat,
D3dusage_depthstencel,
D3drtype_surface,
D3dfmt_d24s8 )))
{
If (succeeded (pd3d-> checkdepthstencilmatch (
Pdevicesettings-> adapterordinal,
Pdevicesetetype-> devicetype,
Pdevicesettings-> adapterformat,
Pdevicesettings-> pp. backbufferformat,
D3dfmt_d24s8 )))
{
Pdevicesettings-> pp. autodepthstencilformat = d3dfmt_d24s8;
}
}

Return true;
}

The candidate scheme is that the callback function can use the framework's cd3denumeration object to verify if d3dfmt_d24s8 is supported:
Bool callback modifydevicesettings (
Dxutdevicesettings * pdevicesettings,
Const d3dcaps9 * pcaps)
{
Cd3denumeration * penum = dxutgetenumeration ();
Cd3denumdevicesettingscombo * pcombo;
 
Pcombo = penum-> getdevicesettingscombo (pdevicesettings );
 
If (pcombo-> depthstencilformatlist. Contains (d3dfmt_d24s8 ))
Pdevicesettings-> pp. autodepthstencilformat = d3dfmt_d24s8;

Return true;
}

After the application modifies the device settings, the framework creates a device with the new settings.
The modifydevicesettings callback function returns a bool value for the update in the DirectX listen l 2005 SDK. If the application returns true, the Framework continues normal device creation. If the return value is false, the device is not changed and the current device is kept. If one already exists. This allows the application to reject requests from the framework that change the device to an unusable device. For example, in the default configuration of multiple monitors, dragging a window between monitors will cause the frame to change the device. However, if the application cannot use other devices, it should be able to refuse to change and continue to use the current device.

Software vertex Processing

If you set a direct3d device to a hardware that supports pixel processing but does not support vertex processing, you need to change the behavior flag. To ensure correct downgrading to the software vertex processing, you cannot reject a device based on the vertex coloring tool version in the isdeviceacceptable callback function, and ensure that the behavior signs are correctly adjusted in the modifydevicesettings callback function. Here is an example to demonstrate how to do these things.
Bool callback modifydevicesettings (dxutdevicesettings * pdevicesettings,
Const d3dcaps9 * pcaps)
{
// 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_hwtransformanlight) = 0 |
Pcaps-> vertexshaderversion <d3dvs_version (1, 1 ))
{
Pdevicesettings-> behaviorflags = d3dcreate_software_vertexprocessing;
}

Else
{
Pdevicesettings-> behaviorflags = d3dcreate_hardware_vertexprocessing;
}

Return true;
}

Use your own device

You do not have to rely on the framework to create direct3d devices. The application can create a device and pass it to the framework. Just as the application can override the window creation settings of the framework. Simply use the settings you want to create a device, and then call the dxutsetdevice function to render the framework on your device.
NOTE: If an application creates a device that does not rely on the framework, the application must release the device interface through cleanup after the main loop is executed.
For more information, see
Use dxut to select more advanced devices