Awaken Your Creativity with the new Windows.UI.Composition

We live and work in a fast-paced, real-time, information environment where the scarcest resource of all is not information itself, but human attention to that information. This is why user experiences and UI need to evolve to more effectively target human attention amid the cacophony of data and distraction. Success or failure of apps presenting the same information can come down to having the most engaging experience. This means creating more personal experiences that are playful, create delight, and drive up engagement, as they provide users with the insights and information they seek. A focus on creating beautiful experiences allows developers to differentiate their apps from the competition.

This is why the Windows platform enables developers to build beautiful apps, simply and by default.

Although this story will unfold over time, today we to announce the first chapter with a brand new family of APIs in the November update of Windows 10 under the Windows.UI.Composition namespace.

This new family of WinRT APIs contains light-weight visuals, animations, effects, and manipulations to create smooth and highly-scalable UI experiences, inspired by the motion and graphical design evolutions in the world around us: in movies, on television, in app and game designs, in print and elsewhere. You can use this functionality within your existing XAML–based Universal Windows Platform app (UWP). In future we expect to support desktop apps as well.

In the initial release of Windows 10, significant work was done to create a new unified compositor and rendering engine for all UWP applications running on Windows 10 devices .

Now with the first update of Windows 10, Build 10586, we are releasing this public API and Windows.UI.Composition.

What is Windows.UI.Composition?

The Windows.UI.Compositon WinRT APIs can be called from any Universal Windows Platform app to create lightweight visuals and apply powerful animations, effects, and manipulations on those objects in your application. The goal is not to replace any existing framework, but to be a valuable supplement to existing frameworks.

In the past, this kind of work was difficult to do in a UWP application and required basic app developers drop off a steep cliff down to DirectX for custom UI work.

With the new API a XAML developer can “drop down” and do custom work in the composition layer using WinRT to create a “Composition Island” of objects in a familiar WinRT language such as C#.

How does this help you with a beautiful engaging UI? By giving you access to this new layer of APIs, Windows.UI.Composition lets you create composition objects directly in the compositor layer, which improves performance and scale using exciting new features.

The New Effects System

Real-time effects that can be animated, customized and chained. Effects include 2D affine transforms, arithmetic composites, blends, color source, composite, contrast, exposure, grayscale, gamma transfer, hue rotate, invert, saturate, sepia, temperature and tint.

Below is an example of a saturation effect that shows a number of key concepts, effects can be defined once and reused multiple times, effects are based on the concept of sources as inputs to effects and effects can be a source to another effects enabling chaining. Effects can be set for animations.

// Create the graphics effect          
var graphicsEffect = new SaturationEffect
{
   Name = "SaturationEffect",
   Saturation = 0.0f,
   Source = new CompositionEffectSourceParameter("mySource")
};

// Compile the effect specifying saturation is an animatable property
var effectFactory = _compositor.CreateEffectFactory(graphicsEffect, new[] { "SaturationEffect.Saturation" });
myEffect = effectFactory.CreateBrush();
myEffect.SetSourceParameter("mySource", surfaceBrush);
myEffect.Properties.InsertScalar("saturationEffect.Saturation", 0f);         

For a detailed look at applying and using the effect see a description of the Effects system in the Overview of The New Effects System.

A New Animation System

Windows.UI.Composition has an expressive, framework-agnostic animation system that allows you to set up Keyframes and Expressions that can move the new lightweight Visuals, drive a transform or a clip, or animate an effect. By running directly in the compositor process, the new system ensures smoothness and scale, letting you run large numbers of concurrent, explicit animations. Below is a quick example of how a KeyFrame animation is structured using a the predefined effect above. Key concepts to take note here are that KeyFrame based animations allow effects, or transforms or any animatable objects in the API to animated over time.

// Create a ScalarKeyFrame to that will be used to animate the Saturation property of an Effect
ScalarKeyFrameAnimation effectAnimation = _compositor.CreateScalarKeyFrameAnimation();
effectAnimation.InsertKeyFrame(0f, 0f);
effectAnimation.InsertKeyFrame(0.50f, 1f);
effectAnimation.InsertKeyFrame(1.0f, 0f);
effectAnimation.Duration = TimeSpan.FromMilliseconds(2500);
effectAnimation.IterationBehavior = AnimationIterationBehavior.Forever;

// Start the Animation on the Saturation property of the Effect
myEffect.Properties.StartAnimation("saturationEffect.Saturation", effectAnimation);

For more detailed information, see the Overview of The New Animation System.

A Deeper Look Starting with the Basics: The Composition Visual Sample

Before diving into the advanced concepts of the API, a good place to start is learning the fundamental concepts by looking at how objects are created using a Compositor and doing basic transformations and tree operations on those objects.

You can learn some of the basic concepts of the API in the CompositionVisual sample from our Composition GitHub. This sample is a simple framework-less app written entirely in the API.

