DXUTCreateDevice

Creates a Direct3D device.

HRESULT DXUTCreateDevice(
  UINT AdapterOrdinal,
  bool bWindowed,
  INT nSuggestedWidth,
  INT nSuggestedHeight,
  LPDXUTCALLBACKISDEVICEACCEPTABLE pCallbackIsDeviceAcceptable,
  LPDXUTCALLBACKMODIFYDEVICESETTINGS pCallbackModifyDeviceSettings,
  void* pUserContext
);

Parameters

AdapterOrdinal

[in] The index of the desired adapter, or D3DADAPTER_DEFAULT for the primary display. The default value is D3DADAPTER_DEFAULT.

bWindowed

[in] If TRUE, the application will start in windowed mode; if FALSE, the application will start in full-screen mode. The default value is TRUE.

nSuggestedWidth

[in] The requested initial width of the application's back buffer. The actual width may be adjusted to fit device and operating system constraints. The default value is 640.

nSuggestedHeight

[in] The requested initial height of the application's back buffer. The actual height may be adjusted to fit device and operating system constraints. The default value is 480. If both nSuggestedWidth and nSuggestedHeight are zero, the dimension of the client area of the window is used.

pCallbackIsDeviceAcceptable

[in] Pointer to a callback function (see LPDXUTCALLBACKISDEVICEACCEPTABLE) which assists in selecting a suitable Direct3D device. If set, the callback function will be called during device enumeration to allow the application to exclude devices from the enumerated list; if NULL, DXUT will add all available devices to the enumerated list. After device enumeration, the framework will use what it determines to be the best device in the enumerated list. The default value is NULL.

pCallbackModifyDeviceSettings

Pointer to a callback function (see LPDXUTCALLBACKMODIFYDEVICESETTINGS)to allow the application to adjust device settings. If the callback function is supplied, it will be called before creating a device.

[in] The callback function is provided with what the framework determines to be the best device settings. The framework allows the application to change device settings; for example, the application can change the behavior flags or the presentation parameters. However, upon creation of the first device, the command-line settings have priority over device setting changes made by the callback function.

If the callback function changes the device settings such that the settings become invalid, the framework will not correct the settings, and device creation will fail.

If the callback function returns false, the framework will not change the device and it will continue to use the current device if one exists. If NULL, the framework will use what it determines to be the best device settings. The default value is NULL.

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

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 Direct3D device for the application; alternately, the application can use the DXUTCreateDeviceFromSettings or handle device creation and pass the desired device to the framework by using the DXUTSetDevice function. If neither DXUTCreateDevice, DXUTCreateDeviceFromSettings, nor DXUTSetDevice have been called before calling DXUTMainLoop, the framework will automatically call DXUTCreateDevice using the default parameter values.

The application can call this method after a device has already been created to change the current device.

Requirements

Header: Declared in Dxut.h.

See Also

DXUTCreateDeviceFromSettings, DXUTMainLoop, DXUTSetDevice