Struct Compositor 

pub struct Compositor { /* private fields */ }

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

Implementations

impl Compositor

pub const MAX_GLOBAL_PLAYBACK_RATE: f32 = 1000.0

The highest global playback rate (WinUI MaxGlobalPlaybackRate).

pub const MIN_GLOBAL_PLAYBACK_RATE: f32 = 0.0

The lowest global playback rate (WinUI MinGlobalPlaybackRate).

pub fn create_animation_controller(&self) -> Rc<AnimationController>

Creates an animation controller (WinUI CreateAnimationController).

pub fn global_playback_rate(&self) -> f32

The rate at which the time of every animation of the compositor runs (WinUI GlobalPlaybackRate): 1 by default, 0.5 for half speed.

pub fn set_global_playback_rate(&self, value: f32)

Sets the global playback rate, clamped to MIN_GLOBAL_PLAYBACK_RATE..MAX_GLOBAL_PLAYBACK_RATE. It applies from the next frame to running animations and to those started later: their time from then on runs at the new rate.

impl Compositor

The easing factories of WinUI Compositor. They return the typed function (Rc), which key frames take as it is (insert_key_frame_with_easing) or as an Easing (.into()).

pub fn create_cubic_bezier_easing_function( &self, control_point1: Vector2, control_point2: Vector2, ) -> Rc<CubicBezierEasingFunction>

A cubic Bezier curve with the given control points (WinUI CreateCubicBezierEasingFunction).

pub fn create_linear_easing_function(&self) -> Rc<LinearEasingFunction>

The linear curve (WinUI CreateLinearEasingFunction).

pub fn create_step_easing_function(&self) -> Rc<StepEasingFunction>

A step function with one step (WinUI CreateStepEasingFunction()).

pub fn create_step_easing_function_with_step_count( &self, step_count: i32, ) -> Rc<StepEasingFunction>

A step function with step_count steps (WinUI CreateStepEasingFunction(stepCount)).

impl Compositor

pub fn create_scalar_key_frame_animation(&self) -> Rc<ScalarKeyFrameAnimation>

impl Compositor

pub fn create_double_key_frame_animation(&self) -> Rc<DoubleKeyFrameAnimation>

impl Compositor

pub fn create_boolean_key_frame_animation(&self) -> Rc<BooleanKeyFrameAnimation>

impl Compositor

pub fn create_color_key_frame_animation(&self) -> Rc<ColorKeyFrameAnimation>

impl Compositor

pub fn create_vector_key_frame_animation(&self) -> Rc<VectorKeyFrameAnimation>

impl Compositor

pub fn create_vector2_key_frame_animation(&self) -> Rc<Vector2KeyFrameAnimation>

impl Compositor

pub fn create_vector3_key_frame_animation(&self) -> Rc<Vector3KeyFrameAnimation>

impl Compositor

pub fn create_vector3d_key_frame_animation( &self, ) -> Rc<Vector3DKeyFrameAnimation>

impl Compositor

pub fn create_vector4_key_frame_animation(&self) -> Rc<Vector4KeyFrameAnimation>

impl Compositor

pub fn create_quaternion_key_frame_animation( &self, ) -> Rc<QuaternionKeyFrameAnimation>

impl Compositor

pub fn create_relative_point_key_frame_animation( &self, ) -> Rc<RelativePointKeyFrameAnimation>

impl Compositor

pub fn create_relative_scalar_key_frame_animation( &self, ) -> Rc<RelativeScalarKeyFrameAnimation>

impl Compositor

pub fn create_spring_scalar_animation( &self, ) -> Rc<SpringScalarNaturalMotionAnimation>

Creates a SpringScalarNaturalMotionAnimation.

impl Compositor

pub fn create_spring_vector2_animation( &self, ) -> Rc<SpringVector2NaturalMotionAnimation>

Creates a SpringVector2NaturalMotionAnimation.

impl Compositor

pub fn create_spring_vector3_animation( &self, ) -> Rc<SpringVector3NaturalMotionAnimation>

Creates a SpringVector3NaturalMotionAnimation.

impl Compositor

pub fn create_effect_factory( &self, effect: impl Into<GraphicsEffect>, ) -> Rc<CompositionEffectFactory>

CreateEffectFactory(graphicsEffect): a factory of brushes that draw effect, without animatable properties.

pub fn create_effect_factory_with_properties( &self, effect: impl Into<GraphicsEffect>, animatable_properties: &[&str], ) -> Rc<CompositionEffectFactory>

