SwapEffect Enumeration (Microsoft.DirectX.Direct3D)

Article
06/29/2006

Defines swap effects.

Definition

Visual Basic Public Enum SwapEffect

C# public enum SwapEffect

C++ public enum class SwapEffect

JScript public enum SwapEffect

Members

Member Value Description

Discard 1 When a swap chain is created with a swap effect of Flip or Copy, the runtime guarantees that a Present operation will not affect the content of any of the back buffers. However, meeting this guarantee can involve substantial video memory or processing overheads, especially when implementing flip semantics for a windowed swap chain or copy semantics for a full-screen swap chain.
An application can use the Discard swap effect to avoid these overheads and to enable the display driver to choose the most efficient presentation technique for the swap chain.
Discard is also the only swap effect that can be used when specifying a value other than None for PresentParameters.MultiSampleType. Like a swap chain that uses Flip, a swap chain that uses Discard might include more than one back buffer, any of which can be accessed using Device.GetBackBuffer or SwapChain.GetBackBuffer.
The swap chain is essentially a queue where 0 always indexes the back buffer that will be displayed by the next Present operation and from which buffers are discarded once they have been displayed. An application that uses this swap effect should update an entire back buffer before invoking a Present operation that displays it.
The debug version of the runtime overwrites the contents of discarded back buffers with random data, to enable developers to verify that their applications are updating the entire back buffer surface correctly.
For a full-screen swap chain, the presentation rate is determined by the value assigned to PresentParameters.PresentationInterval when the device or swap chain is created. Unless this value is Immediate, the presentation is synchronized with the vertical sync of the monitor. For a windowed swap chain, the presentation is implemented by means of copy operations, and always occurs immediately.

Copy 3 This swap effect can be specified only for a swap chain that comprises a single back buffer.
Whether the swap chain is windowed or full-screen, the runtime guarantees the semantics implied by a copy-based Present operation; specifically, that the operation leaves the content of the back buffer unchanged, instead of replacing it with the content of the front buffer as a flip-based Present operation would.
For a windowed swap chain, a Present operation causes the back buffer content to be copied immediately to the client area of the target window. No attempt is made to synchronize the copy with the vertical retrace period of the display adapter, so tearing effects may be observed.
For a full-screen swap chain, the runtime uses a combination of flip and copy operations, which are supported by hidden back buffers if necessary, to accomplish the Present operation. Accordingly, the presentation is synchronized with the display adapter's vertical retrace and its rate is constrained by the chosen presentation interval. A swap chain specified with the Immediate flag is the only exception. (For more information, see PresentParameters.PresentationInterval.) In this case, a Present operation copies the back buffer content directly to the front buffer without waiting for the vertical retrace.

Flip 2 The swap chain might include multiple back buffers and is essentially a circular queue that includes the front buffer. Within this queue, the back buffers are always numbered sequentially from 0 to (n - 1), where n is the number of back buffers, so that 0 denotes the least recently presented buffer.
When Present is invoked, the queue is rotated so that the front buffer becomes the back buffer (n - 1), while the back buffer 0 becomes the new front buffer.
For a full-screen swap chain, the presentation rate is determined by the value assigned to the PresentParameters.PresentationInterval when the device or swap chain is created. Unless this value is Immediate, the presentation is synchronized with the vertical sync of the monitor.
For a windowed swap chain, the flipping is implemented by means of copy operations, and the presentation always occurs immediately.

