cranpose_render_common/

lib.rs

#![doc = include_str!("../README.md")]

mod annotated_text;
mod ascii_glyphs;
pub mod debug_toggles;
pub mod dev_overlay;
mod direct_mapped_cache;

/// The frame background every renderer clears to (linear values; sRGB
/// surfaces display this as rgb(75, 75, 86)). One definition so backends
/// cannot drift.
pub const FRAME_CLEAR_COLOR: [f32; 4] = [18.0 / 255.0, 18.0 / 255.0, 24.0 / 255.0, 1.0];
pub mod brush_sampling;
mod font_features;
pub mod font_layout;
pub mod font_source;
mod font_tracking;
pub mod geometry;
pub mod gpos_kerning;
pub mod graph;
mod graph_hash;
pub mod graph_scene;
pub mod hit_graph;
pub mod image_compare;
pub mod layer_composition;
mod layer_recycling;
pub mod layer_shadow;
pub mod layer_transform;
pub mod primitive_emit;
pub mod raster_cache;
pub mod render_contract;
pub mod scene_builder;
pub mod shape_sdf;
pub mod software_text_raster;
pub mod style_shared;
mod text_cache_key;
pub mod text_hyphenation;
pub mod text_mask_gamma;
pub mod text_measure;
pub mod text_paint;
#[cfg(feature = "text-shaping")]
mod text_shaping;

#[cfg(test)]
#[path = "tests/pointer_slices.rs"]
mod pointer_slices;

use cranpose_core::{MemoryApplier, collections::map::HashSet};
use cranpose_foundation::nodes::input::PointerEvent;
use cranpose_ui::LayoutTree;
pub use cranpose_ui_graphics::Brush;
use cranpose_ui_graphics::Size;

/// Describes scene nodes whose recorded content or layer properties changed.
///
/// Content updates may re-record a node's draw commands. Layer updates change
/// graphics-layer properties while retaining those recordings. If a node
/// appears in both slices, content dirt takes precedence.
/// Layout, child structure, and draw-command changes belong in `content`.
///
/// ```
/// use cranpose_render_common::SceneUpdates;
/// let updates = SceneUpdates {
///     content: &[1],
///     layers: &[2],
///     moved: &[3],
/// };
/// assert!(!updates.is_empty());
/// ```
#[derive(Clone, Copy, Debug, Default)]
pub struct SceneUpdates<'a> {
    /// Nodes whose recorded draw content must be refreshed.
    pub content: &'a [cranpose_core::NodeId],
    /// Nodes whose graphics-layer properties changed without content dirt.
    pub layers: &'a [cranpose_core::NodeId],
    /// Nodes that moved in their parent and kept their size: the scene moves
    /// what it drew for them unless another list names them too.
    pub moved: &'a [cranpose_core::NodeId],
}

impl<'a> SceneUpdates<'a> {
    /// Creates an update containing only nodes with changed draw content.
    pub const fn content(nodes: &'a [cranpose_core::NodeId]) -> Self {
        Self {
            content: nodes,
            layers: &[],
            moved: &[],
        }
    }

    /// Returns whether the update contains no dirty nodes.
    pub const fn is_empty(self) -> bool {
        self.content.is_empty() && self.layers.is_empty() && self.moved.is_empty()
    }
}

/// Trait implemented by hit-test targets stored inside a [`RenderScene`].
pub trait HitTestTarget {
    /// Dispatches a pointer event to this target's handlers.
    fn dispatch(&self, event: PointerEvent);

    /// Dispatches a pointer event using the current live node state when available.
    ///
    /// Render-scene hit targets may cache closures from an older scene build. Pointer
    /// dispatch goes through this hook so implementations can resolve fresh handlers
    /// from the current applier while still using the target's geometry snapshot.
    fn dispatch_with_applier(&self, _applier: &mut MemoryApplier, event: PointerEvent) {
        self.dispatch(event);
    }

    /// Returns the NodeId associated with this hit target.
    /// Used by HitPathTracker to cache stable identity instead of geometry.
    fn node_id(&self) -> cranpose_core::NodeId;

    /// The pointer's appearance while it hovers this target, when the target
    /// names one.
    ///
    /// The shell asks the hit list top-down and applies the first answer, so
    /// the innermost region under the pointer decides the cursor.
    fn pointer_icon(&self) -> Option<cranpose_ui_graphics::PointerIcon> {
        None
    }

    /// Returns the node capture path that should stay attached to this target's gesture.
    ///
    /// The default is just this target's own node. Renderers can override this to
    /// include stable ancestor pointer-input nodes that must continue receiving
    /// Move/Up/Cancel even if the original descendant target is recycled.
    fn capture_path(&self) -> Vec<cranpose_core::NodeId> {
        vec![self.node_id()]
    }
}

/// Trait describing the minimal surface area required by the application
/// shell to process pointer events and refresh the frame graph.
pub trait RenderScene {
    type HitTarget: HitTestTarget + Clone;

    fn clear(&mut self);

