cranpose_render_common/lib.rs
1//! Common rendering contracts shared between renderer backends.
2
3mod annotated_text;
4mod ascii_glyphs;
5pub mod debug_toggles;
6pub mod dev_overlay;
7mod direct_mapped_cache;
8
9/// The frame background every renderer clears to (linear values; sRGB
10/// surfaces display this as rgb(75, 75, 86)). One definition so backends
11/// cannot drift.
12pub const FRAME_CLEAR_COLOR: [f32; 4] = [18.0 / 255.0, 18.0 / 255.0, 24.0 / 255.0, 1.0];
13pub mod brush_sampling;
14mod font_features;
15pub mod font_layout;
16pub mod font_source;
17mod font_tracking;
18pub mod geometry;
19pub mod gpos_kerning;
20pub mod graph;
21mod graph_hash;
22pub mod graph_scene;
23pub mod hit_graph;
24pub mod image_compare;
25pub mod layer_composition;
26mod layer_recycling;
27pub mod layer_shadow;
28pub mod layer_transform;
29pub mod primitive_emit;
30pub mod raster_cache;
31pub mod render_contract;
32pub mod scene_builder;
33pub mod shape_sdf;
34pub mod software_text_raster;
35pub mod style_shared;
36mod text_cache_key;
37pub mod text_hyphenation;
38pub mod text_mask_gamma;
39pub mod text_measure;
40
41#[cfg(test)]
42#[path = "tests/pointer_slices.rs"]
43mod pointer_slices;
44
45use cranpose_core::{MemoryApplier, collections::map::HashSet};
46use cranpose_foundation::nodes::input::PointerEvent;
47use cranpose_ui::LayoutTree;
48pub use cranpose_ui_graphics::Brush;
49use cranpose_ui_graphics::Size;
50
51/// Trait implemented by hit-test targets stored inside a [`RenderScene`].
52pub trait HitTestTarget {
53 /// Dispatches a pointer event to this target's handlers.
54 fn dispatch(&self, event: PointerEvent);
55
56 /// Dispatches a pointer event using the current live node state when available.
57 ///
58 /// Render-scene hit targets may cache closures from an older scene build. Pointer
59 /// dispatch goes through this hook so implementations can resolve fresh handlers
60 /// from the current applier while still using the target's geometry snapshot.
61 fn dispatch_with_applier(&self, _applier: &mut MemoryApplier, event: PointerEvent) {
62 self.dispatch(event);
63 }
64
65 /// Returns the NodeId associated with this hit target.
66 /// Used by HitPathTracker to cache stable identity instead of geometry.
67 fn node_id(&self) -> cranpose_core::NodeId;
68
69 /// The pointer's appearance while it hovers this target, when the target
70 /// names one.
71 ///
72 /// The shell asks the hit list top-down and applies the first answer, so
73 /// the innermost region under the pointer decides the cursor.
74 fn pointer_icon(&self) -> Option<cranpose_ui_graphics::PointerIcon> {
75 None
76 }
77
78 /// Returns the node capture path that should stay attached to this target's gesture.
79 ///
80 /// The default is just this target's own node. Renderers can override this to
81 /// include stable ancestor pointer-input nodes that must continue receiving
82 /// Move/Up/Cancel even if the original descendant target is recycled.
83 fn capture_path(&self) -> Vec<cranpose_core::NodeId> {
84 vec![self.node_id()]
85 }
86}
87
88/// Trait describing the minimal surface area required by the application
89/// shell to process pointer events and refresh the frame graph.
90pub trait RenderScene {
91 type HitTarget: HitTestTarget + Clone;
92
93 fn clear(&mut self);
94
95 /// Performs hit testing at the given coordinates.
96 /// Returns hit targets ordered by z-index (top-to-bottom).
97 fn hit_test(&self, x: f32, y: f32) -> Vec<Self::HitTarget>;
98
99 /// The one target a press reaches when it misses every target but lands
100 /// inside a small target grown to the minimum touch size: the nearest such
101 /// target, and none when the point is outside every grown target.
102 fn hit_test_near(&self, _x: f32, _y: f32) -> Option<Self::HitTarget> {
103 None
104 }
105
106 /// Returns NodeIds of all hit regions at the given coordinates.
107 /// This is a convenience method equivalent to `hit_test().map(|h| h.node_id())`.
108 fn hit_test_nodes(&self, x: f32, y: f32) -> Vec<cranpose_core::NodeId> {
109 self.hit_test(x, y)
110 .into_iter()
111 .map(|h| h.node_id())
112 .collect()
113 }
114
115 /// Finds a hit target by NodeId with fresh geometry from the current scene.
116 ///
117 /// This is the key method for HitPathTracker-style gesture handling:
118 /// - On PointerDown, we cache NodeIds (not geometry)
119 /// - On Move/Up/Cancel, we call this to get fresh HitTarget with current geometry
120 /// - Handler closures are preserved (same Rc), so internal state survives
121 ///
122 /// Returns None if the node no longer exists in the scene (e.g., removed during gesture).
123 fn find_target(&self, node_id: cranpose_core::NodeId) -> Option<Self::HitTarget>;
124
125 /// Replaces the set with retained visual observation owners, preserving its capacity.
126 /// Returns whether the scene provides this information.
127 fn collect_retained_visual_observation_nodes(
128 &self,
129 nodes: &mut HashSet<cranpose_core::NodeId>,
130 ) -> bool {
131 nodes.clear();
132 false
133 }
134}
135
136/// Abstraction implemented by concrete renderer backends.
137pub trait Renderer {
138 type Scene: RenderScene;
139 type Error;
140
141 /// Installs renderer-provided app services into the target AppContext.
142 ///
143 /// AppShell calls this before the first composition pass.
144 /// Renderers that provide text measurement or other per-app services should install
145 /// them here rather than as constructor side effects.
146 fn attach_app_context_services(&mut self, _app_context: &cranpose_ui::AppContext) {}
147
148 fn scene(&self) -> &Self::Scene;
149 fn scene_mut(&mut self) -> &mut Self::Scene;
150
151 fn rebuild_scene(
152 &mut self,
153 layout_tree: &LayoutTree,
154 viewport: Size,
155 ) -> Result<(), Self::Error>;
156
157 /// Rebuilds the scene by traversing the LayoutNode tree directly via Applier.
158 ///
159 /// This is the new architecture that eliminates per-frame LayoutTree reconstruction.
160 /// Implementors must read layout state from LayoutNode.layout_state() directly.
161 fn rebuild_scene_from_applier(
162 &mut self,
163 applier: &mut cranpose_core::MemoryApplier,
164 root: cranpose_core::NodeId,
165 viewport: Size,
166 ) -> Result<(), Self::Error>;
167
168 fn update_scene_from_applier(
169 &mut self,
170 applier: &mut cranpose_core::MemoryApplier,
171 root: cranpose_core::NodeId,
172 viewport: Size,
173 dirty_nodes: &[cranpose_core::NodeId],
174 ) -> Result<(), Self::Error> {
175 let _ = dirty_nodes;
176 self.rebuild_scene_from_applier(applier, root, viewport)
177 }
178
179 fn update_visual_scene_from_applier(
180 &mut self,
181 applier: &mut cranpose_core::MemoryApplier,
182 root: cranpose_core::NodeId,
183 viewport: Size,
184 dirty_nodes: &[cranpose_core::NodeId],
185 ) -> Result<(), Self::Error> {
186 self.update_scene_from_applier(applier, root, viewport, dirty_nodes)
187 }
188
189 /// Draw a development overlay (e.g., FPS counter) on top of the scene.
190 ///
191 /// This is called after rebuild_scene when dev options are enabled.
192 /// The text is drawn directly by the renderer without affecting composition.
193 ///
194 /// Default implementation does nothing.
195 fn draw_dev_overlay(&mut self, _text: &str, _viewport: Size) {}
196
197 /// Replaces the developer inspector graph outside the application scene.
198 ///
199 /// Passing `None` removes the inspector. Its primitives must not participate
200 /// in application hit testing, layout, or accessibility.
201 fn set_inspector_overlay(&mut self, _graph: Option<graph::RenderGraph>) {}
202
203 /// Returns whether renderer-side cache materialization needs a visible follow-up frame.
204 fn needs_frame_warmup(&self) -> bool {
205 false
206 }
207}