CompositionProToolkit v0.4 Released!

I am thrilled to announce that CompositionProToolkit v0.4 is now released. It brings a few breaking changes and new features that will help you use the Composition APIs more efficiently. In this blog I will be talking in detail about them.

Breaking Changes

First, let me tell you about the breaking changes incorporated in CompositionProToolkit v0.4

  • ICompositionMaskGenerator has been renamed to ICompositionGenerator – you will now be using this interface to generate many other objects apart from ICompositionMask. (More on that later!)
  • ICompositionMaskGeneratorInternal has been renamed to ICompositionGeneratorInternal – this will not break any of your code as it is an internal class.
  • CompositionMaskGenerator has been renamed to CompositionGenerator – another internal class which implements the ICompositionGenerator and the ICompositionGeneratorInternal interfaces.
  • CompositionMaskFactory has been renamed to CompositionGeneratorFactory – You will be using this class to obtain the instance of ICompositionGenerator.
    • GetCompositionMaskGenerator API has been renamed to GetCompositionGenerator – The parameters of this API remain the same.
public static ICompositionGenerator GetCompositionGenerator(Compositor compositor,     
    CompositionGraphicsDevice graphicsDevice = null, object sharedLock = null)

Now that we are done with the breaking changes, lets discuss the new features that have been added to CompositionProToolkit.

Creating a ICompositionMask using ICanvasBrush

ICompositionGenerator now provides the following additional API to create a ICompositionMask using an ICanvasBrush or its derivatives like CanvasImageBrush, CanvasLinearGradientBrush, CanvasRadialGradientBrush and CanvasSolidColorBrush.

Task<ICompositionMask> CreateMaskAsync(Size size, CanvasGeometry geometry, ICanvasBrush brush);

ICompositionSurfaceImage

ICompositionSurfaceImage is an interface which encapsulates a CompositionDrawingSurface onto which an image can be loaded by providing a Uri. You can then use the CompositionDrawingSurface to create a CompositionSurfaceBrush which can be applied to any Visual.

SurfaceImage.png

ICompositionGenerator provides the following API which allows you to create a CompositionSurfaceImage

Task<ICompositionSurfaceImage> CreateSurfaceImageAsync(Uri uri, Size size, 
    CompositionSurfaceImageOptions options);

This API requires the Uri of the image to be loaded, the size of the CompositionDrawingSurface (usually the same size as the Visual on which it is finally applied) and the CompositionSurfaceImageOptions.

CompositionSurfaceImageOptions

The CompositionSurfaceImageOptions class encapsulates a set of properties which influence the rendering of the image on the CompositionSurfaceImage. The following table shows the list of these properties.

Property Type Description Possible Values
Stretch Stretch Describes how image is resized to fill its allocated space. None,
Uniform,
Fill,
UniformToFill
HorizontalAlignment AlignmentX Describes how image is positioned horizontally. Left,
Center,
Right
VerticalAlignment AlignmentY Describes how image is positioned vertically. Top,
Center,
Bottom
Opacity float Specifies the opacity of the rendered image. 0 - 1f inclusive
Interpolation CanvasImageInterpolation Specifies the interpolation used to render the image. NearestNeighbor, Linear,
Cubic,
MultiSampleLinear,
Anisotropic,
HighQualityCubic
SurfaceBackgroundColor Color Specifies the color which will be used to fill the surface before rendering the image. All possible values that can be created.

Here is how the image is aligned on the Visual’s surface based on the HorizontalAlignment and VerticalAlignment properties

Alignment

The area on the Visual’s surface, which is not covered by the rendered image, will be filled with the color specified by the SurfaceBackgroundColor property

Example

The following example shows how you can load an image onto a Visual

var compositor = ElementCompositionPreview.GetElementVisual(this).Compositor;
var generator = CompositionGeneratorFactory.GetCompositionGenerator(compositor);

var visual = compositor.CreateSpriteVisual();
visual.Size = new Vector2(this.ActualWidth.Single(), this.ActualHeight.Single());
visual.Offset = Vector3.Zero;

var options = new CompositionSurfaceImageOptions(Stretch.Uniform, AlignmentX.Center,
    AlignmentY.Center, 0.9f, CanvasImageInterpolation.Cubic)
    {
        SurfaceBackgroundColor = Colors.Maroon
    };

var surfaceImage =
    await generator.CreateSurfaceImageAsync(new Uri("ms-appx:///Assets/Images/Image3.jpg"), 
          visual.Size.ToSize(), options);

visual.Brush = compositor.CreateSurfaceBrush(_surfaceImage.Surface);

Once you create a CompositionSurfaceBrush from the ICompositionSurfaceImage and apply it to a Visual, you can use the following ICompositionSurfaceImage APIs to resize, provide a new Uri or change the rendering options

Task RedrawAsync();

Task RedrawAsync(CompositionSurfaceImageOptions options);

Task RedrawAsync(Uri uri, CompositionSurfaceImageOptions options);

Task RedrawAsync(Uri uri, Size size, CompositionSurfaceImageOptions options);

Task ResizeAsync(Size size);

Task ResizeAsync(Size size, CompositionSurfaceImageOptions options);

Once you call any of the above methods, the Visual’s brush is also updated.

Visual Reflection

A new API has been added to CompositionProToolkit which allows you to create the reflection of any Visual.

Task CreateReflectionAsync(ContainerVisual visual, float reflectionDistance = 0f,
    float reflectionLength = 0.7f, ReflectionLocation location = ReflectionLocation.Bottom);

The parameters required for this API are

  • visual – A ContainerVisual whose reflection has to be created.
  • reflectionDistance – The distance between the visual and its reflection.
  • reflectionLength – The normalized length (0 – 1f, inclusive) of the visual that must be visible in the reflection. Default value is 0.7f.
  • location – Specifies the location of the reflection with respect to the visual – Bottom, Top, Left or Right. Default value is ReflectionLocation.Bottom.

ReflectionLocation.png

This API will create a reflection even if an effect is applied to the Visual.

ReflectionWithEffect.png

If the visual has multiple other visuals in its visual tree, then the entire visual tree is reflected.

ReflectionMultipleVisuals.png

Other Changes

With the Anniversary Release of Windows 10, CompositionProToolkit project has migrated to Windows SDK 14393. Also it now requires CompositionExpressionToolkit v0.2.4 or higher, and Win2d v1.19 or higher (this is added automatically when you add a NuGet reference to CompositionProToolkit).

The source code is available in GitHub and the NuGet library is available here.

Advertisements

One thought on “CompositionProToolkit v0.4 Released!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s