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

cranpose_render_common/
lib.rs
