diff --git a/windows-apps-src/graphics/using-the-visual-layer-with-xaml.md b/windows-apps-src/graphics/using-the-visual-layer-with-xaml.md index 8c71daa8e8..f34317a08b 100644 --- a/windows-apps-src/graphics/using-the-visual-layer-with-xaml.md +++ b/windows-apps-src/graphics/using-the-visual-layer-with-xaml.md @@ -1,4 +1,5 @@ ---- author: jaster +--- +author: jaster ms.assetid: b7a4ac8a-d91e-461b-a060-cc6fcea8e778 title: Using the Visual Layer with XAML description: Learn techniques for using the Visual Layer API's in combination with existing XAML content to create advanced animations and effects. @@ -8,4 +9,274 @@ ms.topic: article ms.prod: windows ms.technology: uwp keywords: windows 10, uwp ---- # Using the Visual Layer with XAML ## Introduction Most apps that consume Visual Layer capabilities will use XAML to define the main UI content. In the Windows 10 Anniversary Update, there are new features in the XAML framework and the Visual Layer that make it easier to combine these two technologies to create stunning user experiences. XAML and Visual Layer “interop” functionality can be used to create advanced animations and effects not available using XAML API’s alone. This includes: - Scroll driven animations and parallax - Automatic layout animations - Pixel perfect drop shadows - Blur and frosted glass effects These effects and animations can be applied to existing XAML content, so you don’t have to dramatically restructure your XAML app to take advantage of the new functionality. Layout animations, shadows, and blur effects are covered in the Recipes section below. For a code sample implementing parallax, see the [ParallaxingListItems sample](https://github.com/Microsoft/WindowsUIDevLabs/tree/master/SampleGallery/Samples/SDK%2010586/ParallaxingListItems). The [WindowsUIDevLabs repository](https://github.com/Microsoft/WindowsUIDevLabs) also has several other samples for implementing animations, shadows and effects. ## The **ElementCompositionPreview** class [**ElementCompositionPreview**](https://msdn.microsoft.com/en-us/library/windows/apps/windows.ui.xaml.hosting.elementcompositionpreview.aspx) is a static class that provides XAML and Visual Layer interop functionality. For an overview of the Visual Layer and its functionality, see [Visual Layer](https://msdn.microsoft.com/en-us/windows/uwp/graphics/visual-layer). The **ElementCompositionPreview** class provides the following methods: - [**GetElementVisual**](https://msdn.microsoft.com/en-us/library/windows/apps/windows.ui.xaml.hosting.elementcompositionpreview.getelementvisual.aspx): Get a "handout" Visual that is used to render this element - [**SetElementChildVisual**](https://msdn.microsoft.com/en-us/library/windows/apps/windows.ui.xaml.hosting.elementcompositionpreview.setelementchildvisual.aspx): Sets a "handin" Visual as the last child of this element’s visual tree. This Visual will draw on top of the rest of the element. - [**GetElementChildVisual**](https://msdn.microsoft.com/en-us/library/windows/apps/windows.ui.xaml.hosting.elementcompositionpreview.getelementvisual.aspx): Retrieve the Visual set using **SetElementChildVisual** - [**GetScrollViewerManipulationPropertySet**](https://msdn.microsoft.com/en-us/library/windows/apps/windows.ui.xaml.hosting.elementcompositionpreview.getelementvisual.aspx): Get an object that can be used to create 60fps animations based on scroll offset in a **ScrollViewer** ## Remarks on **ElementCompositionPreview.GetElementVisual** **ElementCompositionPreview.GetElementVisual** returns a “handout” Visual that is used to render the given **UIElement**. Properties such as **Visual.Opacity**, **Visual.Offset**, and **Visual.Size** are set by the XAML framework based on the state of the UIElement. This enables techniques such as implicit reposition animations (see *Recipes*). Note that since **Offset** and **Size** are set as the result of XAML framework layout, developers should be careful when modifying or animating these properties. Developers should only modify or animate Offset when the element’s top-left corner has the same position as that of its parent in layout. Size should generally not be modified, but accessing the property may be useful. For example, the Drop Shadow and Frosted Glass samples below use Size of a handout Visual as input to an animation. As an additional caveat, updated properties of the handout Visual will not be reflected in the corresponding UIElement. So for example, setting **UIElement.Opacity** to 0.5 will set the corresponding handout Visual’s Opacity to 0.5. However, setting the handout Visual’s **Opacity** to 0.5 will cause the content to appear at 50% opacity, but will not change the value of the corresponding UIElement’s Opacity property. ### Example of **Offset** animation #### Incorrect ```xml ``` ```csharp // Doesn’t work because Image has a margin! ElementCompositionPreview.GetElementVisual(MyImage).StartAnimation("Offset", parallaxAnimation); ``` #### Correct ```xml ``` ```csharp // This works because the Canvas parent doesn’t generate a layout offset. ElementCompositionPreview.GetElementVisual(MyImage).StartAnimation("Offset", parallaxAnimation); ``` ## The **ElementCompositionPreview.SetElementChildVisual** method **ElementCompositionPreview.SetElementChildVisual** allows the developer to supply a “handin” Visual that will appear as part of an element’s Visual Tree. This allows developers to create a “Composition Island” where Visual-based content can appear inside a XAML UI. Developers should be conservative about using this technique because Visual-based content will not have the same accessibility and user experience guarantees of XAML content. Therefore, it is generally recommended that this technique only be used when necessary to implement custom effects such as those found in the Recipes section below. ## **GetAlphaMask** methods [**Image**](https://msdn.microsoft.com/library/windows/apps/br242752), [**TextBlock**](https://msdn.microsoft.com/library/windows/apps/br209652), and [**Shape**](https://msdn.microsoft.com/library/windows/apps/br243377) each implement a method called **GetAlphaMask** that returns a **CompositionBrush** representing a grayscale image with the shape of the element. This **CompositionBrush** can serve as an input for a Composition **DropShadow**, so the shadow can reflect the shape of the element instead of a rectangle. This enables pixel perfect, contour-based shadows for text, images with alpha, and shapes. See *Drop Shadow* below for an example of this API. ## Recipes ### Reposition animation Using Composition Implicit Animations, a developer can automatically animate changes in an element’s layout relative to its parent. For example, if you change the **Margin** of the button below, it will automatically animate to its new layout position. #### Implementation overview 1. Get the handout **Visual** for the target element 2. Create an **ImplicitAnimationCollection** that automatically animates changes in the **Offset** property 3. Associate the **ImplicitAnimationCollection** with the backing Visual #### XAML ```xml