Swap​Chain​Panel Swap​Chain​Panel Swap​Chain​Panel Swap​Chain​Panel Class

Definition

Provides a hosting surface, where Microsoft DirectX swap chains provide content that can be rendered into a XAML UI. A SwapChainPanel element is a key component for an app that renders Microsoft DirectX graphics and then presents those visuals within a XAML page.

public : class SwapChainPanel : Grid, ISwapChainPanelpublic class SwapChainPanel : Grid, ISwapChainPanelPublic Class SwapChainPanel Inherits Grid Implements ISwapChainPanel// This API is not available in Javascript.
<SwapChainPanel .../>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited properties

Inherited events

Inherited methods

Remarks

A SwapChainPanel 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 code examples that use SwapChainPanel, see XAML SwapChainPanel DirectX interop sample.

The SwapChainPanel class does not inherit from the Control class, so you can't programmatically focus it directly for purposes of capturing key events. Consider setting the focus to a focusable element inside the panel and letting the key event bubble.

In order to maintain crisp vector rendering, you should listen for the CompositionScaleChanged event and query the CompositionScaleX and CompositionScaleY property values to account for the current UI scale, and potentially render again from DirectX. Otherwise XAML layout might do the scaling and your visuals might be degraded.

Initializing a SwapChainPanel element

Before a SwapChainPanel can render content, you must initialize it from the Microsoft DirectX side.

Cast the SwapChainPanel instance to IInspectable or IUnknown, then call QueryInterface to obtain a reference to the ISwapChainPanelNative interface (this is the native interface implementation that is the complement to the SwapChainPanel and enables the interop bridge). Then, call ISwapChainPanelNative::SetSwapChain on that reference to associate your implemented swap chain with the SwapChainPanel 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, and you'll also see this implementation pattern in the SDK samples, and in the code you get from the DirectX (XAML) project template in Microsoft Visual Studio. Specifically, in the DirectX (XAML) project template, you'll see the **QueryInterface ** call and the call to ISwapChainPanelNative::SetSwapChain in the DeviceResources::CreateWindowSizeDependentResources method implementation in DeviceResources.cpp.

The API that enables you to add a SwapChain to an existing SwapChainPanel is not a runtime class API, it is a Microsoft DirectX API. You implement the swap chain input as a Microsoft DirectX interface (IDXGISwapChain).

SwapChainPanel and SwapChainBackgroundPanel

SwapChainPanel has less restrictions on its interactions and placement in UI than does SwapChainBackgroundPanel.

Swap chains

  • Swap chains must run on the main UI thread. This is usually accomplished by calling SetSwapChain on a reference that was initialized as a XAML object element.
  • A single swap chain can be associated with multiple SwapChainPanel elements. Or, your app can have multiple swap chains, with each providing the presentation for a separate SwapChainPanel.
  • However, performance can decline if many swap chains are updated simultaneously. We recommend that your app use no more than four swap chains.
  • Content that's rendered via the swap chain is not stretched when it's resized by the user; instead, the resizing behavior is similar to setting Stretch="None" on an Image element.
  • There are other techniques for rendering swap chain content that goes directly to the app's core window rather than a XAML-composed element. See CreateSwapChainForCoreWindow.

Processing input on background threads

Using the CreateCoreIndependentInputSource method, apps can process input and render to a SwapChainPanel entirely on one or more background threads. This enables high performance input and rendering independent of the XAML UI thread.

Constructors

SwapChainPanel() SwapChainPanel() SwapChainPanel() SwapChainPanel()

Initializes a new instance of the SwapChainPanel class.

public : SwapChainPanel()public SwapChainPanel()Public Sub New()// This API is not available in Javascript.

Remarks

Important

Initialization through the constructor is not enough to enable the SwapChainPanel element to render the swap chain. You must use a native interface and Microsoft DirectX code. For more info see the "Initializing a SwapChainPanel element" section in the SwapChainPanel class topic.

Properties

CompositionScaleX CompositionScaleX CompositionScaleX CompositionScaleX

Gets the x-axis scale factor of the SwapChainPanel.

public : float CompositionScaleX { get; }public float CompositionScaleX { get; }Public ReadOnly Property CompositionScaleX As float// This API is not available in Javascript.
Value
float float float float

The x-axis scale factor of the SwapChainPanel. A value of 1.0 means no scaling is applied.

Remarks

The CompositionScaleX scale factor is applied to the swap chain content when it's rendered to the screen and composited into the XAML content. The scale factor is derived from calculating the render transformations (implicit or explicit) applied to the SwapChainPanel and its ancestors.

The scale factor will be an estimate if a Projection property value is present on the SwapChainPanel or one of its ancestors.

