IDXGIFactory2::CreateSwapChainForComposition method (dxgi1_2.h)

Creates a swap chain that you can use to send Direct3D content into the DirectComposition API, to the Windows.UI.Xaml framework, or to Windows UI Library (WinUI) XAML, to compose in a window.

Syntax

HRESULT CreateSwapChainForComposition(
  [in]           IUnknown                    *pDevice,
  [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. Software drivers, like D3D_DRIVER_TYPE_REFERENCE, are not supported for composition swap chains.

[in] pDesc

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

You must specify the DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL value in the SwapEffect member of DXGI_SWAP_CHAIN_DESC1 because CreateSwapChainForComposition supports only flip presentation model.

You must also specify the DXGI_SCALING_STRETCH value in the Scaling member of DXGI_SWAP_CHAIN_DESC1.

[in, optional] pRestrictToOutput

A pointer to the IDXGIOutput interface for the output to restrict content to. You must also pass the DXGI_PRESENT_RESTRICT_TO_OUTPUT flag in a IDXGISwapChain1::Present1 call to force the content to appear blacked out on any other output. If you want to restrict the content to a different output, you must create a new swap chain. However, you can conditionally restrict content based on the DXGI_PRESENT_RESTRICT_TO_OUTPUT flag.

Set this parameter to NULL if you don't want to restrict content to an output target.

[out] ppSwapChain

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

Return value

CreateSwapChainForComposition 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, CreateSwapChainForComposition fails with E_NOTIMPL. For more info about the Platform Update for Windows 7, see Platform Update for Windows 7.

Remarks

You can use composition swap chains with either:

• DirectComposition's IDCompositionVisual interface,
• System XAML's SwapChainPanel or SwapChainBackgroundPanel classes.
• Windows UI Library (WinUI) 3 XAML's SwapChainPanel or SwapChainBackgroundPanel classes.

For DirectComposition, you can call the IDCompositionVisual::SetContent method to set the swap chain as the content of a visual object, which then allows you to bind the swap chain to the visual tree. For XAML, the SwapChainBackgroundPanel class exposes a classic COM interface ISwapChainBackgroundPanelNative. You can use the ISwapChainBackgroundPanelNative::SetSwapChain method to bind to the XAML UI graph. For info about how to use composition swap chains with XAML’s SwapChainBackgroundPanel class, see DirectX and XAML interop.

The IDXGISwapChain::SetFullscreenState, IDXGISwapChain::ResizeTarget, IDXGISwapChain::GetContainingOutput, IDXGISwapChain1::GetHwnd, and IDXGISwapChain::GetCoreWindow methods aren't valid on this type of swap chain. If you call any of these methods on this type of swap chain, they fail.

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

Examples

For a code example showing how to use CreateSwapChainForComposition, see SwapChainPanel and gaming.

• For WinRT XAML, the ISwapChainPanelNative and ISwapChainBackgroundPanelNative interfaces are declared in the windows.ui.xaml.media.dxinterop.h header.
• For Windows UI Library (WinUI) XAML, the ISwapChainPanelNative and ISwapChainBackgroundPanelNative interfaces are declared in the microsoft.ui.xaml.media.dxinterop.h header.

Requirements

See also

• For best performance, use DXGI flip model
• IDXGIFactory2