Finetuning

Author: niels9001

hub/apps/develop/composition/visual-layer.md

@@ -1,14 +1,16 @@
 ---
-title: Visual layer for WinUI apps
-description: The Microsoft.UI.Composition API gives your WinUI and Windows App SDK apps access to the composition layer between the framework layer (XAML) and the graphics layer (DirectX).
+title: Visual layer overview
+description: The Microsoft.UI.Composition Visual layer provides a high performance, retained-mode API for graphics, effects, animations, and input for WinUI and Windows App SDK apps.
 ms.date: 03/16/2026
 ms.topic: article
 ms.localizationpriority: medium
 ---
-# Visual layer for WinUI apps
+# Visual layer overview
 
 The Visual layer provides a high performance, retained-mode API for graphics, effects, and animations, and is the foundation for all UI across Windows devices. You define your UI in a declarative manner, and the Visual layer relies on graphics hardware acceleration to ensure your content, effects, and animations are rendered in a smooth, glitch-free manner independent of the app's UI thread.
 
+The types in [Microsoft.UI.Composition](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition) form the Windows App SDK/WinUI 3 implementation of the Visual layer.
+
 Notable highlights:
 
 * Familiar WinRT APIs
@@ -30,7 +32,7 @@ The primary functions of the Visual layer are:
 
 ### Content
 
-Content is hosted, transformed and made available for use by the animation and effects system using visuals. At the base of the class hierarchy is the [**Visual**](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.visual) class, a lightweight, thread-agile proxy in the app process for visual state in the compositor. Sub-classes of Visual include  [**ContainerVisual**](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.containervisual) to allow for children to create trees of visuals and [**SpriteVisual**](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.spritevisual) that contains content and can be painted with either solid colors, custom drawn content or visual effects. Together, these Visual types make up the visual tree structure for 2D UI and back most visible XAML FrameworkElements.
+Content is hosted, transformed and made available for use by the animation and effects system using visuals. At the base of the class hierarchy is the [**Visual**](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.visual) class, a lightweight, thread-agile proxy in the app process for visual state in the compositor. Sub-classes of Visual include  [**ContainerVisual**](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.containervisual) to allow for children to create trees of visuals and [**SpriteVisual**](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.spritevisual) that contains content and can be painted with either solid colors, custom drawn content or visual effects. Together, these Visual types make up the visual tree structure for 2D UI and back most visible XAML FrameworkElements.
 
 For more information, see the [Composition Visual](composition-visual-tree.md) overview.
 
@@ -44,25 +46,61 @@ For more information, see the [Composition Effects](composition-effects.md) over
 
 ### Animations
 
-The animation system in the Visual layer lets you move visuals, animate effects, and drive transformations, clips, and other properties.  It is a framework agnostic system that has been designed from the ground up with performance in mind.  It runs independently from the UI thread to ensure smoothness and scalability.  While it lets you use familiar KeyFrame animations to drive property changes over time, it also lets you set up mathematical relationships between different properties, including user input, letting you directly craft seamless choreographed experiences.
+The animation system in the Visual layer lets you move visuals, animate effects, and drive transformations, clips, and other properties.  It is a framework agnostic system that has been designed from the ground up with performance in mind.  It runs independently from the UI thread to ensure smoothness and scalability.  While it lets you use familiar KeyFrame animations to drive property changes over time, it also lets you set up mathematical relationships between different properties, including user input, letting you directly craft seamless choreographed experiences.
 
 For more information, see the [Composition animations](composition-animation.md) overview.
 
-### Working with WinUI XAML
+## Working with WinUI XAML
 
 You can get to a Visual created by the XAML framework, and backing a visible FrameworkElement, by using the [**ElementCompositionPreview**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.hosting.elementcompositionpreview) class in [**Microsoft.UI.Xaml.Hosting**](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.hosting). Note that Visuals created for you by the framework come with some limits on customization. This is because the framework is managing offsets, transforms, and lifetimes. You can, however, create your own Visuals and attach them to an existing WinUI element via ElementCompositionPreview, or by adding them to an existing ContainerVisual somewhere in the visual tree structure.
 
 For more information, see the [Using the Visual layer with XAML](using-the-visual-layer-with-xaml.md) overview.
 
-### Working with your desktop app
+## Working with your desktop app
 
 You can use the Visual layer to enhance the look, feel, and functionality of Win32 desktop apps built with the Windows App SDK, as well as WPF, Windows Forms, and C++ Win32 desktop apps. You can migrate islands of content to use the Visual layer and keep the rest of your UI in its existing framework. This means you can make significant updates and enhancements to your application UI without needing to make extensive changes to your existing code base.
 
 For more information, see [Modernize your desktop app using the Visual layer](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps).
 
