IDirectDrawSurface5::Flip

This method makes the surface memory associated with the DDSCAPS_BACKBUFFER surface become associated with the front-buffer surface.

HRESULT Flip(
  LPDIRECTDRAWSURFACE5 lpDDSurfaceTargetOverride, 
  DWORD dwFlags
);

Parameters

  • lpDDSurfaceTargetOverride
    Address of the IDirectDrawSurface5 interface for an arbitrary surface in the flipping chain. The default for this parameter is NULL, in which case DirectDraw cycles through the buffers in the order they are attached to each other. If this parameter is not NULL, DirectDraw flips to the specified surface instead of the next surface in the flipping chain. The method fails if the specified surface is not a member of the flipping chain.
  • dwFlags
    Flags specifying flip options. The following table shows the possible flags.
    Flag Description
    DDFLIP_EVEN For use only when displaying video in an overlay surface. The new surface contains data from the even field of a video signal. This flag cannot be used with the DDFLIP_ODD flag.
    DDFLIP_INTERVAL2
    DDFLIP_INTERVAL3
    DDFLIP_INTERVAL4
    These flags indicate how many vertical retraces to wait between each flip. The default is 1. DirectDraw will return DERR_WASSTILLDRAWING for each surface involved in the flip until the specified number of vertical retraces has occurred. If DDFLIP_INTERVAL2 is set, DirectDraw will flip on every second vertical sync; if DDFLIP_INTERVAL3, on every third sync; and if DDFLIP_INTERVAL4, on every fourth sync.

    These flags are effective only if DDCAPS2_FLIPINTERVAL is set in the DDCAPS structure returned for the device.

    DDFLIP_NOVSYNC Causes DirectDraw to perform the physical flip as close as possible to the next scan line. Subsequent operations involving the two flipped surfaces will not check to see if the physical flip has finished, that is, they will not return DDERR_WASSTILLDRAWING for that reason (but may for other reasons). This check allows an application to perform flips at a higher frequency than the monitor refresh rate, but may introduce visible artifacts.

    If DDCAPS2_FLIPNOVSYNC is not set in the DDCAPS structure returned for the device, DDFLIP_NOVSYNC has no effect.

    DDFLIP_ODD For use only when displaying video in an overlay surface. The new surface contains data from the odd field of a video signal. This flag cannot be used with the DDFLIP_EVEN flag.
    DDFLIP_WAIT Typically, if the flip cannot be set up because the state of the display hardware is not appropriate, the DDERR_WASSTILLDRAWING error returns immediately and no flip occurs. Setting this flag causes the method to continue trying to flip if it receives the DDERR_WASSTILLDRAWING error from the HAL. The method does not return until the flipping operation has been successfully set up, or another error, such as DDERR_SURFACEBUSY, is returned.

Return Values

If the method succeeds, the return value is DD_OK.

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

Remarks

This method can be called only for a surface that has the DDSCAPS_FLIP and DDSCAPS_FRONTBUFFER capabilities. The display memory previously associated with the front buffer is associated with the back buffer.

The lpDDSurfaceTargetOverride parameter is used in rare cases when the back buffer is not the buffer that should become the front buffer. Typically this parameter is NULL.

The IDirectDrawSurface5::Flip method will always be synchronized with the vertical blank. If the surface has been assigned to a video port, this method updates the visible overlay surface and the video port's target surface.

Requirements

OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later.
Header: Ddraw.h.
Link Library: Ddraw.lib.

See Also

IDirectDrawSurface5::GetFlipStatus

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.