CreateEffectFactory(graphicsEffect, animatableProperties): a factory of brushes that draw effect, whose properties named in animatable_properties (EffectName.PropertyName, as Blur.BlurAmount) can be changed and animated on the brushes.

pub fn create_backdrop_brush(&self) -> CompositionBackdropBrush

CreateBackdropBrush: a brush that shows what is behind the visual that paints it: the compositor draws again what was drawn under the visual (winui-materials.md, the backdrop).

pub fn create_host_backdrop_brush(&self) -> CompositionHostBackdropBrush

CreateHostBackdropBrush: a brush that shows what is behind the window (see CompositionHostBackdropBrush).

impl Compositor

pub fn create_scoped_batch( &self, batch_type: CompositionBatchTypes, ) -> Rc<CompositionScopedBatch>

Creates a scoped batch that aggregates the animations of the given types started from now on (WinUI CreateScopedBatch).

pub fn get_commit_batch( &self, batch_type: CompositionBatchTypes, ) -> Rc<CompositionCommitBatch>

The batch of the animations started in the current frame, which the next commit ends (WinUI GetCommitBatch). The animations started in the frame before the call belong to it too. A commit is requested, so the batch ends even if nothing else changes.

pub fn create_property_set(&self) -> Rc<CompositionPropertySet>

Creates a property set (WinUI CreatePropertySet).

impl Compositor

pub fn create_ambient_light(&self) -> AmbientLight

CreateAmbientLight.

pub fn create_distant_light(&self) -> DistantLight

CreateDistantLight.

pub fn create_point_light(&self) -> PointLight

CreatePointLight.

pub fn create_spot_light(&self) -> SpotLight

CreateSpotLight.

impl Compositor

pub fn create_shape_visual(&self) -> ShapeVisual

CreateShapeVisual: a visual that draws shapes.

pub fn create_sprite_shape(&self) -> CompositionSpriteShape

CreateSpriteShape: a shape without a geometry.

pub fn create_sprite_shape_with_geometry( &self, geometry: Option<Rc<CompositionGeometry>>, ) -> CompositionSpriteShape

CreateSpriteShape(geometry): a shape that draws geometry.

pub fn create_container_shape(&self) -> CompositionContainerShape

CreateContainerShape: a shape that groups shapes.

pub fn create_rectangle_geometry(&self) -> CompositionRectangleGeometry

CreateRectangleGeometry: an empty rectangle at the origin.

pub fn create_rounded_rectangle_geometry( &self, ) -> CompositionRoundedRectangleGeometry

CreateRoundedRectangleGeometry: an empty rounded rectangle at the origin.

pub fn create_ellipse_geometry(&self) -> CompositionEllipseGeometry

CreateEllipseGeometry: an ellipse with zero radii at the origin.

pub fn create_line_geometry(&self) -> CompositionLineGeometry

CreateLineGeometry: a line from the origin to the origin.

pub fn create_path_geometry(&self) -> CompositionPathGeometry

CreatePathGeometry: a geometry without a path.

pub fn create_path_geometry_with_path( &self, path: Option<CompositionPath>, ) -> CompositionPathGeometry

CreatePathGeometry(path): a geometry that shows path.

pub fn create_view_box(&self) -> Rc<CompositionViewBox>

CreateViewBox: a view box with a zero size.

pub fn create_geometric_clip(&self) -> GeometricClip

CreateGeometricClip: a clip without a geometry.

pub fn create_geometric_clip_with_geometry( &self, geometry: Option<Rc<CompositionGeometry>>, ) -> GeometricClip

CreateGeometricClip(geometry): a clip to the inside of geometry.

impl Compositor

pub fn create_sprite_visual(&self) -> SpriteVisual

CreateSpriteVisual: a visual that paints its size with a brush.

pub fn create_color_brush(&self) -> CompositionSolidColorBrush

CreateColorBrush: the WinUI name of create_solid_color_brush.

pub fn create_color_brush_with_color( &self, color: Color, ) -> CompositionSolidColorBrush

CreateColorBrush(color): the WinUI name of create_solid_color_brush_with.

pub fn create_surface_brush(&self) -> CompositionSurfaceBrush

CreateSurfaceBrush: a brush that paints a surface, without a surface.

pub fn create_surface_brush_with_surface( &self, surface: Rc<dyn ICompositionSurface>, ) -> CompositionSurfaceBrush

CreateSurfaceBrush(surface): a brush that paints surface.

