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