Module composition 

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 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;

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).

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.

server

The server (render thread) side of the composition renderer.

transport

The transport between the UI-thread compositor and the server compositor: batches of serialized changes.

Structs

CompositingRenderer

A renderer that utilizes a Compositor to render the visual tree.

CompositionBitmapCache

Caches the subtree of a visual in a bitmap.

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.

CompositionExperimentalAcrylicVisual

A draw list visual that draws an acrylic rectangle below its content.

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.

CompositionObject

The part every composition object embeds: what upstream’s abstract CompositionObject holds.

CompositionOptions

Options of the composition renderer.

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.

CompositionSolidColorVisual

A visual that fills its size with a color.

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

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.

Compositor

The compositor: manages the composition objects of the UI thread and commits their changes to the server compositor in batches.

ElementComposition

Access to the composition visuals of the visuals of the visual tree.

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.

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).

Enums

CompositionBlendMode

CompositionGetValueStatus

The result of reading a value of a CompositionPropertySet.

CompositionGradientExtendMode

CompositionStretch

CompositionTransparencyLevel

The level of transparency a composition target is rendered with.

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).

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.