pub fn create_visual_surface(&self) -> Rc<CompositionVisualSurface>

CreateVisualSurface: a live image of the subtree of a visual.

pub fn create_drop_shadow(&self) -> Rc<DropShadow>

CreateDropShadow: a shadow for a sprite visual.

pub fn create_inset_clip(&self) -> InsetClip

CreateInsetClip: a clip with zero insets.

pub fn create_inset_clip_with_insets( &self, left: f32, top: f32, right: f32, bottom: f32, ) -> InsetClip

CreateInsetClip(leftInset, topInset, rightInset, bottomInset).

pub fn create_rectangle_clip(&self) -> RectangleClip

CreateRectangleClip: a clip whose edges are all zero (it leaves nothing visible until its edges are set).

pub fn create_rectangle_clip_with( &self, left: f32, top: f32, right: f32, bottom: f32, ) -> RectangleClip

CreateRectangleClip(left, top, right, bottom).

pub fn create_rectangle_clip_with_radii( &self, left: f32, top: f32, right: f32, bottom: f32, top_left_radius: Vector, top_right_radius: Vector, bottom_right_radius: Vector, bottom_left_radius: Vector, ) -> RectangleClip

CreateRectangleClip(left, top, right, bottom, topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius).

impl Compositor

pub fn create_layer_visual(&self) -> LayerVisual

CreateLayerVisual: a container visual whose children are composed into one layer.

pub fn create_redirect_visual(&self) -> RedirectVisual

CreateRedirectVisual: a visual that shows the subtree of another visual, without a source.

pub fn create_redirect_visual_with_source_visual( &self, source: Option<Rc<CompositionVisual>>, ) -> RedirectVisual

CreateRedirectVisual(source): a visual that shows the subtree of source.

pub fn create_nine_grid_brush(&self) -> CompositionNineGridBrush

CreateNineGridBrush: a brush that paints another brush as a nine-grid.

pub fn create_mask_brush(&self) -> CompositionMaskBrush

CreateMaskBrush: a brush that paints a brush through the alpha of another.

pub fn create_color_gradient_stop( &self, offset: f32, color: Color, ) -> Rc<CompositionGradientStop>

CreateColorGradientStop(offset, color): the WinUI name of create_gradient_stop_with.

pub fn create_color_gradient_stop_default(&self) -> Rc<CompositionGradientStop>

CreateColorGradientStop(): the WinUI name of create_gradient_stop.

impl Compositor

pub fn create_composition_target( &self, surfaces: RenderSurfaces, ) -> Rc<CompositionTarget>

Creates a composition target that renders to one of the surfaces surfaces returns.

pub fn create_container_visual(&self) -> Rc<CompositionContainerVisual>

pub fn create_expression_animation(&self) -> Rc<ExpressionAnimation>

pub fn create_expression_animation_with( &self, expression: &str, ) -> Rc<ExpressionAnimation>

pub fn create_implicit_animation_collection( &self, ) -> Rc<ImplicitAnimationCollection>

pub fn create_animation_group(&self) -> Rc<CompositionAnimationGroup>

pub fn create_solid_color_visual(&self) -> CompositionSolidColorVisual

