Module composition

Expand description

The composition renderer.

§Architecture and threading

As upstream, there are two compositors. The Compositor lives on the UI thread together with the composition objects; the server::ServerCompositor owns the server-side counterparts of those objects and renders them. They exchange data in one direction only, through batches: at commit the UI-thread compositor serializes the changes of its objects into a transport::CommittedBatch and enqueues it; at the start of each frame the server compositor applies the queued batches.

The object model of the UI thread is Rc-based and thread-affine, so the two sides are kept apart by construction rather than by locks:

UI-thread objects never hold their server counterpart. They hold a server::ServerObjectId, a plain value. A server object is created by the server compositor itself, from a factory carried by the batch (Compositor::create_server_object); changes and disposal refer to it by id. Server objects therefore need not be Send: they are created, mutated and dropped on the render thread only.
The batch queue (server::BatchQueue) is the only crossing point. What may cross is exactly what a transport::BatchObject can hold plus plain values.
The few values the UI thread reads back (the clock, the readback indices, batch completion) are Send + Sync types shared through Arc.

Today the server compositor runs on the thread of its compositor in every configuration: the render loop may tick on any thread (its tasks are Send + Sync), and a tick that arrives elsewhere is marshalled to the compositor’s dispatcher. Running the server on a dedicated render thread is blocked by one thing outside this module: the platform resource handles carried by batches (std::sync::Arc<dyn IGeometryImpl>, std::sync::Arc<crate::platform::SharedBitmapImpl>, std::sync::Arc<dyn IGlyphRunImpl>, immutable brushes and pens) are Rc-based and so are the render contracts the server draws with. Once those are shareable across threads, the remaining steps are local: require Send on the Job, Create and Value payloads of BatchObject, make the batch queue a mutex-protected queue, and construct the server compositor on the render thread. No unsafe is used anywhere in the composition renderer.

The browser target has no threads; it uses the same single-thread mode with a UI-thread render timer.

Re-exports§

pub use brushes::CompositionBrush;
pub use brushes::CompositionConicGradientBrush;
pub use brushes::CompositionGradientBrush;
pub use brushes::CompositionLinearGradientBrush;
pub use brushes::CompositionRadialGradientBrush;
pub use brushes::CompositionSolidColorBrush;
pub use brushes::CompositionSurfaceBrush;
pub use brushes::CompositionMaskBrush;
pub use brushes::CompositionNineGridBrush;
pub use brushes::CompositionBackdropBrush;
pub use brushes::CompositionEffectBrush;
pub use brushes::CompositionHostBackdropBrush;
pub use effects::CompositionEffectFactory;
pub use effects::CompositionEffectFactoryError;
pub use effects::CompositionEffectFactoryLoadStatus;
pub use effects::CompositionEffectSourceParameter;
pub use server::RenderSurfaces;
pub use animations::BooleanKeyFrameAnimation;
pub use animations::ColorKeyFrameAnimation;
pub use animations::DoubleKeyFrameAnimation;
pub use animations::QuaternionKeyFrameAnimation;
pub use animations::RelativePointKeyFrameAnimation;
pub use animations::RelativeScalarKeyFrameAnimation;
pub use animations::ScalarKeyFrameAnimation;
pub use animations::Vector2KeyFrameAnimation;
pub use animations::Vector3DKeyFrameAnimation;
pub use animations::Vector3KeyFrameAnimation;
pub use animations::Vector4KeyFrameAnimation;
pub use animations::VectorKeyFrameAnimation;
pub use animations::AnimationController;
pub use animations::AnimationControllerProgressBehavior;
pub use animations::CompositionColorSpace;
pub use animations::NaturalMotionAnimation;
pub use animations::ScalarNaturalMotionAnimation;
pub use animations::SpringScalarNaturalMotionAnimation;
pub use animations::SpringVector2NaturalMotionAnimation;
pub use animations::SpringVector3NaturalMotionAnimation;
pub use animations::Vector2NaturalMotionAnimation;
pub use animations::Vector3NaturalMotionAnimation;

Modules§

