IDXGIFactory2::CreateSwapChainForHwnd method (dxgi1_2.h)

Article
10/13/2021

Creates a swap chain that is associated with an HWND handle to the output window for the swap chain.

Syntax

HRESULT CreateSwapChainForHwnd(
  [in]           IUnknown                              *pDevice,
  [in]           HWND                                  hWnd,
  [in]           const DXGI_SWAP_CHAIN_DESC1           *pDesc,
  [in, optional] const DXGI_SWAP_CHAIN_FULLSCREEN_DESC *pFullscreenDesc,
  [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] hWnd

The HWND handle that is associated with the swap chain that CreateSwapChainForHwnd creates. This parameter cannot be NULL.

[in] pDesc

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

[in, optional] pFullscreenDesc

A pointer to a DXGI_SWAP_CHAIN_FULLSCREEN_DESC structure for the description of a full-screen swap chain. You can optionally set this parameter to create a full-screen swap chain. Set it to NULL to create a windowed swap chain.

[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 CreateSwapChainForHwnd creates.

Return value

CreateSwapChainForHwnd 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, or pDesc data members are invalid.
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: DXGI_SCALING_NONE is not supported on Windows 7 or Windows Server 2008 R2 with the Platform Update for Windows 7 installed and causes CreateSwapChainForHwnd to return DXGI_ERROR_INVALID_CALL when called. For more info about the Platform Update for Windows 7, see Platform Update for Windows 7.

Remarks

Note Do not use this method in Windows Store apps. Instead, use IDXGIFactory2::CreateSwapChainForCoreWindow.

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 hWnd 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 at a time with an HWND, 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.

Requirements

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