pub fn create_custom_visual( &self, handler: impl FnOnce() -> Rc<dyn ICompositionCustomVisualHandler> + Send + 'static, ) -> CompositionCustomVisual

The handler belongs to the render thread: handler creates it there.

pub fn create_drawing_surface(&self) -> CompositionDrawingSurface

pub fn create_surface_visual(&self) -> CompositionSurfaceVisual

pub fn create_solid_color_brush(&self) -> CompositionSolidColorBrush

pub fn create_solid_color_brush_with( &self, color: Color, ) -> CompositionSolidColorBrush

pub fn create_linear_gradient_brush(&self) -> CompositionLinearGradientBrush

pub fn create_conic_gradient_brush(&self) -> CompositionConicGradientBrush

pub fn create_radial_gradient_brush(&self) -> CompositionRadialGradientBrush

pub fn create_gradient_stop_with( &self, offset: f64, color: Color, ) -> Rc<CompositionGradientStop>

pub fn create_gradient_stop(&self) -> Rc<CompositionGradientStop>

impl Compositor

pub fn with_render_thread( render_loop: Arc<dyn IRenderLoop>, gpu: Option<Arc<dyn IPlatformGraphics>>, use_ui_thread_for_synchronous_commits: bool, scheduler: &Rc<dyn ICompositorScheduler>, dispatcher: Arc<Dispatcher>, options: Option<CompositionOptions>, clock: Option<Arc<dyn Fn() -> Duration + Send + Sync>>, ) -> Rc<Compositor>

Creates a compositor in the render-thread mode: the thread that ticks render_loop renders the frames.

The server compositor is confined to the compositor lock, not to a thread: with use_ui_thread_for_synchronous_commits the thread of this compositor renders too, at the synchronous points (a resize, the first show), as the reference does on platforms that ask for it.

Without it, and with a loop that runs in the background, the server compositor is also confined to the thread that ticks (see is_confined_to_render_thread). The loop says where it runs when the compositor is created.

gpu is shared with the caller, who may keep its handle: the server side holds one of its own and the thread that renders asks it for the graphics context.

pub fn new( gpu: Option<Arc<dyn IPlatformGraphics>>, use_ui_thread_for_synchronous_commits: bool, ) -> Rc<Compositor>

Creates a compositor that renders on the render loop registered in the service locator and commits through the media context.

The threads follow the render loop, as in the reference: with a loop that runs in the background (the thread of the platform’s render timer) that thread renders the frames, under the compositor lock (the render-thread mode); with a loop of the UI thread the UI thread renders. FERROUI_RENDER_THREAD=0 in the environment keeps the rendering on the UI thread with a background loop too (each tick is marshalled to it): a way back while the mode is young.

pub fn with_scheduler( render_loop: Arc<dyn IRenderLoop>, gpu: Option<Arc<dyn IPlatformGraphics>>, use_ui_thread_for_synchronous_commits: bool, scheduler: &Rc<dyn ICompositorScheduler>, dispatcher: Arc<Dispatcher>, options: Option<CompositionOptions>, clock: Option<CompositorClock>, ) -> Rc<Compositor>

Creates a compositor with every collaborator given explicitly.

options defaults to the options registered in the service locator; clock defaults to the dispatcher’s clock.

pub fn render_loop(&self) -> &Arc<dyn IRenderLoop>

The render loop the server compositor is driven by.

pub fn use_ui_thread_for_synchronous_commits(&self) -> bool

pub fn server(&self) -> &Rc<ServerCompositor>

The server compositor. It belongs to the render thread: UI-thread code may only use it to drive a frame when the render loop runs on the UI thread, and in tests.

pub fn with_server<R>(&self, f: impl FnOnce(&Rc<ServerCompositor>) -> R) -> R

Runs f with the server compositor under the compositor lock: the way in from this thread in either mode. What f gets must not leave it.

pub fn locked_server(&self) -> Arc<LockedServerCompositor>

The server compositor behind its lock, as a handle that may cross to the thread that renders: for work of that thread that cannot be a job of a batch, because it has to run whether or not this compositor commits again and whether or not its graphics are ready (the release of a surface that is closed). The work enters the graph with try_with, which answers None once the graph is released.

Not from upstream, where such work captures the server compositor itself.

pub fn render_on_this_thread(&self) -> bool

Renders a frame on this thread, under the compositor lock: what the synchronous points do (Server.Render upstream).

Panics

When the compositor is confined to its render thread: this thread waits for a frame there, it never renders one.

pub fn renders_on_render_thread(&self) -> bool

Whether the thread that ticks the render loop renders the frames, not the thread of this compositor.

pub fn is_confined_to_render_thread(&self) -> bool

Whether the thread that ticks the render loop is the only one that renders: the render-thread mode without use_ui_thread_for_synchronous_commits, on a loop that runs in the background (the condition under which the reference waits for the render thread at the synchronous points).

The render targets, the graphics context and everything else that belongs to the thread that draws are then created, used and dropped by the render thread alone. This thread still enters the compositor lock (with_server), for what does not render: it commits batches, posts jobs and waits for them.

pub fn readback(&self) -> &Arc<ReadbackIndices>

The readback indices the server writes and this side reads.

pub fn dispatcher(&self) -> &Arc<Dispatcher>

The dispatcher of the thread the compositor belongs to.

pub fn clock_elapsed(&self) -> Duration

The time elapsed on the compositor clock.

pub fn after_commit(&self, handler: impl Fn() + 'static) -> Rc<dyn IDisposable>

Subscribes to the notification raised after each commit.

pub fn request_composition_batch_commit_async(&self) -> Arc<CompositionBatch>

Requests the pending changes to be committed and returns the batch they will be part of.

pub fn request_commit_async(&self) -> Arc<CompositionBatch>

Requests the pending changes to be committed.

pub fn commit(&self) -> Arc<CompositionBatch>

Serializes the pending changes into a batch and hands it to the server compositor.

pub fn create_server_object( &self, factory: impl FnOnce(&Rc<ServerCompositor>, ServerObjectId) -> Rc<dyn IServerObject> + Send + 'static, ) -> ServerObjectId

Allocates the id of a new server object and queues its creation for the next batch. factory runs on the render thread.

pub fn register_for_serialization( &self, composition_object: Rc<dyn ICompositorSerializable>, )

Queues an object whose changes must be written to the next batch.

pub fn dispose_on_next_batch(&self, obj: ServerObjectId)

Disposes a server object with the next batch, and releases it: the server compositor drops it and its id can be reused.

pub fn request_composition_update(&self, action: impl FnOnce() + 'static)

Enqueues a callback to be run before the next commit.

pub fn post_server_job( &self, job: impl FnOnce(&ServerCompositor) + Send + 'static, post_target: bool, )

Posts a job that runs on the render thread with the next batch: before the composition targets are rendered, or after them when post_target is set.

pub fn post_server_object_job( &self, target: ServerObjectId, job: impl FnOnce(&ServerCompositor, Option<Rc<dyn IServerObject>>) + Send + 'static, post_target: bool, )

Posts a job that runs on the render thread with the next batch and receives the server object target (None when it does not exist). Upstream a job holds the server object itself; this job names it, and the object is resolved when the batch is read, so the job reaches an object that the same batch disposes.

pub fn invoke_server_object_job_async<T: Send + 'static>( &self, target: ServerObjectId, job: impl FnOnce(&ServerCompositor, Option<Rc<dyn IServerObject>>) -> Result<T, ServerJobError> + Send + 'static, post_target: bool, ) -> ServerJobTask<T>

invoke_server_job_async with a job that receives the server object target; see post_server_object_job.

pub fn invoke_server_job_async<T: Send + 'static>( &self, job: impl FnOnce(&ServerCompositor) -> Result<T, ServerJobError> + Send + 'static, post_target: bool, ) -> ServerJobTask<T>

Runs job on the render thread with the next batch and returns a task that completes with its result (InvokeServerJobAsync). A job that fails faults the task with its error.

pub fn create_composition_visual_snapshot( &self, visual: &CompositionVisual, scaling: f64, ) -> ServerJobTask<Bitmap>

Renders a visual and its children into a new bitmap, on the render thread with the next batch, after the composition targets are rendered (CreateCompositionVisualSnapshot).

The task is faulted with a CompositionVisualSnapshotError when the visual belongs to another compositor or is not attached to a composition target (InvalidOperationException upstream, which the asynchronous method also reports through its task).

pub fn try_get_render_interface_feature( &self, feature_type: TypeId, ) -> LocalFuture<Option<RenderInterfaceFeature>>

Attempts to query for a feature from the platform render interface (TryGetRenderInterfaceFeature): a future that completes with the feature, or None when the render interface has none. Awaited on the thread of the compositor; see get_render_interface_public_features for when it completes.

Upstream hands out the feature object itself, which the two threads then share. Here the feature is an Rc of the server side, so what is handed out is a RenderInterfaceFeature: a handle to the same feature that stays inside the compositor lock and lends the feature there. It keeps the feature alive as the object upstream does.

pub fn try_get_composition_gpu_interop( &self, ) -> LocalFuture<Option<Rc<dyn ICompositionGpuInterop>>>

Attempts to query for the GPU interop feature from the platform render interface (TryGetCompositionGpuInterop): a future that completes with the interop with GPU objects created outside of the framework, or None when the render interface does not support it. Awaited on the thread of the compositor.

Upstream awaits the feature (TryGetRenderInterfaceFeature) and constructs the interop where the await continues: on the render thread, when a job of the render thread gave the feature. Here the feature is an object of the server side: the server part of the interop is made from it inside the lock, where the feature is read (in that job, for a confined compositor without a cache), and this thread makes the interop around it.

pub fn unit_test_is_registered_for_serialization( &self, serializable: &dyn ICompositorSerializable, ) -> bool

Whether an object is queued for serialization (for unit tests).

pub fn try_get_default_compositor() -> Option<Rc<Compositor>>

The compositor registered in the service locator, if any.

Trait Implementations

impl Drop for Compositor

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.