animations: Composition animations.
brushes: The composition brushes and their server-side counterparts.
drawing: Render data: the recorded form of what a visual draws, its resources, and the operations on it (replay, bounds, hit testing).
effects: The effects of the WinUI composition API (phase 6, scoped): the effect descriptions an effect factory is made from (the FerroUI form of the Win2D effects WinUI takes), the factory, and the loaded graph its brushes draw.
expressions: Expressions of composition animations: the variant value type, the expression tree, its parser and the functions callable from expressions.
generated: The composition object model generated from the composition schema.
hit_testing: Hit testing of the composition visual tree.
interactions: Microsoft.UI.Composition.Interactions: interaction trackers and the visual interaction sources that drive them with input.
server: The server (render thread) side of the composition renderer.
system_backdrops: Microsoft.UI.Composition.SystemBackdrops (winui-materials.md): the controllers of the system backdrops (Mica and desktop acrylic), their configuration and their targets.
transport: The transport between the UI-thread compositor and the server compositor: batches of serialized changes.

Structs§

AlphaMask: The alpha mask of an element: a CompositionSurfaceBrush that shows the alpha of what the element draws, for a DropShadow.Mask and other composition effects.
AmbientLight: A light that lights every point of its targets alike (WinUI Microsoft.UI.Composition.AmbientLight): Color times Intensity, both animatable.
AnimationCompletion: The guards of the batches a running animation belongs to. It is Send: it is created on the UI thread with the animation and moved to the server instance of the animation, which releases it when the animation is over.
BatchCompletionGuard: The share of one batch in a running animation: dropping it tells the batch that the animation is over.
CompositingRenderer: A renderer that utilizes a Compositor to render the visual tree.
CompositionBatchCompletedEventArgs: The arguments of the Completed event of a batch (WinUI CompositionBatchCompletedEventArgs, which has no members of its own).
CompositionBatchTypes: Batch types for CompositionCommitBatch and CompositionScopedBatch (WinUI CompositionBatchTypes, a flags enumeration).
CompositionBitmapCache: Caches the subtree of a visual in a bitmap.
CompositionClip: A clip of a visual (WinUI Microsoft.UI.Composition.CompositionClip): the area of the visual that stays visible, with its own animatable transform (AnchorPoint, CenterPoint, Offset, RotationAngle, Scale, TransformMatrix) in the space of the visual.
CompositionCommitBatch: The group of the animations started in the current frame (WinUI CompositionCommitBatch): it is ended when the compositor commits the frame and raises completed once the animations started in the frame are over.
CompositionContainerShape: A shape that groups shapes under its transform (WinUI Microsoft.UI.Composition.CompositionContainerShape): its shapes are drawn in order, in its space.
CompositionCustomVisual: A container visual that draws through a handler on the render thread.
CompositionCustomVisualHandler: The state upstream’s abstract CompositionCustomVisualHandler keeps, and its protected members: what a handler class embeds and returns from ICompositionCustomVisualHandler::handler_base.
CompositionDrawListVisual: The composition visual of a visual of the visual tree: draws what the visual rendered.
CompositionDrawingSurface: A composition surface whose content is set from imported GPU images.
CompositionEllipseGeometry: An ellipse (WinUI Microsoft.UI.Composition.CompositionEllipseGeometry): its center and its radii radius, both animatable (Center, Radius).
CompositionExperimentalAcrylicVisual: A draw list visual that draws an acrylic rectangle below its content.
CompositionGeometry: The geometry of a sprite shape or a geometric clip (WinUI Microsoft.UI.Composition.CompositionGeometry), with the animatable trimming of its outline: TrimStart and TrimEnd (fractions of the length of the outline, default 0 and 1) and TrimOffset (added to both, wrapping around the outline).
CompositionGpuImportedImageSynchronizationCapabilities: The ways the access to an imported GPU image can be synchronized.
CompositionGpuImportedObjectBase: What upstream’s CompositionGpuImportedObjectBase holds on the side of the caller: the compositor, the task of the import and the handle of the server part.
CompositionGradientStop: A gradient stop of the composition brushes, with animatable color and offset.
CompositionImportedGpuImage: A GPU image imported into the compositor.
CompositionImportedGpuSemaphore: A GPU semaphore imported into the compositor.
CompositionInterop: The interop of a compositor with the GPU objects of its render interface context.
CompositionLight: A light (WinUI Microsoft.UI.Composition.CompositionLight): it lights the visuals of targets and their subtrees, minus the visuals of exclusions_from_targets and their subtrees, while it is_enabled. A visual that some enabled light reaches shows its content multiplied by the sum of the lights that reach it, so it is dark where none of them shines.
CompositionLineGeometry: A line (WinUI Microsoft.UI.Composition.CompositionLineGeometry) from start to end, both animatable (Start, End).
CompositionObject: The part every composition object embeds: what upstream’s abstract CompositionObject holds.
CompositionOptions: Options of the composition renderer.
CompositionPath: The path of a CompositionPathGeometry (WinUI Microsoft.UI.Composition.CompositionPath): an immutable platform geometry, made from a FerroUI Geometry (a StreamGeometry, a PathGeometry, …) or from a string of path data.
CompositionPathGeometry: A geometry that shows a CompositionPath (WinUI Microsoft.UI.Composition.CompositionPathGeometry).
CompositionPropertySet: Property sets are composition objects that allow storage of key values pairs that can be shared across the application and are not tied to the lifetime of another composition object. Property sets are most commonly used with animations, where they maintain key-value pairs that are referenced to drive portions of composition animations. Property sets provide the ability to insert key-value pairs or retrieve a value for a given key. A property set does not support a delete function – ensure you use property sets to store values that will be shared across the application.
CompositionRectangleGeometry: A rectangle (WinUI Microsoft.UI.Composition.CompositionRectangleGeometry): (offset, size), both animatable (Offset, Size).
CompositionRoundedRectangleGeometry: A rectangle with rounded corners (WinUI Microsoft.UI.Composition.CompositionRoundedRectangleGeometry): (offset, size) with the elliptical radii corner_radius, all animatable (CornerRadius, Offset, Size). The radii are limited to half the size.
CompositionScopedBatch: An explicitly created group of active animations or effects (WinUI CompositionScopedBatch).
CompositionShape: A shape of a shape visual (WinUI Microsoft.UI.Composition.CompositionShape), with its own animatable transform in the space of its parent (CenterPoint, Offset, RotationAngle, Scale, TransformMatrix), applied as the transform of a visual: the transform matrix, the scale and the rotation about the center point, then the offset.
CompositionShapeCollection: The shapes of a shape visual or of a container shape (WinUI Microsoft.UI.Composition.CompositionShapeCollection), drawn in order.
CompositionSolidColorVisual: A visual that fills its size with a color.
CompositionSpriteShape: A shape that fills and strokes a geometry (WinUI Microsoft.UI.Composition.CompositionSpriteShape).
CompositionSurface: A surface that a surface visual shows. The server-side counterpart provides the bitmap.
CompositionSurfaceVisual: A visual that shows a composition surface.
CompositionTarget: The root of a composition visual tree: what a renderer draws to a render target.
CompositionTileMode
CompositionViewBox: The area of the shape coordinates a shape visual or a geometric clip shows (WinUI Microsoft.UI.Composition.CompositionViewBox): the rectangle (offset, size) of the shapes is mapped onto the visual by stretch and placed by the alignment ratios, as a surface brush lays out its surface. Offset, Size and the ratios are animatable.
CompositionVisual: A node of the composition visual tree.
CompositionVisualCollection: The children of a composition visual.
CompositionVisualSnapshotError: The error of a snapshot that cannot be taken (InvalidOperationException): see Compositor::create_composition_visual_snapshot.
CompositionVisualSurface: A live image of the subtree of a visual, shown by a surface brush (WinUI Microsoft.UI.Composition.CompositionVisualSurface).
Compositor: The compositor: manages the composition objects of the UI thread and commits their changes to the server compositor in batches.
DistantLight: A light from far away in one direction (WinUI Microsoft.UI.Composition.DistantLight): every point of a flat visual is lit alike, by the cosine of the angle between the direction and the visual. Color, Direction and Intensity are animatable.
DropShadow: The shadow of a sprite or layer visual (WinUI Microsoft.UI.Composition.DropShadow), with animatable BlurRadius, Color, Offset and Opacity.
ElementComposition: Access to the composition visuals of the visuals of the visual tree.
GeometricClip: A clip that leaves visible the inside of a geometry (WinUI Microsoft.UI.Composition.GeometricClip), in the coordinates of the visual it is set on, or of its view_box when it has one: the view box maps the geometry onto the size of the visual as for a shape visual. The transform of the clip applies after the view box. A change of the geometry (its trimming and animations included) or of the view box changes the clip.
InsetClip: A clip that leaves visible the rectangle (left_inset, top_inset, width - right_inset, height - bottom_inset) of the visual it is set on (WinUI Microsoft.UI.Composition.InsetClip). The insets are animatable (LeftInset, TopInset, RightInset, BottomInset).
LayerVisual: A container visual whose children are composed into one offscreen layer, which is then drawn with the opacity of the visual and its shadow (WinUI Microsoft.UI.Composition.LayerVisual).
LoadedImageSurface: A composition surface whose content is an image (WinUI Microsoft.UI.Xaml.Media.LoadedImageSurface), here backed by a Bitmap.
MatrixUtils: Helpers computing the transform of a composition visual.
PendingAnimations: The animation instances created on the UI thread (as their factories) that have not been sent to the server yet, by the property they animate.
PointLight: A light from a point (WinUI Microsoft.UI.Composition.PointLight): a point of a visual is lit by the cosine of the angle of the light to the visual, weakened by the attenuation of the distance 1 / (constant + linear * d + quadratic * d^2) between the minimum and the maximum cutoff. Every member but CoordinateSpace is animatable.
RectangleClip: A clip that leaves visible a rectangle, with optional rounded corners, in the coordinates of the visual it is set on (WinUI Microsoft.UI.Composition.RectangleClip). Every member is animatable (Left, Top, Right, Bottom, TopLeftRadius, TopRightRadius, BottomLeftRadius, BottomRightRadius); the radii are elliptical (WinUI Vector2).
RedirectVisual: A visual that shows the subtree of another visual in its own place (WinUI Microsoft.UI.Composition.RedirectVisual): the source keeps rendering where it is, and the redirect visual draws the content and the children of the source again, in its own coordinates, under its own children.
RenderInterfaceFeature: A feature of the platform render interface (Compositor::try_get_render_interface_feature).
ServerGpuImportedObjectBase: What the server part of every imported object holds: the context and the feature the object is imported with, and the outcome of the import.
ServerImportedGpuImage: The server part of an imported GPU image.
ServerImportedGpuSemaphore: The server part of an imported GPU semaphore.
ServerJobTask: The outcome of a job run on the render thread: what Compositor::invoke_server_job_async returns (a task upstream).
ShapeVisual: A visual that draws shapes (WinUI Microsoft.UI.Composition.ShapeVisual): its shapes in order, through its view_box when it has one, then its children.
SpotLight: A light from a point into a cone (WinUI Microsoft.UI.Composition.SpotLight): a point light whose light is the inner cone colour inside the inner cone, falls off to the outer cone colour and to nothing at the edge of the outer cone, and is nothing outside it. The cone angles are measured from the direction to the edge of the cone, in radians. Every member but CoordinateSpace is animatable.
SpriteVisual: A visual that paints its size with a composition brush and casts a shadow (WinUI Microsoft.UI.Composition.SpriteVisual): the shadow of its rectangle, then the brush over (0, 0, size), then its children.
ThemeShadowVisual: The shadow visual of a caster: created by the caster’s Visual, shown by its parent before the caster’s own visual.
VisualUnorderedCollection: A set of visuals (WinUI Microsoft.UI.Composition.VisualUnorderedCollection): the targets or the exclusions of a light.

