IDirect3D9::CreateDevice Method

Creates a device to represent the display adapter.

Syntax

HRESULT CreateDevice(      

    UINT Adapter,
    D3DDEVTYPE DeviceType,
    HWND hFocusWindow,
    DWORD BehaviorFlags,
    D3DPRESENT_PARAMETERS *pPresentationParameters,
    IDirect3DDevice9** ppReturnedDeviceInterface
);

Parameters

Adapter

[in] Ordinal number that denotes the display adapter. D3DADAPTER_DEFAULT is always the primary display adapter.

DeviceType

[in] Member of the D3DDEVTYPE enumerated type that denotes the desired device type. If the desired device type is not available, the method will fail.

hFocusWindow

[in] Window handle to which focus belongs for this Microsoft?Direct3D?device. The window specified must be a top-level window for full-screen.

BehaviorFlags

[in] Combination of one or more options that control device creation. For more information, see D3DCREATE.

pPresentationParameters

[in, out] Pointer to a D3DPRESENT_PARAMETERS structure, describing the presentation parameters for the device to be created.

For Microsoft Windows?2000 and Windows XP, the full-screen device display refresh rate is set in the following order.

1. User-specified nonzero ForcedRefreshRate registry key, if supported by the device.
2. Application-specified nonzero refresh rate value in the presentation parameter.
3. Refresh rate of the latest desktop mode, if supported by the device.
4. 75 hertz if supported by the device.
5. 60 hertz if supported by the device.
6. Device default.

An unsupported refresh rate will default to the closest supported refresh rate below it. For example, if the application specifies 63 hertz, 60 hertz will be used. There are no supported refresh rates below 57 hertz.

Calling this method changes the value of several members of D3DPRESENT_PARAMETERS.

• BackBufferCount, BackBufferWidth, and BackBufferHeight = 0 for windowed or full-screen mode.
• BackBufferFormat = D3DFMT_UNKNOWN for windowed mode only. Full-screen mode must specify a format.

If D3DCREATE_ADAPTERGROUP_DEVICE is set, pPresentationParameters is an array. Regardless of the number of heads that exist, only one depth/stencil surface is automatically created.

ppReturnedDeviceInterface

[out, retval] Address of a pointer to the returned IDirect3DDevice9 interface, which represents the created device.

Return Value

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be one of the following values.

D3DERR_INVALIDCALL	The method call is invalid. For example, a method's parameter may have an invalid value.
D3DERR_NOTAVAILABLE	This device does not support the queried technique.
D3DERR_OUTOFVIDEOMEMORY	Direct3D does not have enough display memory to perform the operation.

Remarks

This method returns a fully working device interface, set to the required display mode (or windowed), and allocated with the appropriate back buffers. To begin rendering, the application needs only to create and set a depth buffer (assuming EnableAutoDepthStencil is FALSE in D3DPRESENT_PARAMETERS).

This method should not be run during the handling of WM_CREATE. An application should never pass a window handle to Direct3D while handling WM_CREATE. Any call to create, release, or reset the device must be done using the same thread as the window procedure of the focus window.

Note that D3DCREATE_HARDWARE_VERTEXPROCESSING, D3DCREATE_MIXED_VERTEXPROCESSING, and D3DCREATE_SOFTWARE_VERTEXPROCESSING are mutually exclusive flags, and that at least one of these vertex processing flags must be specified when calling this method.

Back buffers created as part of the device are only lockable if D3DPRESENTFLAG_LOCKABLE_BACKBUFFER is specified in the presentation parameters. (Multisampled back buffers and depth surfaces are never lockable.)

The methods IDirect3DDevice9::Reset, IUnknown::Release, and IDirect3DDevice9::TestCooperativeLevel must be called from the same thread that used this method to create a device.

D3DFMT_UNKNOWN can be specified for the windowed mode back buffer format when calling IDirect3D9::CreateDevice, IDirect3DDevice9::Reset, and IDirect3DDevice9::CreateAdditionalSwapChain. This means the application does not have to query the current desktop format before calling IDirect3D9::CreateDevice for windowed mode. For full-screen mode, the back buffer format must be specified.

See Also

Direct3DCreate9, D3DDEVICE_CREATION_PARAMETERS, IDirect3DDevice9::Reset, Multihead