In the sample there are a number of transparent, solid color squares that can be clicked on and dragged about the screen. When clicked on, a square will come to the front, rotate 45 degrees. Then when you drag it about the screen it will becomes opaque.

This shows a number of basic concepts for working with the API including:

• Creating a compositor
• Creating a SpriteVisual with a ColorBrush
• Clipping a Visual
• Rotating a Visual
• Setting Opacity
• Changing the Visual’s position in the collection.

In the sample there are also three different Visuals at work:

• Visual– base object, the majority of the properties are here, and inherited by the other Visual objects.
• ContainerVisual– derives from Visual, and adds the ability to create children.
• SpriteVisual – derives from ContainerVisual and adds the ability to associate a brush that paints pixels, is used to paint the Visual with images, effects or a solid color on the Visual.

While this sample doesn’t cover concepts like Animations or more complex effects, it contains the building blocks that all of those systems use. There will bemore links to supplemental information in future blog posts.

Please note, all example code below is in C#.

Creating a Compositor

Creating a Compositor and storing it for use as a factory in a _variable is a simple task. This is a simple line of code:

_compositor = new Compositor();

Creating a SpriteVisual and ColorBrush

Using the Compositor it’s now easy to create objects whenever you need them, such as a SpriteVisual and a ColorBrush.:

var visual = _compositor.CreateSpriteVisual();

visual.Brush = _compositor.CreateColorBrush(Color.FromArgb(0xFF, 0xFF, 0xFF, 0xFF));

While this is only a few simple lines of code, it demonstrates a powerful concept, SpriteVisuals are the heart of our new effects system. The SpriteVisual allows for great flexibility and interplay in color, image and effect creation. The SpriteVisual is a single visual type that can fill a 2D rectangle with a brush, in this case a solid color.

Clipping a Visual

The Compositor can also be used to create clips on a Visual. Below is an example from the sample of using the InsetClip to trim each side of the Visual:

var clip = _compositor.CreateInsetClip();

clip.LeftInset = 1.0f;
clip.RightInset = 1.0f;
clip.TopInset = 1.0f;
clip.BottomInset = 1.0f;

_currentVisual.Clip = clip;

Transforming a Visual

A Visual can be transformed with a rotation. RotationAngle supports both radeons and degrees. It defaults to Radeons, but it’s easy to specify degrees as shown in below:

child.RotationAngleInDegrees = 45.0f;

Rotation is just one example of a set of transform components provided by the API to make these tasks easier. Other include Offset, Scale, Orientation, RotationAxis and a 4×4 TransformMatrix.

Setting Opacity

This is also a simple operation using a float value. For example, in the sample all the squares start at .8 opacity:

visual.Opacity = 0.8f;

Important Note: All of the clips and transforms above, like almost all objects in the API, are animatable.

Managing Your Visual tree

A Visual’s position relative to its sibling’s can be changed in a number of ways when it is added or moved in the tree, it can be placed above another Visual with InsertAbove, placed below with InsertBelow, move to the top with InsertAtTop or the bottom with InsertAtBottom.

In the sample a Visual that has been clicked on is sorted to the top:

parent.Children.InsertAtTop(_currentVisual);

It’s also important to note that while sibling re-ordering appears to change Visual z-order, this is still essentially a 2D scene, and does not represent a true global 3D z-order.

XAML Interoperability

One of the key concepts of the new API is the ability to add a “composition island” of objects directly to a XAML application. A developer can get the backing Visual of a UIElement in XAML and apply an animation or load a custom image an apply an effect.

For a detailed example of how this works, see this Parallax Code Sample.

This is only the beginning of learning Windows.UI.Composition

These basic concepts only the scratch the surface of the power of the new API there’s much, much more.

Follow the links below to learn more:

• Overview of The New Effects System
• Overview of The New Animation System
• Advanced DX and D2D Interoperability

Additional Resources:

• MSDN Article on the new API: Graphics and Animation – Windows Composition Turns 10– this covers more complex topics
• Samples from our Composition GitHub.
• Read the full documentation for the API on MSDN.
• The list of Known Issues on MSDN.
• Contact the team: WinComp@microsoft.com

• Follow us on Twitter: @wincomposition

Special Note to Preview Users of the API

Thanks to all of you who tried out the preview version of the API, for your efforts and feedback. You helped make this a better API. As a preview user there are several things to note about the final API:

• You no longer need to declare a security capability in your manifest, the API is fully public.
• We have removed the SolidColorVisual, ImageVisual and EffectVisual. You now use Color, Image and Effects through SpriteVisuals.
• Pause and Resume were removed from animation system to streamline using Start and Stop.
• A new Composition batch feature has been added.
• Better DirectX and D2D interop through the CompositionDrawingSurface .
• Improved XAML interop.

For a detailed list of all the changes please see this MSDN forum post.

Blog post written by John Serna on the Windows.UI.Composition Team.