    /// Performs hit testing at the given coordinates.
    /// Returns hit targets ordered by z-index (top-to-bottom).
    fn hit_test(&self, x: f32, y: f32) -> Vec<Self::HitTarget>;

    /// The one target a press reaches when it misses every target but lands
    /// inside a small target grown to the minimum touch size: the nearest such
    /// target, and none when the point is outside every grown target.
    fn hit_test_near(&self, _x: f32, _y: f32) -> Option<Self::HitTarget> {
        None
    }

    /// Returns NodeIds of all hit regions at the given coordinates.
    /// This is a convenience method equivalent to `hit_test().map(|h| h.node_id())`.
    fn hit_test_nodes(&self, x: f32, y: f32) -> Vec<cranpose_core::NodeId> {
        self.hit_test(x, y)
            .into_iter()
            .map(|h| h.node_id())
            .collect()
    }

    /// Finds a hit target by NodeId with fresh geometry from the current scene.
    ///
    /// This is the key method for HitPathTracker-style gesture handling:
    /// - On PointerDown, we cache NodeIds (not geometry)
    /// - On Move/Up/Cancel, we call this to get fresh HitTarget with current geometry
    /// - Handler closures are preserved (same Rc), so internal state survives
    ///
    /// Returns None if the node no longer exists in the scene (e.g., removed during gesture).
    fn find_target(&self, node_id: cranpose_core::NodeId) -> Option<Self::HitTarget>;

    /// Replaces the set with retained visual observation owners, preserving its capacity.
    /// Returns whether the scene provides this information.
    fn collect_retained_visual_observation_nodes(
        &self,
        nodes: &mut HashSet<cranpose_core::NodeId>,
    ) -> bool {
        nodes.clear();
        false
    }
}

/// Abstraction implemented by concrete renderer backends.
pub trait Renderer {
    type Scene: RenderScene;
    type Error;

    /// Installs renderer-provided app services into the target AppContext.
    ///
    /// AppShell calls this before the first composition pass.
    /// Renderers that provide text measurement or other per-app services should install
    /// them here rather than as constructor side effects.
    fn attach_app_context_services(&mut self, _app_context: &cranpose_ui::AppContext) {}

    /// Sets how many device pixels the renderer draws for one logical unit.
    ///
    /// AppShell sets its primary renderer's scale to the density it lays
    /// out with, at construction and on every density change, so a host
    /// sets it only for the renderers of other surfaces. Renderers that take
    /// the scale with each draw ignore it.
    fn set_root_scale(&mut self, _scale: f32) {}

    fn scene(&self) -> &Self::Scene;
    fn scene_mut(&mut self) -> &mut Self::Scene;

    fn rebuild_scene(
        &mut self,
        layout_tree: &LayoutTree,
        viewport: Size,
    ) -> Result<(), Self::Error>;

    /// Rebuilds the scene by traversing the LayoutNode tree directly via Applier.
    ///
    /// This is the new architecture that eliminates per-frame LayoutTree reconstruction.
    /// Implementors must read layout state from LayoutNode.layout_state() directly.
    fn rebuild_scene_from_applier(
        &mut self,
        applier: &mut cranpose_core::MemoryApplier,
        root: cranpose_core::NodeId,
        viewport: Size,
    ) -> Result<(), Self::Error>;

    fn update_scene_from_applier(
        &mut self,
        applier: &mut cranpose_core::MemoryApplier,
        root: cranpose_core::NodeId,
        viewport: Size,
        updates: SceneUpdates<'_>,
    ) -> Result<(), Self::Error> {
        let _ = updates;
        self.rebuild_scene_from_applier(applier, root, viewport)
    }

    fn update_visual_scene_from_applier(
        &mut self,
        applier: &mut cranpose_core::MemoryApplier,
        root: cranpose_core::NodeId,
        viewport: Size,
        updates: SceneUpdates<'_>,
    ) -> Result<(), Self::Error> {
        self.update_scene_from_applier(applier, root, viewport, updates)
    }

    /// Draw a development overlay (e.g., FPS counter) on top of the scene.
    ///
    /// This is called after rebuild_scene when dev options are enabled.
    /// The text is drawn directly by the renderer without affecting composition.
    ///
    /// Default implementation does nothing.
    fn draw_dev_overlay(&mut self, _text: &str, _viewport: Size) {}

    /// Replaces the developer inspector graph outside the application scene.
    ///
    /// Passing `None` removes the inspector. Its primitives must not participate
    /// in application hit testing, layout, or accessibility.
    fn set_inspector_overlay(&mut self, _graph: Option<graph::RenderGraph>) {}

    /// Returns whether renderer-side cache materialization needs a visible follow-up frame.
    fn needs_frame_warmup(&self) -> bool {
        false
    }

    /// Returns whether the last frame drew a placeholder for an effect whose
    /// pipelines are still compiling, so its picture is not final yet; the
    /// renderer asks for the frame that replaces it once they land.
    fn awaits_pipelines(&self) -> bool {
        false
    }
}