ferroui_base/rendering/composition/
mod.rs

1//! The composition renderer.
2//!
3//! # Architecture and threading
4//!
5//! As upstream, there are two compositors. The [`Compositor`] lives on the
6//! UI thread together with the composition objects; the
7//! [`server::ServerCompositor`] owns the server-side counterparts of those
8//! objects and renders them. They exchange data in one direction only,
9//! through batches: at commit the UI-thread compositor serializes the
10//! changes of its objects into a [`transport::CommittedBatch`] and enqueues
11//! it; at the start of each frame the server compositor applies the queued
12//! batches.
13//!
14//! The object model of the UI thread is `Rc`-based and thread-affine, so
15//! the two sides are kept apart by construction rather than by locks:
16//!
17//! * UI-thread objects never hold their server counterpart. They hold a
18//!   [`server::ServerObjectId`], a plain value. A server object is created
19//!   by the server compositor itself, from a factory carried by the batch
20//!   ([`Compositor::create_server_object`]); changes and disposal refer to
21//!   it by id. Server objects therefore need not be `Send`: they are
22//!   created, mutated and dropped on the render thread only.
23//! * The batch queue ([`server::BatchQueue`]) is the only crossing point.
24//!   What may cross is exactly what a [`transport::BatchObject`] can hold
25//!   plus plain values.
26//! * The few values the UI thread reads back (the clock, the readback
27//!   indices, batch completion) are `Send + Sync` types shared through
28//!   `Arc`.
29//!
30//! Today the server compositor runs on the thread of its compositor in
31//! every configuration: the render loop may tick on any thread (its tasks
32//! are `Send + Sync`), and a tick that arrives elsewhere is marshalled to
33//! the compositor's dispatcher. Running the server on a dedicated render
34//! thread is blocked by one thing outside this module: the platform
35//! resource handles carried by batches (`std::sync::Arc<dyn IGeometryImpl>`,
36//! `std::sync::Arc<crate::platform::SharedBitmapImpl>`, `std::sync::Arc<dyn IGlyphRunImpl>`, immutable brushes and
37//! pens) are `Rc`-based and so are the render contracts the server draws
38//! with. Once those are shareable across threads, the remaining steps are
39//! local: require `Send` on the `Job`, `Create` and `Value` payloads of
40//! `BatchObject`, make the batch queue a mutex-protected queue, and
41//! construct the server compositor on the render thread. No `unsafe` is
42//! used anywhere in the composition renderer.
43//!
44//! The browser target has no threads; it uses the same single-thread mode
45//! with a UI-thread render timer.
46
47pub mod animations;
48pub mod brushes;
49pub mod drawing;
50pub mod effects;
51pub mod system_backdrops;
52pub mod expressions;
53pub mod generated;
54pub mod hit_testing;
55pub mod interactions;
56pub mod server;
57#[cfg(any(test, feature = "testing"))]
58pub mod testing;
59pub mod transport;
60
61mod alpha_mask;
62mod composition_batch;
63mod composition_cache_mode;
64mod composition_clip;
65mod composition_custom_visual;
66mod composition_custom_visual_handler;
67mod composition_draw_list_visual;
68mod composition_drawing_surface;
69mod composition_external_memory;
70mod composition_interop;
71mod composition_experimental_acrylic_visual;
72mod composition_geometry;
73mod composition_light;
74mod composition_gradient_stop;
75mod composition_object;
76mod composition_object_impls;
77mod composition_options;
78mod composition_property_set;
79mod composition_shape;
80mod composition_shape_factories;
81mod composition_solid_color_visual;
82mod composition_surface;
83mod composition_surface_visual;
84mod composition_target;
85mod composition_view_box;
86mod composition_visual_surface;
87mod composition_winui_factories;
88mod composition_visual_winui;
89mod composition_winui_enums;
90mod composition_winui_layer_factories;
91mod layer_visual;
92mod redirect_visual;
93mod compositing_renderer;
94mod compositor_factories;
95mod container_visual;
96mod drop_shadow;
97mod i_composition_surface;
98mod loaded_image_surface;
99mod shape_visual;
100mod sprite_visual;
101mod element_composition_preview;
102mod theme_shadow_visual;
103mod visual;
104mod visual_collection;
105mod composition_transparency_level;
106mod compositor;
107mod enums;
108mod i_composition_object_host;
109mod i_composition_target_debug_events;
110mod i_compositor_serializable;
111mod matrix_utils;
112mod render_interface_feature;
113
114pub use alpha_mask::{AlphaMask, ALPHA_MASK_MAX_SIZE};
115pub use composition_batch::{
116    AnimationCompletion, BatchCompletionGuard, CompositionBatchCompletedEventArgs, CompositionBatchTypes,
117    CompositionCommitBatch, CompositionScopedBatch,
118};
119pub use composition_cache_mode::{CompositionBitmapCache, CompositionCacheMode};
120pub use composition_custom_visual::CompositionCustomVisual;
121pub use composition_custom_visual_handler::{CompositionCustomVisualHandler, ICompositionCustomVisualHandler};
122pub use composition_drawing_surface::CompositionDrawingSurface;
123pub use composition_external_memory::{
124    CompositionGpuImportedImageSynchronizationCapabilities, ICompositionGpuImportedObject, ICompositionGpuInterop,
125    ICompositionImportableSharedGpuContextImage, ICompositionImportableSharedGpuContextObject,
126    ICompositionImportableSharedGpuContextSemaphore, ICompositionImportedGpuImage, ICompositionImportedGpuSemaphore,
127};
128pub use composition_interop::{
129    CompositionGpuImportedObjectBase, CompositionImportedGpuImage, CompositionImportedGpuSemaphore, CompositionInterop,
130    IServerGpuImportedObject, ServerGpuImportedObjectBase, ServerImportedGpuImage,
131    ServerImportedGpuSemaphore,
132};
133pub use composition_draw_list_visual::{CompositionDrawListVisual, ICompositionDrawListVisualExtension};
134pub use brushes::{
135    CompositionBrush, CompositionConicGradientBrush, CompositionGradientBrush, CompositionLinearGradientBrush,
136    CompositionRadialGradientBrush, CompositionSolidColorBrush, CompositionSurfaceBrush,
137};
138pub use composition_clip::{CompositionClip, GeometricClip, InsetClip, RectangleClip};
139pub use composition_geometry::{
140    CompositionEllipseGeometry, CompositionGeometry, CompositionLineGeometry, CompositionPath, CompositionPathGeometry,
141    CompositionRectangleGeometry, CompositionRoundedRectangleGeometry,
142};
143pub use composition_shape::{
144    CompositionContainerShape, CompositionShape, CompositionShapeCollection, CompositionSpriteShape, CompositionStrokeCap,
145    CompositionStrokeLineJoin,
146};
147pub use composition_view_box::CompositionViewBox;
148pub use shape_visual::ShapeVisual;
149pub use brushes::{CompositionMaskBrush, CompositionNineGridBrush};
150// The WinUI effect brushes (phase 6); the effect descriptions and the
151// factory are in `effects`.
152pub use brushes::{CompositionBackdropBrush, CompositionEffectBrush, CompositionHostBackdropBrush};
153pub use effects::{
154    CompositionEffectFactory, CompositionEffectFactoryError, CompositionEffectFactoryLoadStatus,
155    CompositionEffectSourceParameter,
156};
157pub use composition_winui_enums::{
158    CompositionBackfaceVisibility, CompositionBorderMode, CompositionCompositeMode, CompositionMappingMode,
159};
160pub use layer_visual::LayerVisual;
161pub use redirect_visual::RedirectVisual;
162pub use composition_visual_surface::CompositionVisualSurface;
163pub use drop_shadow::DropShadow;
164pub use composition_light::{
165    AmbientLight, CompositionLight, DistantLight, PointLight, SpotLight, VisualUnorderedCollection,
166};
167pub use i_composition_surface::ICompositionSurface;
168pub use loaded_image_surface::{LoadedImageSourceLoadStatus, LoadedImageSurface};
169pub use sprite_visual::SpriteVisual;
170pub use composition_experimental_acrylic_visual::CompositionExperimentalAcrylicVisual;
171pub use composition_gradient_stop::CompositionGradientStop;
172pub use composition_object::{AsCompositionObject, CompositionObject, ICompositionObjectAnimations};
173pub use composition_options::CompositionOptions;
174pub use composition_property_set::{CompositionGetValueStatus, CompositionPropertySet};
175pub use composition_solid_color_visual::CompositionSolidColorVisual;
176pub use composition_surface::CompositionSurface;
177pub use composition_surface_visual::CompositionSurfaceVisual;
178pub use composition_target::CompositionTarget;
179pub use compositing_renderer::CompositingRenderer;
180pub use container_visual::CompositionContainerVisual;
181pub use element_composition_preview::ElementComposition;
182pub use theme_shadow_visual::ThemeShadowVisual;
183pub use server::RenderSurfaces;
184pub use visual::CompositionVisual;
185pub use visual_collection::CompositionVisualCollection;
186pub use composition_transparency_level::CompositionTransparencyLevel;
187pub use compositor::{
188    CompositionVisualSnapshotError, Compositor, ICompositorScheduler, LocalFuture, ServerJobError, ServerJobTask,
189};
190pub use enums::{
191    CompositionBitmapInterpolationMode, CompositionBlendMode, CompositionDropShadowSourcePolicy,
192    CompositionGradientExtendMode, CompositionStretch, CompositionTileMode,
193};
194pub use i_composition_object_host::{ICompositionObject, ICompositionObjectHost, PendingAnimations};
195pub use i_composition_target_debug_events::ICompositionTargetDebugEvents;
196pub use i_compositor_serializable::ICompositorSerializable;
197pub use matrix_utils::MatrixUtils;
198pub use render_interface_feature::RenderInterfaceFeature;
199// The key frame animation classes are generated into the namespace of the
200// compositor upstream.
201pub use animations::{
202    BooleanKeyFrameAnimation, ColorKeyFrameAnimation, DoubleKeyFrameAnimation, QuaternionKeyFrameAnimation,
203    RelativePointKeyFrameAnimation, RelativeScalarKeyFrameAnimation, ScalarKeyFrameAnimation, Vector2KeyFrameAnimation,
204    Vector3DKeyFrameAnimation, Vector3KeyFrameAnimation, Vector4KeyFrameAnimation, VectorKeyFrameAnimation,
205};
206// The WinUI animation types of `Microsoft.UI.Composition` that are not in the
207// schema: the natural motion animations, the animation controller and the
208// colour space of colour animations.
209pub use animations::{
210    AnimationController, AnimationControllerProgressBehavior, CompositionColorSpace, NaturalMotionAnimation,
211    ScalarNaturalMotionAnimation, SpringScalarNaturalMotionAnimation, SpringVector2NaturalMotionAnimation,
212    SpringVector3NaturalMotionAnimation, Vector2NaturalMotionAnimation, Vector3NaturalMotionAnimation,
213};
214
215#[cfg(test)]
216mod composition_property_set_tests;
217#[cfg(test)]
218mod composition_batch_tests;
219#[cfg(test)]
220mod compositor_tests;
221#[cfg(test)]
222mod render_thread_tests;
223#[cfg(test)]
224mod composition_drawing_surface_tests;
225#[cfg(test)]
226pub(crate) mod test_compositor;
ferroui_base/rendering/composition/mod.rs

ferroui_base/rendering/composition/
mod.rs
