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