Enums§

CompositionBackfaceVisibility: Whether the back of a visual rotated in 3D is shown (WinUI CompositionBackfaceVisibility).
CompositionBitmapInterpolationMode: How a bitmap is resampled when a composition surface brush scales it (WinUI CompositionBitmapInterpolationMode).
CompositionBlendMode
CompositionBorderMode: How the edges of a visual are antialiased (WinUI CompositionBorderMode).
CompositionCompositeMode: How a visual is blended with what is behind it (WinUI CompositionCompositeMode).
CompositionDropShadowSourcePolicy: What a drop shadow is cast from (WinUI CompositionDropShadowSourcePolicy).
CompositionGetValueStatus: The result of reading a value of a CompositionPropertySet.
CompositionGradientExtendMode
CompositionMappingMode: How the points of a gradient brush are measured (WinUI CompositionMappingMode).
CompositionStretch: How the content of a composition surface brush fills the area of the brush (WinUI CompositionStretch).
CompositionStrokeCap: The shape at an end of a stroke or of a dash (WinUI CompositionStrokeCap).
CompositionStrokeLineJoin: How the segments of a stroke are joined (WinUI CompositionStrokeLineJoin).
CompositionTransparencyLevel: The level of transparency a composition target is rendered with.
LoadedImageSourceLoadStatus: The outcome of loading a LoadedImageSurface (WinUI Microsoft.UI.Xaml.Media.LoadedImageSourceLoadStatus).

