D3DXCreateContextEx

The D3DXCreateContextEx function initializes the specified device. Note that this is a more advanced initialization function than D3DXCreateContext.

HRESULT D3DXCreateContextEx(
  DWORD deviceIndex,
  DWORD flags,
  HWND hwnd,
  HWND hwndFocus,
  DWORD numColorBits,
  DWORD numAlphaBits,
  DWORD numDepthbits,
  DWORD numStencilBits,
  DWORD numBackBuffers,
  DWORD width,
  DWORD height,
  DWORD refreshRate,
  LPD3DXCONTEXT* ppCtx
); 

Parameters

deviceIndex

An index value specifying the device. Specifying D3DX_DEFAULT for this parameter will initialize the device with the highest acceleration level afforded on the primary surface. For a complete list of possible values see the Hardware Acceleration Level Constants reference topic.

flags

The valid flags are D3DX_CONTEXT_FULLSCREEN, and D3DX_CONTEXT_OFFSCREEN. These flags cannot both be specified. If no flags are specified, the context defaults to windowed mode.

hwnd

The device window. See remarks.

hwndFocus

The window that receives the keyboard messages from the device window. The device window should be a child of the focus window. This parameter is useful for multiple monitor applications. See remarks.

numColorBits

The number of color bits. If D3DX_DEFAULT is passed for windowed mode, the current desktop's color depth is chosen. For full screen mode, D3DX_DEFAULT causes 16 bit color to be used.

numAlphaBits

The number of bits reserved for the alpha channel. If D3DX_DEFAULT is passed, 0 is chosen.

numDepthbits

The number of bits reserved for the depth buffer. If D3DX_DEFAULT is passed, the highest available number of depth bits is chosen. See remarks.

numStencilBits

The number of bits reserved for the stencil buffer. If D3DX_DEFAULT is passed, the highest available number of stencil bits is chosen. See remarks.

numBackBuffers

The number of back buffers, or D3DX_DEFAULT. See remarks.

width

The width of the window, in pixels, or D3DX_DEFAULT. See remarks.

height

The height of the window, in pixels, or D3DX_DEFAULT. See remarks.

refreshRate

The refresh rate. This parameter is ignored for windowed and off-screen modes. D3DX_DEFAULT means to let DirectDraw choose for your application.

ppCtx

The address of a pointer to the context object that is used for rendering on the chosen device.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails, the return value may be one of the following values:

Remarks

If your application is operating in windowed mode, the hwnd parameter must be a valid window. The hwndFocus parameter must be NULL or D3DX_DEFAULT. Also, if either the width or the height parameter is D3DX_DEFAULT, both values default to the dimensions of the client area of hwnd. Specifying D3DX_DEFAULT for numBackBuffers means 1. You must specify one back buffer.

If your application is operating in full-screen mode, either hwnd or hwndFocus must be a valid window (both cannot be NULL or D3DX_DEFAULT). If hwnd is NULL or D3DX_DEFAULT, a default device window will be created as a child of hwndFocus. If either width or height is D3DX_DEFAULT, width defaults to 640 pixels, and height defaults to 480 pixels. Specifying D3DX_DEFAULT for numBackBuffers means 1. Any number of back buffers can be specified.

If your application is operating in off-screen mode, both hwnd and hwndFocus must be NULL or D3DX_DEFAULT. An error is returned if either width or height is D3DX_DEFAULT. Specifying D3DX_DEFAULT for numBackBuffers means 0. You cannot specify additional back buffers.

If both the numDepthBits and numStencilBits parameters are D3DX_DEFAULT, Direct3DX first picks the highest available number of stencil bits. Then, for the chosen number of stencil bits, the highest available number of depth bits are chosen. If only one of the numStencilBits or numDepthBits parameters is D3DX_DEFAULT, the highest number of bits available for that default parameter is chosen out of the formats that support the number of bits requested for the fixed parameter.

As with any function, you should not expect D3DXCreateContextEx to be fail-safe. Supported device capabilities should be used as a guide for choosing parameter values. Inevitably, there will be some combinations of parameters that do not work.

The default projection matrix setup by the D3DXCreateContextEx function is a left-handed perspective projection with a field-of-view (fov) of pi/2 radians.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Version: Requires DirectX 7.0.
  Header: Declared in d3dxcore.h.
  Library: Use d3dx.lib.

See Also

D3DXCreateContext