D3DPRESENT_PARAMETERS structure

Describes the presentation parameters.

Syntax

typedef struct D3DPRESENT_PARAMETERS {
  UINT                BackBufferWidth;
  UINT                BackBufferHeight;
  D3DFORMAT           BackBufferFormat;
  UINT                BackBufferCount;
  D3DMULTISAMPLE_TYPE MultiSampleType;
  DWORD               MultiSampleQuality;
  D3DSWAPEFFECT       SwapEffect;
  HWND                hDeviceWindow;
  BOOL                Windowed;
  BOOL                EnableAutoDepthStencil;
  D3DFORMAT           AutoDepthStencilFormat;
  DWORD               Flags;
  UINT                FullScreen_RefreshRateInHz;
  UINT                PresentationInterval;
} D3DPRESENT_PARAMETERS, *LPD3DPRESENT_PARAMETERS;

Members

BackBufferWidth

Type: UINT

Width of the new swap chain's back buffers, in pixels. If Windowed is FALSE (the presentation is full-screen), this value must equal the width of one of the enumerated display modes found through EnumAdapterModes. If Windowed is TRUE and either BackBufferWidth or BackBufferHeight is zero, the corresponding dimension of the client area of the hDeviceWindow (or the focus window, if hDeviceWindow is NULL) is taken.

BackBufferHeight

Type: UINT

Height of the new swap chain's back buffers, in pixels. If Windowed is FALSE (the presentation is full-screen), this value must equal the height of one of the enumerated display modes found through EnumAdapterModes. If Windowed is TRUE and either BackBufferWidth or BackBufferHeight is zero, the corresponding dimension of the client area of the hDeviceWindow (or the focus window, if hDeviceWindow is NULL) is taken.

BackBufferFormat

Type: D3DFORMAT

The back buffer format. For more information about formats, see D3DFORMAT. This value must be one of the render-target formats as validated by CheckDeviceType. You can use GetDisplayMode to obtain the current format.

In fact, D3DFMT_UNKNOWN can be specified for the BackBufferFormat while in windowed mode. This tells the runtime to use the current display-mode format and eliminates the need to call GetDisplayMode.

For windowed applications, the back buffer format no longer needs to match the display-mode format because color conversion can now be done by the hardware (if the hardware supports color conversion). The set of possible back buffer formats is constrained, but the runtime will allow any valid back buffer format to be presented to any desktop format. (There is the additional requirement that the device be operable in the desktop; devices typically do not operate in 8 bits per pixel modes.)

Full-screen applications cannot do color conversion.

BackBufferCount

Type: UINT

This value can be between 0 and D3DPRESENT_BACK_BUFFERS_MAX (or D3DPRESENT_BACK_BUFFERS_MAX_EX when using Direct3D 9Ex). Values of 0 are treated as 1. If the number of back buffers cannot be created, the runtime 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.

The method fails if one 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

Type: D3DMULTISAMPLE_TYPE

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.

MultiSampleQuality

Type: DWORD

Quality level. The valid range is between zero and one less than the level returned by pQualityLevels used by CheckDeviceMultiSampleType. Passing a larger value returns the error D3DERR_INVALIDCALL. Paired values of render targets or of depth stencil surfaces and D3DMULTISAMPLE_TYPE must match.

SwapEffect

Type: D3DSWAPEFFECT

Member of the D3DSWAPEFFECT enumerated type. The runtime will guarantee the implied semantics concerning buffer swap behavior; therefore, if Windowed is TRUE and SwapEffect is set to D3DSWAPEFFECT_FLIP, the runtime will create one extra back buffer and copy whichever becomes the front buffer at presentation time.

D3DSWAPEFFECT_COPY requires that BackBufferCount be set to 1.

D3DSWAPEFFECT_DISCARD will be enforced in the debug runtime by filling any buffer with noise after it is presented.

Differences between Direct3D9 and Direct3D9Ex:

• In Direct3D9Ex, D3DSWAPEFFECT_FLIPEX is added to designate when an application is adopting flip mode. That is, when an application's frame is passed in window's mode (instead of copied) to the Desktop Window Manager(DWM) for composition. Flip mode provides more efficient memory bandwidth and enables an application to take advantage of full-screen-present statistics. It does not change full screen behavior. Flip mode behavior is available beginning with Windows 7.

 

hDeviceWindow

Type: HWND

The device window determines the location and size of the back buffer on screen. This is used by Direct3D when the back buffer contents are copied to the front buffer during Present.

• For a full-screen application, this is a handle to the top window (which is the focus window).

  For applications that use multiple full-screen devices (such as a multimonitor system), exactly one device can use the focus window as the device window. All other devices must have unique device windows.

• For a windowed-mode application, this handle will be the default target window for Present. If this handle is NULL, the focus window will be taken.

Note that no attempt is made by the runtime 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

Type: BOOL

TRUE if the application runs windowed; FALSE if the application runs full-screen.

EnableAutoDepthStencil

Type: BOOL

If this value is TRUE, 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

Type: D3DFORMAT

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

Type: DWORD

One of the D3DPRESENTFLAG constants.

FullScreen_RefreshRateInHz

Type: UINT

The rate at which the display adapter refreshes the screen. The value depends on the mode in which the application is running:

• For windowed mode, the refresh rate must be 0.
• For full-screen mode, the refresh rate is one of the refresh rates returned by EnumAdapterModes.

PresentationInterval

Type: UINT

The maximum rate at which the swap chain's back buffers can be presented to the front buffer. For a detailed explanation of the modes and the intervals that are supported, see D3DPRESENT.

Requirements

See also

Direct3D Structures

CreateDevice

CreateAdditionalSwapChain

Present

Reset