Changes the background color of the swap chain.
HRESULT SetBackgroundColor( [in] const DXGI_RGBA *pColor );
- pColor [in]
A pointer to a DXGI_RGBA structure that specifies the background color to set.
- 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.
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.
Minimum supported client
|Windows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps]|
Minimum supported server
|Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps | Windows Store apps]|