Check this property any time you are handling CompositionScaleChanged (CompositionScaleChanged doesn't have event data, but if it fires it means that CompositionScaleX, CompositionScaleY, or both have changed values on this SwapChainPanel ).

See Also

CompositionScaleXProperty CompositionScaleXProperty CompositionScaleXProperty CompositionScaleXProperty

Identifies the CompositionScaleX dependency property.

public : static DependencyProperty CompositionScaleXProperty { get; }public static DependencyProperty CompositionScaleXProperty { get; }Public Static ReadOnly Property CompositionScaleXProperty As DependencyProperty// This API is not available in Javascript.

CompositionScaleY CompositionScaleY CompositionScaleY CompositionScaleY

Gets the y-axis scale factor of the SwapChainPanel.

public : float CompositionScaleY { get; }public float CompositionScaleY { get; }Public ReadOnly Property CompositionScaleY As float// This API is not available in Javascript.
Value
float float float float

The y-axis scale factor of the SwapChainPanel. A value of 1.0 means no scaling is applied.

Remarks

The CompositionScaleY scale factor is applied to the swap chain content when it's rendered to the screen and composited into the XAML content. The scale factor is derived from calculating the render transformations (implicit or explicit) applied to the SwapChainPanel and its ancestors.

The scale factor will be an estimate if a Projection property value is present on the SwapChainPanel or one of its ancestors.

Check this property any time you are handling CompositionScaleChanged (CompositionScaleChanged doesn't have event data, but if it fires it means that CompositionScaleX, CompositionScaleY, or both have changed values on this SwapChainPanel ).

See Also

CompositionScaleYProperty CompositionScaleYProperty CompositionScaleYProperty CompositionScaleYProperty

Identifies the CompositionScaleY dependency property.

public : static DependencyProperty CompositionScaleYProperty { get; }public static DependencyProperty CompositionScaleYProperty { get; }Public Static ReadOnly Property CompositionScaleYProperty As DependencyProperty// This API is not available in Javascript.

Methods

CreateCoreIndependentInputSource(CoreInputDeviceTypes) CreateCoreIndependentInputSource(CoreInputDeviceTypes) CreateCoreIndependentInputSource(CoreInputDeviceTypes) CreateCoreIndependentInputSource(CoreInputDeviceTypes)

Creates a core input object that handles the input types as specified by the deviceTypes parameter. This core input object can process input events on a background thread.

public : CoreIndependentInputSource CreateCoreIndependentInputSource(CoreInputDeviceTypes deviceTypes)public CoreIndependentInputSource CreateCoreIndependentInputSource(CoreInputDeviceTypes deviceTypes)Public Function CreateCoreIndependentInputSource(deviceTypes As CoreInputDeviceTypes) As CoreIndependentInputSource// This API is not available in Javascript.
Parameters
deviceTypes
CoreInputDeviceTypes CoreInputDeviceTypes CoreInputDeviceTypes CoreInputDeviceTypes

A combined value of the enumeration.

Returns

An object that represents the input subsystem for interoperation purposes and can be used for input event connection points.

Remarks

This method enables an app that includes a SwapChainPanel to handle input and rendering independent of the XAML UI thread, because you're deliberately providing the input processing logic on a background thread. You must call CreateCoreIndependentInputSource from a non-UI thread, otherwise this method will fail.

Use the CreateCoreIndependentInputSource method to create a core input object and associate it with your SwapChainPanel. Upon successful creation, user input of the specified device types that accesses SwapChainPanel contents will be redirected to the thread that CreateCoreIndependentInputSource was called from. Your app can handle this input by registering for input events and processing those events on a background thread. In order to receive input messages through the CoreIndependentInputSource object, the app code must set a swap chain on the SwapChainPanel, and render (at a Microsoft DirectX level) from this swap chain at least once. That provides the rendering that makes hit testing possible.

You typically use CoreDispatcher::ProcessEvents as part of the event handling. Get a CoreDispatcher reference from CoreIndependentInputSource::Dispatcher. For more info on how to use background threads, see ThreadPool or Threading and async programming.

You can call CreateCoreIndependentInputSource multiple times. Each time CreateCoreIndependentInputSource is called, the previous CoreIndependentInputSource object is disassociated with the SwapChainPanel. In other words, only one CoreIndependentInputSource object can get events at a time.

For example code of how to use CreateCoreIndependentInputSource, see the DrawingPanel class definition that is part of the XAML SwapChainPanel DirectX interop sample.

CreateCoreIndependentInputSource d can return null if deviceTypes was passed as CoreInputDeviceTypes.None (that's not a typical way to call CreateCoreIndependentInputSource though).

See Also

Events

CompositionScaleChanged CompositionScaleChanged CompositionScaleChanged CompositionScaleChanged

Occurs when the composition scale factor of the SwapChainPanel has changed.

public : event TypedEventHandler CompositionScaleChanged<SwapChainPanel,  object>public event TypedEventHandler CompositionScaleChanged<SwapChainPanel,  object>Public Event CompositionScaleChanged<SwapChainPanel,  object>// This API is not available in Javascript.
<SwapChainPanel CompositionScaleChanged="eventhandler"/>

Remarks

The supplier of the swap chain content might need to resize their content if a layout pass determines a new size for the panel or containers it's within, or if a RenderTransform is applied on the SwapChainPanel or any of its ancestors. Changes of this nature aren't always originated by app logic that's easy to detect from other events (for example the user might change a device orientation or a view state that causes layout to rerun), so this event provides a notification specifically for the scenario of changing the swap chain content size, which would typically invert the scale factors applied.

Check CompositionScaleX and CompositionScaleY any time you are handling CompositionScaleChanged (CompositionScaleChanged doesn't have event data, but if it fires it means that one or both properties have changed values on this SwapChainPanel ).

This event fires asynchronously versus the originating change. For example, dynamic animations or manipulations might affect the scale factor, and the event is raised when those dynamic changes are completed.

See Also