IDXGIFactory2::CreateSwapChainForCoreWindow method (dxgi1_2.h)

Article
10/13/2021

Creates a swap chain that is associated with the CoreWindow object for the output window for the swap chain.

Syntax

HRESULT CreateSwapChainForCoreWindow(
  [in]           IUnknown                    *pDevice,
  [in]           IUnknown                    *pWindow,
  [in]           const DXGI_SWAP_CHAIN_DESC1 *pDesc,
  [in, optional] IDXGIOutput                 *pRestrictToOutput,
  [out]          IDXGISwapChain1             **ppSwapChain
);

Parameters

[in] pDevice

For Direct3D 11, and earlier versions of Direct3D, this is a pointer to the Direct3D device for the swap chain. For Direct3D 12 this is a pointer to a direct command queue (refer to ID3D12CommandQueue). This parameter cannot be NULL.

[in] pWindow

A pointer to the CoreWindow object that is associated with the swap chain that CreateSwapChainForCoreWindow creates.

[in] pDesc

A pointer to a DXGI_SWAP_CHAIN_DESC1 structure for the swap-chain description. This parameter cannot be NULL.

[in, optional] pRestrictToOutput

A pointer to the IDXGIOutput interface that the swap chain is restricted to. If the swap chain is moved to a different output, the content is black. You can optionally set this parameter to an output target that uses DXGI_PRESENT_RESTRICT_TO_OUTPUT to restrict the content on this output. If you do not set this parameter to restrict content on an output target, you can set it to NULL.

[out] ppSwapChain

A pointer to a variable that receives a pointer to the IDXGISwapChain1 interface for the swap chain that CreateSwapChainForCoreWindow creates.

Return value

CreateSwapChainForCoreWindow returns:

S_OK if it successfully created a swap chain.
E_OUTOFMEMORY if memory is unavailable to complete the operation.
DXGI_ERROR_INVALID_CALL if the calling application provided invalid data, for example, if pDesc or ppSwapChain is NULL.
Possibly other error codes that are described in the DXGI_ERROR topic that are defined by the type of device that you pass to pDevice.

Platform Update for Windows 7: On Windows 7 or Windows Server 2008 R2 with the Platform Update for Windows 7 installed, CreateSwapChainForCoreWindow fails with E_NOTIMPL. For more info about the Platform Update for Windows 7, see Platform Update for Windows 7.

Remarks

Note Use this method in Windows Store apps rather than IDXGIFactory2::CreateSwapChainForHwnd.

If you specify the width, height, or both (Width and Height members of DXGI_SWAP_CHAIN_DESC1 that pDesc points to) of the swap chain as zero, the runtime obtains the size from the output window that the pWindow parameter specifies.

You can subsequently call the IDXGISwapChain1::GetDesc1 method to retrieve the assigned width or height value.

Because you can associate only one flip presentation model swap chain (per layer) at a time with a CoreWindow, the Microsoft Direct3D 11 policy of deferring the destruction of objects can cause problems if you attempt to destroy a flip presentation model swap chain and replace it with another swap chain. For more info about this situation, see Deferred Destruction Issues with Flip Presentation Swap Chains.

For info about how to choose a format for the swap chain's back buffer, see Converting data for the color space.

Overlapping swap chains

Starting with Windows 8.1, it is possible to create an additional swap chain in the foreground layer. A foreground swap chain can be used to render UI elements at native resolution while scaling up real-time rendering in the background swap chain (such as gameplay). This enables scenarios where lower resolution rendering is required for faster fill rates, but without sacrificing UI quality.

Foreground swap chains are created by setting the DXGI_SWAP_CHAIN_FLAG_FOREGROUND_LAYER swap chain flag in the DXGI_SWAP_CHAIN_DESC1 that pDesc points to. Foreground swap chains must also use the DXGI_ALPHA_MODE_PREMULTIPLIED alpha mode, and must use DXGI_SCALING_NONE. Premultiplied alpha means that each pixel's color values are expected to be already multiplied by the alpha value before the frame is presented. For example, a 100% white BGRA pixel at 50% alpha is set to (0.5, 0.5, 0.5, 0.5). The alpha premultiplication step can be done in the output-merger stage by applying an app blend state (see ID3D11BlendState) with the D3D11_RENDER_TARGET_BLEND_DESC structure's SrcBlend field set to D3D11_SRC_ALPHA. If the alpha premultiplication step is not done, colors on the foreground swap chain will be brighter than expected.

The foreground swap chain will use multiplane overlays if supported by the hardware. Call IDXGIOutput2::SupportsOverlays to query the adapter for overlay support.

The following example creates a foreground swap chain for a CoreWindow:


DXGI_SWAP_CHAIN_DESC1 swapChainDesc = { 0 };

swapChainDesc.Width = static_cast<UINT>(m_d3dRenderTargetSize.Width);
swapChainDesc.Height = static_cast<UINT>(m_d3dRenderTargetSize.Height);
swapChainDesc.Format = DXGI_FORMAT_B8G8R8A8_UNORM;
swapChainDesc.Stereo = false;
swapChainDesc.SampleDesc.Count = 1; // Don't use multi-sampling.
swapChainDesc.SampleDesc.Quality = 0;
swapChainDesc.BufferUsage = DXGI_USAGE_RENDER_TARGET_OUTPUT;
swapChainDesc.BufferCount = 2;
swapChainDesc.SwapEffect = DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL;
swapChainDesc.Flags = DXGI_SWAP_CHAIN_FLAG_FOREGROUND_LAYER;
swapChainDesc.AlphaMode = DXGI_ALPHA_MODE_PREMULTIPLIED;
swapChainDesc.Scaling = DXGI_SCALING_NONE;

ComPtr<IDXGISwapChain1> swapChain;
HRESULT hr = dxgiFactory->CreateSwapChainForCoreWindow(
    m_d3dDevice.Get(),
    reinterpret_cast<IUnknown*>(m_window.Get()),
    &swapChainDesc,
    nullptr,
    &swapChain
    );

Present both swap chains together after rendering is complete.

The following example presents both swap chains:


HRESULT hr = m_swapChain->Present(1, 0);

if (SUCCEEDED(hr) && m_foregroundSwapChain)
{
    m_foregroundSwapChain->Present(1, 0);
}

Requirements

Requirement	Value
Minimum supported client	Windows 8 and Platform Update for Windows 7 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	dxgi1_2.h
Library	Dxgi.lib

Share via