cranpose_render_common/
lib.rs

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

cranpose_render_common/
lib.rs
