IDXGISwapChain1::SetBackgroundColor method (dxgi1_2.h)

Changes the background color of the swap chain.

Syntax

HRESULT SetBackgroundColor(
  [in] const DXGI_RGBA *pColor
);

Parameters

[in] pColor

A pointer to a DXGI_RGBA structure that specifies the background color to set.

Return value

SetBackgroundColor returns:

• S_OK if it successfully set the background color.
• E_INVALIDARG if the pColor parameter is incorrect, for example, pColor is NULL or any of the floating-point values of the members of DXGI_RGBA to which pColor points are outside the range from 0.0 through 1.0.
• Possibly other error codes that are described in the DXGI_ERROR topic.

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

Remarks

The background color affects only swap chains that you create with DXGI_SCALING_NONE in windowed mode. You pass this value in a call to IDXGIFactory2::CreateSwapChainForHwnd, IDXGIFactory2::CreateSwapChainForCoreWindow, or IDXGIFactory2::CreateSwapChainForComposition. Typically, the background color is not visible unless the swap-chain contents are smaller than the destination window.

When you set the background color, it is not immediately realized. It takes effect in conjunction with your next call to the IDXGISwapChain1::Present1 method. The DXGI_PRESENT flags that you pass to IDXGISwapChain1::Present1 can help achieve the effect that you require. For example, if you call SetBackgroundColor and then call IDXGISwapChain1::Present1 with the Flags parameter set to DXGI_PRESENT_DO_NOT_SEQUENCE, you change only the background color without changing the displayed contents of the swap chain.

When you call the IDXGISwapChain1::Present1 method to display contents of the swap chain, IDXGISwapChain1::Present1 uses the DXGI_ALPHA_MODE value that is specified in the AlphaMode member of the DXGI_SWAP_CHAIN_DESC1 structure to determine how to handle the a member of the DXGI_RGBA structure, the alpha value of the background color, that achieves window transparency. For example, if AlphaMode is DXGI_ALPHA_MODE_IGNORE, IDXGISwapChain1::Present1 ignores the a member of DXGI_RGBA.

Requirements

See also

DXGI_SCALING

IDXGISwapChain1

IDXGISwapChain1::GetBackgroundColor