| -api-id | -api-type |
|---|---|
T:Windows.UI.Xaml.Controls.SwapChainBackgroundPanel |
winrt class |
Implements a XAML layout surface target for Microsoft DirectX interoperation scenarios. This panel has some atypical restrictions on its usage within an app window; see Remarks.
Important
SwapChainBackgroundPanel may be altered or unavailable for releases after Windows 8.1. Instead, use SwapChainPanel.
<SwapChainBackgroundPanel .../>Important
SwapChainBackgroundPanel is deprecated and may not be supported in future releases. Change any existing code that used SwapChainBackgroundPanel to use SwapChainPanel instead. There's no downside to using SwapChainPanel; the API is new because it relies upon an upgrade in the internal rendering and composition systems that were introduced starting with Windows 8.1.
For most scenarios a SwapChainPanel will provide a more versatile Microsoft DirectX interop render surface than a SwapChainBackgroundPanel does. That's because a SwapChainPanel doesn't have many of the XAML-side composition limitations that are listed in the "Composition limitations" section below. For example you can apply a RenderTransform to a SwapChainPanel. For more info, see DirectX and XAML interop and SwapChainPanel.
A SwapChainBackgroundPanel is a Grid subclass, so you can use ColumnDefinitions and RowDefinitions properties to declare the panel's characteristics, and the attached properties of Grid such as Grid.Row and Grid.Column on child elements to position those child elements in the layout.
For more info on how to use SwapChainBackgroundPanel, including sample code, see DirectX and XAML interop.
The SwapChainBackgroundPanel class does not inherit from the Control class, and you cannot force focus to this element. Events that rely on having focus, such as KeyUp and KeyDown, may have no effect.
Before a SwapChainBackgroundPanel can render content, you must initialize it from the Microsoft DirectX side.
Cast the SwapChainBackgroundPanel instance to IInspectable or IUnknown, then call QueryInterface to obtain a reference to the ISwapChainBackgroundPanelNative interface (this is the native interface implementation that is the complement to the SwapChainBackgroundPanel and enables the interop bridge). Then, call ISwapChainBackgroundPanelNative.SetSwapChain on that reference to associate your implemented swap chain with the SwapChainBackgroundPanel instance.
It's common to put the code that queries the interface and sets the swap chain as part of a Create*Resources method. The Create*Resources methods are an implementation pattern that's seen in the Microsoft DirectX Renderer class templates/examples.
The API that enables you to add a SwapChain to an existing SwapChainBackgroundPanel is not a runtime class API, it is a Microsoft DirectX API. You implement the swap chain input as a Microsoft DirectX interface (IDXGISwapChain).
- A SwapChainBackgroundPanel element can only appear as the root element of a XAML element tree, or cannot have a parent element if the object tree is established through code.
- The SwapChainBackgroundPanel exists as a discrete layout element mainly so that you can satisfy some of the existing restrictions on Microsoft DirectX SwapChain integration within a Windows UI. In particular, there can only be one SwapChain per window, and the visuals in that overlay appear last in any possible z-order displayed in the window.
- Although SwapChainBackgroundPanel is a UIElement derived class, projection and transformation API have no effect upon its rendering presentation.
- Some of the non-layout properties that are inherited from Grid or from base classes such as FrameworkElement have no effect when set on a SwapChainBackgroundPanel. This is because it is the Microsoft DirectX SwapChain that should have the greater influence over what appears within the panel.