cranpose_render_common/
lib.rs

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

cranpose_render_common/
lib.rs
