D3DPRESENT_PARAMETERS

Article
06/30/2006

This structure describes the presentation parameters.

typedef struct _D3DPRESENT_PARAMETERS_ {
  UINT BackBufferWidth;
  UINT BackBufferHeight;
  D3DFORMAT BackBufferFormat;
  UINT BackBufferCount;
  D3DMULTISAMPLE_TYPE MultiSampleType;
  D3DSWAPEFFECT SwapEffect;
  HWND hDeviceWindow;
  BOOL Windowed;
  BOOL EnableAutoDepthStencil;
  D3DFORMAT AutoDepthStencilFormat;
  DWORD Flags;
  UINT FullScreen_RefreshRateInHz;
  UINT FullScreen_PresentationInterval;
} D3DPRESENT_PARAMETERS;

Members

BackBufferWidth and BackBufferHeight
Width and height of the new swap chain's back buffers, in pixels. If Windowed is FALSE (the presentation is full-screen), then these values must equal the width and height of one of the enumerated display modes found through IDirect3D8::EnumAdapterModes. If Windowed is TRUE and either of these values is zero, then the corresponding dimension of the client area of the hDeviceWindow (or the focus window, if hDeviceWindow is NULL) is taken.
BackBufferFormat
Member of the D3DFORMAT enumerated type. This value must be one of the render target formats as validated by IDirect3D8::CheckDeviceType.

If Windowed is set to TRUE, then BackBufferFormat must be set to match the format of the current display mode. Use IDirect3DDevice8::GetDisplayMode to obtain the current format.
BackBufferCount
This value can be 0, 1, 2 or 3. Note that 0 is treated as 1. If the number of back buffers cannot be created, the run time will fail the method call and fill this value with the number of back buffers that could be created. As a result, an application can call the method twice with the same D3DPRESENT_PARAMETERS structure and expect it to work the second time.

One back buffer is considered the minimum number of back buffers. The method call fails if 1 back buffer cannot be created. The value of BackBufferCount influences what set of swap effects are allowed. Specifically, any D3DSWAPEFFECT_COPY swap effect requires that there be exactly one back buffer.
MultiSampleType
Member of the D3DMULTISAMPLE_TYPE enumerated type. The value must be D3DMULTISAMPLE_NONE unless SwapEffect has been set to D3DSWAPEFFECT_DISCARD. Multisampling is supported only if the swap effect is D3DSWAPEFFECT_DISCARD.
SwapEffect
Member of the D3DSWAPEFFECT enumerated type. The run time will guarantee the implied semantics concerning buffer swap behavior. So if Windowed is TRUE and SwapEffect is set to D3DSWAPEFFECT_FLIP, then the run time will create one extra back buffer, and copy whichever becomes the front buffer at presentation time.

D3DSWAPEFFECT_COPY and D3DSWAPEFFECT_COPY_VSYNC require that BackBufferCount be set to 1.

D3DSWAPEFFECT_DISCARD will be enforced in the debug run time by filling any buffer with noise after it is presented.
hDeviceWindow
If full-screen, this is the cover window. If windowed, this will be the default target window for IDirect3DDevice8::Present. If this value is NULL, the focus window will be taken. For applications that use multiple full-screen devices, such as a multimonitor system, exactly one device should use the focus window as the device window. All other devices should have unique device windows. Otherwise, behavior is undefined and applications will not work as expected.

Note that no attempt is made by the run time to reflect user changes in window size. The back buffer is not implicitly reset when this window is reset. However, the Present method does automatically track window position changes.
Windowed
TRUE if the application runs windowed, FALSE if the application runs full-screen.
EnableAutoDepthStencil
If this value is TRUE, Microsoft® Direct3D® will manage depth buffers for the application. The device will create a depth-stencil buffer when it is created. The depth-stencil buffer will be automatically set as the render target of the device. When the device is reset, the depth-stencil buffer will be automatically destroyed and recreated in the new size.

If EnableAutoDepthStencil is TRUE, then AutoDepthStencilFormat must be a valid depth-stencil format.
AutoDepthStencilFormat
Member of the D3DFORMAT enumerated type. The format of the automatic depth-stencil surface that the device will create. This member is ignored unless EnableAutoDepthStencil is TRUE.

Flags
This member can be set to 0, or to the following flag.

Flag	Description
D3DPRESENTFLAG_LOCKABLE_BACKBUFFER	Set this flag if the application requires the ability to lock the back-buffer directly. Note that back buffers are not lockable unless the application specifies D3DPRESENTFLAG_LOCKABLE_BACKBUFFER when calling IDirect3D8::CreateDevice or IDirect3DDevice8::Reset. Lockable back buffers incur a performance cost on some graphics hardware configurations. Performing a lock operation (or using IDirect3DDevice8::CopyRects to read/write) on the lockable back-buffer decreases performance on many cards. In this case, consider using textured triangles to move data to the back buffer.

D3DPRESENTFLAG_LOCKABLE_BACKBUFFER

Set this flag if the application requires the ability to lock the back-buffer directly. Note that back buffers are not lockable unless the application specifies D3DPRESENTFLAG_LOCKABLE_BACKBUFFER when calling IDirect3D8::CreateDevice or IDirect3DDevice8::Reset. Lockable back buffers incur a performance cost on some graphics hardware configurations.

Performing a lock operation (or using IDirect3DDevice8::CopyRects to read/write) on the lockable back-buffer decreases performance on many cards. In this case, consider using textured triangles to move data to the back buffer.

FullScreen_RefreshRateInHz
The rate at which the display adapter refreshes the screen. For windowed mode, this value must be 0. Otherwise, this value must be one of the refresh rates returned by IDirect3D8::EnumAdapterModes or one of the following values.

Flag	Description
D3DPRESENT_RATE_DEFAULT	The run time chooses the presentation rate or adopts the current rate if windowed.
D3DPRESENT_RATE_UNLIMITED	The presentation rate runs as quickly as the hardware can deliver frames.

FullScreen_PresentationInterval
Maximum rate at which the swap chain's back buffers may be presented. For a windowed swap chain, this value must be D3DPRESENT_INTERVAL_DEFAULT (0). For a full-screen swap chain it may be D3DPRESENT_INTERVAL_DEFAULT or the value corresponding to exactly one of the flags enumerated in the PresentationIntervals member of D3DCAPS8.

Flag	Description
D3DPRESENT_INTERVAL_IMMEDIATE	Present operations might be affected immediately. The driver will not wait for the vertical retrace period.
D3DPRESENT_INTERVAL_ONE	The driver will wait for the vertical retrace period. Present operations will not be affected more frequently than the screen refresh.
D3DPRESENT_INTERVAL_TWO	The driver will wait for the vertical retrace period. Present operations will not be affected more frequently than every second screen refresh.
D3DPRESENT_INTERVAL_THREE	The driver will wait for the vertical retrace period. Present operations will not be affected more frequently than every third screen refresh.
D3DPRESENT_INTERVAL_FOUR	The driver will wait for the vertical retrace period. Present operations will not be affected more frequently than every fourth screen refresh.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: D3d8types.h.

D3DPRESENT_PARAMETERS

Members

Requirements

See Also

Additional resources