DXGIXPresentArray

Serves as the Present method when using multiple overlay planes, or when needing to make use of the PresentImmediateThreshold functionality.

Syntax

HRESULT DXGIXPresentArray(
         UINT SyncInterval,
         UINT PresentImmediateThreshold,
         UINT Flags,
         UINT NumSwapChains,
         IDXGISwapChain1 * const *ppSwapChain,
         const DXGIX_PRESENTARRAY_PARAMETERS *pPresentParameters
)

Parameters

SyncInterval
Type: UINT

[in] The sync interval in number of vsyncs. 0 means to present immediately with tearing. 1 means to present every vsync (that is, 60 fps) and 2 means to present every second vsync (that is, 30 fps).

PresentImmediateThreshold
Type: UINT

[in] The immediate threshold for presenting, as a percentage (from 0 to 100) of screen coverage in scanlines.

This PresentImmediateThreshold parameter corresponds to the D3DRS_PRESENTIMMEDIATETHRESHOLD functionality on Xbox 360. It allows for presents that are synchronized to vsync (no tearing) when the target frame-rate is being met; and it allows for immediate presents (with tearing) when the target frame-rate is not being met. The value of the parameter controls what portion of the screen is allowed to have tearing.

The rules for PresentImmediateThreshold functionality are:

If the GPU is done the frame before the desired number of vsyncs, wait until the appropriate vsync before flipping. For example, when the title is making its target budget, always flip synchronized to the vsync.
If the GPU is done the frame after the desired number of vsyncs:
- If the DAC is less than x% threshold of the way through the frame, flip immediately. For example, if the title just missed its frame target, and if the DAC is still scanning out of the top of the frame where tearing wouldn’t be very noticeable, flip immediately and tear.
- If the DAC is more than x% threshold of the way through the frame, flip at the next vsync.
- If zero is entered for the threshold then sync to vsync, no change from a simple present to vsync.

For example, if this parameter is set at 30, this means if the display has scanned out less than 30 percent of the visible scanlines, flip.

Note

PresentImmediateThreshold has no effect if the threshold is within the system GPU reservation. For example, if a title uses a PresentImmediateThreshold of 10, the title might not see any Flips other than at vblanks. When the title misses the vblank, the title automatically also misses the threshold, since the system reservation occupies the entire 10%.

Flags
Type: UINT

[in] For the flags, see DXGI_PRESENT at MSDN.

NumSwapChains
Type: UINT

[in] The number of swap chains.

ppSwapChain
Type: IDXGISwapChain1 * const *

[in] The swap chain, as a pointer to pointer to IDXGISwapChain1.

pPresentParameters
Type: DXGIX_PRESENTARRAY_PARAMETERS *

[in] The parameters for presenting an array, as a pointer to a DXGIX_PRESENTARRAY_PARAMETERS structure.

If the new DXGIX_PRESENTARRAY_PARAMETERS parameters are changed from the previous call to DXGIXPresentArray:

The PresentImmediateThreshold argument will be treated as if it is zero.
If the SyncInterval argument is 0, the SyncInterval argument will be treated as if it is one.

This is because any changes to the hardware’s scaler parameters have to be done synchronously to the Vsync. In other words, immediate presents are not supported when the scaler parameters change from the previous frame’s setting.

Return value

Type: HRESULT

One of the Direct3D 11 return codes.

Remarks

DXGIXPresentArray is the recommended present method for Xbox One.

If you are having trouble hitting your target frame-rate at your target resolution on the GPU, consider dynamically resizing your resolution based on GPU load. The DXGIXPresentArray method allows the scaler resolution settings to be synchronously changed frame-to-frame. Remember that on Xbox One or Xbox One S you can have your HUD on one overlay plane and your 3D content on another overlay plane with a different resolution and blended using per-pixel hardware. If your situation allows, you can also render one plane at a slower update rate by taking advantage of the UsePreviousBuffer field of the DXGIX_PRESENTARRAY_PARAMETERS structure. The scaler quality is an improvment over the Xbox 360.

Note

Xbox One X does not support compositing of two display planes in this manner, but does support the use of two display planes for SDR and HDR (see below).

This is the only Present method that can be used when outputting HDR (high dynamic range) and WCG (wide color gamut), and in this case the title must present two swapchains:

The first swap chain is output to the HDR/WGC TV, and this swap chain must have been created using the DXGI_FORMAT_R10G10B10A2_UNORM format and the DXGIX_SWAP_CHAIN_FLAG_COLORIMETRY_RGB_BT2020_ST2084 swapchain flag (refer to DXGI_SWAP_CHAIN_FLAG). This indicates that the swapchain data is HDR and WCG encoded with ST.2084 transfer curve using BT.2020 primaries.
The second swap chain is used for GameDVR and screenshots. The data in this swapchain is an 8-bit SDR (standard dynamic range): gamma (i.e. 2.2) and BT.709 primaries.

Alternatively a title may create a single HDR swap chain in the format DXGI_FORMAT_R10G10B10A2_UNORM and using the DXGIX_SWAP_CHAIN_FLAG_COLORIMETRY_RGB_BT2020_ST2084 DXGIX_SWAP_CHAIN_FLAG_AUTOMATIC_GAMEDVR_TONEMAP swap chain flags together to indicate that the swap chain data is HDR and that the driver should perform SDR tone mapping automatically. When using automatic tone mapping, the title does not need to create or present the SDR swap chain itself, only the single HDR swap chain needs to be presented with DXGIXPresentArray; the SDR swap chain will be prepared and used for GameDVR automatically.

Note

For the highest-quality recording and best performance its recommended that titles perform tone mapping manually by omitting DXGIX_SWAP_CHAIN_FLAG_AUTOMATIC_GAMEDVR_TONEMAP and using the separate HDR and SDR swap chains.

When using HDR, the second hardware plane is not available because the title needs to use the two hardware planes to output HDR to the TV, and SDR to GameDVR.

Refer to High Dynamic Range (HDR) output for the HDR initialization process.

Exclusive apps can create and present up to 3840x2160 swapchains. When using the DXGIXPresentArray function, each member of the source rectangle is limited to multiples of four. If both dimensions of a swap-chain are less than or equal to 1920x1080, then the destination rectangle is assumed to be in a 1920x1080 virtual space; if either dimension is greater than 1920x1080, then the destination rectangle is assumed to be in a 3840x2160 virtual space. In either case, the scale factor must be set such that the destination rectangle is fully contained within this virtual space. For example:

If the resolution of the swap chain is 1600x900, then the virtual destination desktop has a resolution of 1920x1080 and the correct scale factor is 1.2.
If the resolution of the swap chain is 2560x1440, then the virtual destination desktop has a resolution of 3840x2160 and the correct scale factor is 1.5.
If the resolution of the swap chain is 2016x900, then the virtual destination desktop has a resolution of 3840x2160 and the correct scale factors are 1.90476 and 2.4.

As with 1920x1080 swapchains, the destination virtual space is automatically scaled up or down to match the resolution of the display mode on the television. There can be a maximum of three buffers in the swapchain (that is, it can be at the most triple-buffered).

Requirements

Header: Declared in d3d11_x.h.