Constants§

ALPHA_MASK_MAX_SIZE: The largest side of the image of a mask, in pixels. A mask that would be larger is drawn smaller, and its brush scaled back up.

Traits§

AsCompositionObject: A composition object as code refers to any composition object: a reference parameter of an animation, an object stored in a property set (upstream CompositionObject as a parameter type).
ICompositionCustomVisualHandler: The overridable members of a custom visual handler. A handler class embeds a CompositionCustomVisualHandler and implements this trait.
ICompositionDrawListVisualExtension: What a class derived from the draw list visual outside of this module (the custom composition visual of a control) adds to its UI-thread side: the serialization of its own changes.
ICompositionGpuImportedObject: An imported GPU object that’s usable by composition APIs
ICompositionGpuInterop: The import of GPU objects created outside of the framework into the compositor.
ICompositionImportableSharedGpuContextImage: An GPU image descriptor obtained from a context from the same share group as one used by the compositor
ICompositionImportableSharedGpuContextObject: An GPU object descriptor obtained from a context from the same share group as one used by the compositor
ICompositionImportableSharedGpuContextSemaphore: An GPU semaphore descriptor obtained from a context from the same share group as one used by the compositor
ICompositionImportedGpuImage: An imported GPU image object that’s usable by composition APIs
ICompositionImportedGpuSemaphore: An imported GPU semaphore object that’s usable by composition APIs
ICompositionObject: A UI-thread composition object as other composition objects refer to it: something with a server-side counterpart.
ICompositionObjectAnimations: The animation members of CompositionObject, written against the class that embeds one.
ICompositionObjectHost: What a generated client property block needs from the composition object that embeds it (the members of upstream CompositionObject the generated code uses).
ICompositionSurface: A surface a composition surface brush shows (WinUI ICompositionSurface): a CompositionSurface (a drawing surface), a CompositionVisualSurface or a LoadedImageSurface.
ICompositionTargetDebugEvents: Receives debugging information from a composition target while it renders a frame.
ICompositorScheduler: Receives the request to commit a compositor’s pending changes; the media context implements it and schedules the commit with the next frame.
ICompositorSerializable: An object whose changes are serialized into the next batch of a compositor.
IServerGpuImportedObject: The server part of an imported object: what the jobs of the render thread import, use and dispose.

Type Aliases§

CompositionCacheMode: The cache mode of a composition visual.
CompositionContainerVisual: A visual that can have children: every visual.
LocalFuture: A future of the thread of the compositor: what its asynchronous members return (a ValueTask upstream), awaited on that thread.
ServerJobError: The error of a job run on the render thread: it crosses to the thread that asked for the job.