Windows UI Composition API Reference (UWP)

The Windows UI Composition API provides a low-level, hardware-accelerated rendering pipeline for UWP (Universal Windows Platform) applications. It allows developers to create fluid, dynamic, and visually rich user interfaces with extensive control over animations, transformations, and visual effects.

Introduction

The Composition API enables developers to build complex visual trees composed of various visual elements like sprites, text, images, and effects. It leverages the GPU for rendering, resulting in highly performant UI that can handle demanding visual scenarios. This API is fundamental to modern Windows UI development, powering frameworks like XAML Composition and providing direct access to the rendering surface.

Core Concepts

Compositor: The central object responsible for managing the visual tree, rendering, and animations.
Visual: The basic building block of the visual tree. Various types of Visuals exist, such as SpriteVisual for 2D content and ContainerVisual for grouping.
Visual Tree: A hierarchical structure of Visual objects that defines what is rendered on the screen.
Properties: Visuals have properties like Offset, Size, Opacity, and TransformMatrix that can be animated.
Animations: The API supports various animation types, including ScalarTransitionAnimation, Vector3TransitionAnimation, and Vector4TransitionAnimation, allowing for smooth property changes.

API Reference

Compositor

The Compositor class is the heart of the Composition API. It manages the visual tree, creates Visual objects, and handles the rendering process.

class Compositor { public VisualCollection Children { get; } public void Render(); // ... other methods and properties }

Visual

The base class for all objects in the composition tree.

abstract class Visual { public Vector3 Offset { get; set; } public float Opacity { get; set; } public Matrix4x4 TransformMatrix { get; set; } public VisualCollection Children { get; } // ... common properties }

SpriteVisual

Represents a simple 2D surface that can display content, such as an image or a color.

class SpriteVisual : Visual { public Brush Brush { get; set; } public Shadow Shadow { get; set; } // ... }

Properties:

Name	Type	Description
`Brush`	`Brush`	The brush used to render the content of the `SpriteVisual`. Can be a solid color, an image, or a visual effect.
`Shadow`	`Shadow`	Applies a shadow effect to the visual.

ContainerVisual

A Visual that can hold other Visual objects, forming a hierarchical structure.

class ContainerVisual : Visual { // Inherits properties from Visual // ... }

ContainerVisual primarily uses the Children property inherited from Visual to manage its child visuals.

VisualCollection

A collection of Visual objects, typically managed by a ContainerVisual or the Compositor itself.

class VisualCollection : ICollection { public void InsertAt(uint index, Visual visual); public void RemoveAt(uint index); // ... ICollection members }

Insets

Represents thickness values for different edges (left, top, right, bottom), often used for padding or layout.

struct Insets { public double Left { get; set; } public double Top { get; set; } public double Right { get; set; } public double Bottom { get; set; } // ... constructor }

Color

Represents an ARGB (Alpha, Red, Green, Blue) color value.

struct Color { public byte A { get; set; } public byte R { get; set; } public byte G { get; set; } public byte B { get; set; } public static Color FromArgb(byte a, byte r, byte g, byte b); // ... }

Vector2

Represents a 2D vector with X and Y components.

struct Vector2 { public float X { get; set; } public float Y { get; set; } public static Vector2 Parse(string value); // ... }

Vector3

Represents a 3D vector with X, Y, and Z components.

struct Vector3 { public float X { get; set; } public float Y { get; set; } public float Z { get; set; } // ... }

Matrix4x4

Represents a 4x4 matrix, commonly used for 3D transformations (translation, rotation, scale).

struct Matrix4x4 { // Properties representing matrix elements public static Matrix4x4 CreateTranslation(Vector3 position); public static Matrix4x4 CreateRotationX(float radians); public static Matrix4x4 CreateScale(float xScale, float yScale, float zScale = 1.0f); // ... }

Animation

Represents an animation that changes a property over time. This is a conceptual overview; specific animation types (like ScalarTransitionAnimation) are used in practice.

Note: The Composition API utilizes a specific animation system where animations are created and targeted to properties of Visuals. This typically involves creating an animation instance (e.g., ScalarTransitionAnimation) and then inserting it into the target Visual's animation properties.

Getting Started

To use the Composition API, you typically need to obtain a Compositor instance. In UWP applications, this is often accessible through the CoreWindow or a SwapChainPanel.


// Example: Getting the Compositor in a UWP app
var coreWindow = CoreWindow.GetForCurrentThread();
var compositor = new Compositor();
var visual = compositor.CreateSpriteVisual();
visual.Size = new Vector2((float)coreWindow.Bounds.Width, (float)coreWindow.Bounds.Height);
visual.Brush = compositor.CreateColorBrush(new Color { R = 255, G = 0, B = 0, A = 255 }); // Red color

var visualCollection = compositor.CreateContainerVisual();
visualCollection.Children.Add(visual);

// Link the visual tree to the target element (e.g., SwapChainPanel)
// swapChainPanel.CompositionVisual = visualCollection;

Examples

Explore the official Microsoft samples for practical implementations of the Composition API, including animations, effects, and custom controls.

FAQ

Q: How does Composition API relate to XAML?
A: XAML UI elements can be backed by Composition visuals, allowing developers to leverage the declarative nature of XAML while benefiting from the performance of the Composition pipeline. Many XAML properties automatically map to Composition API properties.

Q: Can I animate any property?
A: Most animatable properties of Visual objects can be animated. This includes position, opacity, scale, rotation, and color.