SwapChainPanel SwapChainPanel SwapChainPanel Class

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.

Syntax

Declaration

public class SwapChainPanelpublic class SwapChainPanelPublic Class SwapChainPanel
<SwapChainPanel .../>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

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 RowDefinitions and ColumnDefinitions 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(Windows.UI.Core.CoreInputDeviceTypes) 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 summary

Initializes a new instance of the SwapChainPanel class.

Properties summary

Gets the x-axis scale factor of the SwapChainPanel.

Identifies the CompositionScaleX dependency property.

Gets the y-axis scale factor of the SwapChainPanel.

Identifies the CompositionScaleY dependency property.

Methods summary

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.

Events summary

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

Constructors

  • SwapChainPanel()
    SwapChainPanel()
    SwapChainPanel()
    SwapChainPanel()

    Initializes a new instance of the SwapChainPanel class.

    public SwapChainPanel()public SwapChainPanel()Public Function SwapChainPanel() As

    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

    Property Value

    • 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 ).

  • 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

    Property Value

  • 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

    Property Value

    • 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 ).

  • 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

    Property Value

Methods

Events

  • CompositionScaleChanged
    CompositionScaleChanged
    CompositionScaleChanged
    CompositionScaleChanged

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

    public event TypedEventHandler CompositionScaleChangedpublic event TypedEventHandler CompositionScaleChangedPublic Event CompositionScaleChanged
    <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.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll