cranpose_render_common/
lib.rs

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

cranpose_render_common/
lib.rs