-## Additional resources
+## Differences from UWP
+
+The **Microsoft.UI.Composition** namespace provides access to functionality that's nearly identical to the UWP Visual layer (**Windows.UI.Composition**), in the most commonly used scenarios. But there are exceptions and differences.
+
+### Getting a Compositor instance
+
+In desktop apps (a WinUI app is a desktop app), **Window.Current** is `null`. So you can't retrieve an instance of [Compositor](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.compositor) from `Window.Current.Compositor`. In WinUI apps, we recommend that you call [ElementCompositionPreview.GetElementVisual(UIElement)](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.hosting.elementcompositionpreview.getelementvisual) to get a Composition [Visual](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.visual), and retrieve the `Compositor` from the visual's [Compositor](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.compositionobject.compositor) property. In cases where you don't have access to a **UIElement** (for example, if you create a [CompositionBrush](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.compositionbrush) in a class library), you can call [CompositionTarget.GetCompositorForCurrentThread](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.compositiontarget.getcompositorforcurrentthread).
+
+### External content
+
+The **Microsoft.UI.Composition** compositor runs entirely within a Windows App SDK app and has access only to pixels that it drew. That means that any *external* content (content that wasn't drawn by the compositor) is unknown to the compositor, which creates certain limitations.
+
+An example of external content is the (**Microsoft.UI.Xaml.Controls**) [MediaPlayerElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediaplayerelement). The Windows media stack provides to XAML an opaque media swap chain handle. XAML gives that handle to the compositor, which in turn hands it off to Windows (via **Windows.UI.Composition**) to display. Since the compositor can't see any of the pixels in the media swap chain, it can't composite that as part of the overall rendering for the window. Instead, it gives the media swap chain to Windows to render it below the compositor's rendering, with a hole cut out of the compositor's rendering in order to allow the media swap chain below it to be visible.
+
+[![Diagram of rendering external content](../windows-app-sdk/images/external-content.png) ](../windows-app-sdk/images/external-content.png#lightbox)
+
+In the Windows App SDK/WinUI, the following APIs all create external content:
+
+* [MediaPlayerElement](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediaplayerelement)
+* [SwapChainPanel](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.swapchainpanel)
+* [WebView2](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.webview2)
+* [MicaBackdrop](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.micabackdrop) and [DesktopAcrylicBackdrop](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.desktopacrylicbackdrop), as well as the underlying [MicaController](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.micacontroller) and [DesktopAcrylicController](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.systembackdrops.desktopacryliccontroller) that they use.
+
+The model of handling external content creates these limitations:
+
+* It's not possible to have compositor content behind external content. For example, it's not possible to give a **WebView2** a transparent background in order to see XAML buttons or images behind it. The only things that can be behind external content are *other* external content and the window background. Because of that, we discourage/disable transparency for external content.
+* It's not possible to have compositor content sample from external content. For example, [AcrylicBrush](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) isn't able to sample and blur any pixels from a **MediaPlayerElement**. **AcrylicBrush** will sample from the compositor's image, which is transparent black for external content areas. Similarly, **AcrylicBrush** in front of a **MicaBackdrop** or **DesktopAcrylicBackdrop** can't see any colors that those backdrops will draw; and instead, the brush will blur the transparent black.
+* Another scenario is known as *destination invert*, which is used for the caret of text box controls to invert the pixels that the text insertion caret is in front of. That invert similarly samples from the compositor surface, and it will be impacted if the text box doesn't have an opaque background that's drawn by the compositor.
+* Because the WinUI [SwapChainPanel](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.swapchainpanel) creates external content, it doesn't support transparency. Nor does it support applying [AcrylicBrush](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) and other effects that use a [CompositionBackdropBrush](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.compositionbackdropbrush) in front of it.
+
+## Samples
+
+The Windows App SDK Samples project includes a comprehensive set of composition samples that demonstrate how to use the **Microsoft.UI.Composition** APIs to build rich visual experiences. These samples cover a wide range of scenarios — from basic layout and transforms to advanced effects, lighting, shadows, and InteractionTracker-based input handling like pull-to-refresh and parallax scrolling. Whether you're getting started with the Visual layer or looking for patterns to apply in your own app, these samples are a practical reference for seeing how the building blocks come together.
+
+Explore the samples on GitHub: [WindowsAppSDK-Samples / SceneGraph](https://github.com/microsoft/WindowsAppSDK-Samples/tree/main/Samples/SceneGraph).
+
+![app gif](https://media.giphy.com/media/Hx2beMDfEA7QqWPvD4/giphy.gif)
+
+## Related topics
 
-* [**Full reference documentation for the API**](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition)
-* Advanced UI and Composition samples in the [Windows Composition Samples GitHub](https://github.com/microsoft/WindowsCompositionSamples)
-* Explore WinUI controls and patterns in the [WinUI Gallery](https://github.com/microsoft/WinUI-Gallery)
-* Read Kenny Kerr's MSDN article on this API: [Graphics and Animation - Windows Composition Turns 10](/archive/msdn-magazine/2015/windows-10-special-issue/graphics-and-animation-windows-composition-turns-10)
+* [**Microsoft.UI.Composition API reference**](/windows/windows-app-sdk/api/winrt/microsoft.ui.composition)
+* [Using the Visual layer in desktop apps](../desktop/modernize/ui/visual-layer-in-desktop-apps.md)

hub/apps/develop/graphics.md

@@ -32,7 +32,7 @@ The following articles provide information about features available via WinRT AP
 
 | Article | Description |
 |---------|-------------|
-| [Visual layer](../windows-app-sdk/composition.md) | Learn how to use the visual layer in UWP apps. The visual layer provides a high performance, retained-mode API for graphics, effects and animations, and is the foundation for all WinRT XAML-based UI in Windows apps. |
+| [Visual layer](composition/visual-layer.md) | Learn how to use the Visual layer in WinUI and Windows App SDK apps. The Visual layer provides a high performance, retained-mode API for graphics, effects and animations, and is the foundation for all WinRT XAML-based UI in Windows apps. |
 | [Using the Visual layer in desktop apps](../desktop/modernize/ui/visual-layer-in-desktop-apps.md) | Learn how to use the visual layer in WPF, Windows Forms, and C++ Win32 apps. |
 | [XAML platform](/windows/apps/develop/platform/xaml/) | Learn the fundamentals of the XAML language and concepts for WinRT-based graphic components Windows apps. |
 

hub/apps/develop/toc.yml

@@ -240,10 +240,9 @@ items:
       items:
       - name: Overview
         href: graphics.md
-      - name: Enhance UI with the Visual layer
-        href: ../windows-app-sdk/composition.md
+      - name: Visual layer
         items:
-        - name: Visual layer overview
+        - name: Overview
           href: composition/visual-layer.md
         - name: Composition visual
           href: composition/composition-visual-tree.md