Member	Value	Description
Discard	1	When a swap chain is created with a swap effect of Flip or Copy, the runtime guarantees that a Present operation will not affect the content of any of the back buffers. However, meeting this guarantee can involve substantial video memory or processing overheads, especially when implementing flip semantics for a windowed swap chain or copy semantics for a full-screen swap chain. An application can use the Discard swap effect to avoid these overheads and to enable the display driver to choose the most efficient presentation technique for the swap chain. Discard is also the only swap effect that can be used when specifying a value other than None for PresentParameters.MultiSampleType. Like a swap chain that uses Flip, a swap chain that uses Discard might include more than one back buffer, any of which can be accessed using Device.GetBackBuffer or SwapChain.GetBackBuffer. The swap chain is essentially a queue where 0 always indexes the back buffer that will be displayed by the next Present operation and from which buffers are discarded once they have been displayed. An application that uses this swap effect should update an entire back buffer before invoking a Present operation that displays it. The debug version of the runtime overwrites the contents of discarded back buffers with random data, to enable developers to verify that their applications are updating the entire back buffer surface correctly. For a full-screen swap chain, the presentation rate is determined by the value assigned to PresentParameters.PresentationInterval when the device or swap chain is created. Unless this value is Immediate, the presentation is synchronized with the vertical sync of the monitor. For a windowed swap chain, the presentation is implemented by means of copy operations, and always occurs immediately.
Copy	3	This swap effect can be specified only for a swap chain that comprises a single back buffer. Whether the swap chain is windowed or full-screen, the runtime guarantees the semantics implied by a copy-based Present operation; specifically, that the operation leaves the content of the back buffer unchanged, instead of replacing it with the content of the front buffer as a flip-based Present operation would. For a windowed swap chain, a Present operation causes the back buffer content to be copied immediately to the client area of the target window. No attempt is made to synchronize the copy with the vertical retrace period of the display adapter, so tearing effects may be observed. For a full-screen swap chain, the runtime uses a combination of flip and copy operations, which are supported by hidden back buffers if necessary, to accomplish the Present operation. Accordingly, the presentation is synchronized with the display adapter's vertical retrace and its rate is constrained by the chosen presentation interval. A swap chain specified with the Immediate flag is the only exception. (For more information, see PresentParameters.PresentationInterval.) In this case, a Present operation copies the back buffer content directly to the front buffer without waiting for the vertical retrace.
Flip	2	The swap chain might include multiple back buffers and is essentially a circular queue that includes the front buffer. Within this queue, the back buffers are always numbered sequentially from 0 to (n - 1), where n is the number of back buffers, so that 0 denotes the least recently presented buffer. When Present is invoked, the queue is rotated so that the front buffer becomes the back buffer (n - 1), while the back buffer 0 becomes the new front buffer. For a full-screen swap chain, the presentation rate is determined by the value assigned to the PresentParameters.PresentationInterval when the device or swap chain is created. Unless this value is Immediate, the presentation is synchronized with the vertical sync of the monitor. For a windowed swap chain, the flipping is implemented by means of copy operations, and the presentation always occurs immediately.

Remarks

The state of the back buffer after a call to Present is well-defined by each of these swap effects, and whether the Microsoft Direct3D device was created with a full-screen swap chain or a windowed swap chain has no effect on this state. In particular, the Flip swap effect operates the same whether windowed or full-screen, and the Direct3D runtime guarantees this by creating extra buffers. As a result, it is recommended that applications use Discard whenever possible to avoid any performance penalties, because the current swap effect is always the most efficient in terms of memory consumption and performance.

Full-screen destination alpha will not work with applications that use Flip or Discard. This means that the DestinationBlend render state will not work as expected because, from the driver's point of view, full-screen swap chains with these swap effects do not have an explicit pixel format. The driver infers that it should take on the display format, which does not have an alpha channel. To work around this, use Copy and check the DriverCaps.SupportsAlphaFullscreenFlipOrDiscard property, which indicates whether the driver can perform alpha blending when Flip or Discard are used.

Enumeration Information

Namespace Microsoft.DirectX.Direct3D

Assembly Microsoft.DirectX.Direct3D (microsoft.directx.direct3d.dll)

Strong Name Microsoft.DirectX.Direct3D, Version=1.0.900.0, Culture=neutral, PublicKeyToken=d3231b57b74a1492

Visual Basic	Public Enum SwapEffect
C#	public enum SwapEffect
C++	public enum class SwapEffect
JScript	public enum SwapEffect

Namespace	Microsoft.DirectX.Direct3D
Assembly	Microsoft.DirectX.Direct3D (microsoft.directx.direct3d.dll)
Strong Name	Microsoft.DirectX.Direct3D, Version=1.0.900.0, Culture=neutral, PublicKeyToken=d3231b57b74a1492

SwapEffect Enumeration (Microsoft.DirectX.Direct3D)

Additional resources