tessera-components 0.0.0

//! Text Rendering Pipeline for UI Components
//!
//! This module implements the GPU pipeline and related utilities for efficient
//! text rendering in Tessera UI components. It leverages the Glyphon engine for
//! font management, shaping, and rasterization, providing high-quality and
//! performant text output. Typical use cases include rendering static labels,
//! paragraphs, and editable text fields within the UI.
//!
//! The pipeline is designed to be reusable and efficient, sharing a static font
//! system across the application to minimize resource usage. It exposes APIs
//! for preparing, measuring, and rendering text, supporting advanced features
//! such as font fallback, shaping, and multi-line layout.
//!
//! This module is intended for integration into custom UI components and
//! rendering flows that require flexible and robust text display.

use std::{num::NonZero, sync::OnceLock};

use glyphon::fontdb;
use parking_lot::{RwLock, RwLockReadGuard, RwLockWriteGuard};
use tessera_ui::{
    Color, PxPosition,
    renderer::drawer::pipeline::{DrawContext, DrawablePipeline},
    wgpu,
};

use super::command::{TextCommand, TextConstraint};

/// It costs a lot to create a glyphon font system, so we use a static one
/// to share it every where and avoid creating it multiple times.
static FONT_SYSTEM: OnceLock<RwLock<glyphon::FontSystem>> = OnceLock::new();

/// Create TextData is a heavy operation, so we provide a lru cache to store
/// recently used TextData.
static TEXT_DATA_CACHE: OnceLock<RwLock<lru::LruCache<LruKey, TextData>>> = OnceLock::new();

#[derive(PartialEq)]
struct LruKey {
    text: String,
    color: Color,
    font_size: f32,
    line_height: f32,
    /// The final computed bounds, used as the cache key instead of constraint.
    bounds: [u32; 2],
}

impl Eq for LruKey {}

impl std::hash::Hash for LruKey {
    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
        self.text.hash(state);
        self.color.r.to_bits().hash(state);
        self.color.g.to_bits().hash(state);
        self.color.b.to_bits().hash(state);
        self.color.a.to_bits().hash(state);
        self.font_size.to_bits().hash(state);
        self.line_height.to_bits().hash(state);
        self.bounds.hash(state);
    }
}

fn write_lru_cache() -> RwLockWriteGuard<'static, lru::LruCache<LruKey, TextData>> {
    TEXT_DATA_CACHE
        .get_or_init(|| {
            RwLock::new(lru::LruCache::new(
                NonZero::new(100).expect("text cache size must be non-zero"),
            ))
        })
        .write()
}

#[cfg(target_os = "android")]
fn init_font_system() -> RwLock<glyphon::FontSystem> {
    let mut font_system = glyphon::FontSystem::new();

    font_system.db_mut().load_fonts_dir("/system/fonts");
    font_system.db_mut().set_sans_serif_family("Roboto");
    font_system.db_mut().set_serif_family("Noto Serif");
    font_system.db_mut().set_monospace_family("Droid Sans Mono");
    font_system.db_mut().set_cursive_family("Dancing Script");
    font_system.db_mut().set_fantasy_family("Dancing Script");

    RwLock::new(font_system)
}

#[cfg(not(target_os = "android"))]
fn init_font_system() -> RwLock<glyphon::FontSystem> {
    RwLock::new(glyphon::FontSystem::new())
}

/// It costs a lot to create a glyphon font system, so we use a static one
/// to share it every where and avoid creating it multiple times.
/// This function returns a read lock of the font system.
pub fn read_font_system() -> RwLockReadGuard<'static, glyphon::FontSystem> {
    FONT_SYSTEM.get_or_init(init_font_system).read()
}

/// It costs a lot to create a glyphon font system, so we use a static one
/// to share it every where and avoid creating it multiple times.
/// This function returns a write lock of the font system.
pub fn write_font_system() -> RwLockWriteGuard<'static, glyphon::FontSystem> {
    FONT_SYSTEM.get_or_init(init_font_system).write()
}

/// A text renderer
/// Pipeline for rendering text using the Glyphon engine.
///
/// This struct manages font atlas, cache, viewport, and swash cache for
/// efficient text rendering.
pub struct GlyphonTextRender {
    /// Glyphon font atlas, a heavy-weight, shared resource.
    atlas: glyphon::TextAtlas,
    /// Glyphon cache, a heavy-weight, shared resource.
    #[allow(unused)]
    cache: glyphon::Cache,
    /// Glyphon viewport, holds screen-size related buffers.
    viewport: glyphon::Viewport,
    /// Glyphon swash cache, a CPU-side cache for glyph rasterization.
    swash_cache: glyphon::SwashCache,
    /// Multisample state for anti-aliasing.
    msaa: wgpu::MultisampleState,
    /// Glyphon text renderer, responsible for rendering text.
    renderer: glyphon::TextRenderer,
}

impl GlyphonTextRender {
    /// Creates a new text renderer pipeline.
    ///
    /// # Parameters
    ///
    /// - `gpu`: The wgpu device.
    /// - `queue`: The wgpu queue.
    /// - `config`: Surface configuration.
    /// - `sample_count`: Multisample count for anti-aliasing.
    pub fn new(
        gpu: &wgpu::Device,
        queue: &wgpu::Queue,
        config: &wgpu::SurfaceConfiguration,
        sample_count: u32,
    ) -> Self {
        let cache = glyphon::Cache::new(gpu);
        let mut atlas = glyphon::TextAtlas::new(gpu, queue, &cache, config.format);
        let viewport = glyphon::Viewport::new(gpu, &cache);
        let swash_cache = glyphon::SwashCache::new();
        let msaa = wgpu::MultisampleState {
            count: sample_count,
            mask: !0,
            alpha_to_coverage_enabled: false,
        };
        let renderer = glyphon::TextRenderer::new(&mut atlas, gpu, msaa, None);

        Self {
            atlas,
            cache,
            viewport,
            swash_cache,
            msaa,
            renderer,
        }
    }
}

impl DrawablePipeline<TextCommand> for GlyphonTextRender {
    fn draw(&mut self, context: &mut DrawContext<TextCommand>) {
        if context.commands.is_empty() {
            return;
        }

        self.viewport.update(
            context.queue,
            glyphon::Resolution {
                width: context.config.width,
                height: context.config.height,
            },
        );

        let text_areas = context.commands.iter().map(|(command, _size, start_pos)| {
            let start_pos = PxPosition::new(
                start_pos.x + command.offset.x,
                start_pos.y + command.offset.y,
            );
            command.data.text_area(start_pos)
        });

        self.renderer
            .prepare(
                context.device,
                context.queue,
                &mut write_font_system(),
                &mut self.atlas,
                &self.viewport,
                text_areas,
                &mut self.swash_cache,
            )
            .expect("glyphon prepare failed");

        self.renderer
            .render(&self.atlas, &self.viewport, context.render_pass)
            .expect("glyphon render failed");

        // Re-create the renderer to release borrow on atlas
        let new_renderer =
            glyphon::TextRenderer::new(&mut self.atlas, context.device, self.msaa, None);
        let _ = std::mem::replace(&mut self.renderer, new_renderer);
    }
}

/// Text data for rendering, including buffer and size.
#[derive(Debug, Clone)]
pub struct TextData {
    /// glyphon text buffer
    text_buffer: glyphon::Buffer,
    /// text area size
    pub size: [u32; 2],
    /// Baseline offset of the first visible line, relative to the text origin.
    pub first_baseline: f32,
    /// Baseline offset of the last visible line, relative to the text origin.
    pub last_baseline: f32,
    /// Number of visible layout lines.
    pub line_count: u32,
    base_color: Color,
    current_color: Color,
    text: String,
    font_size: f32,
    line_height: f32,
}

/// Measurement result returned by `TextData::measure()`.
#[derive(Debug, Clone, Copy)]
#[allow(dead_code)]
pub struct TextMeasureInfo {
    /// The computed size of the text area.
    pub size: [u32; 2],
    /// Baseline offset of the first visible line.
    pub first_baseline: f32,
    /// Baseline offset of the last visible line.
    pub last_baseline: f32,
    /// Number of visible layout lines.
    pub line_count: u32,
}

impl PartialEq for TextData {
    fn eq(&self, other: &Self) -> bool {
        self.size == other.size
            && self.first_baseline == other.first_baseline
            && self.last_baseline == other.last_baseline
            && self.line_count == other.line_count
            && self.base_color == other.base_color
            && self.current_color == other.current_color
            && self.text == other.text
            && self.font_size == other.font_size
            && self.line_height == other.line_height
    }
}

impl TextData {
    /// Measures text layout and caches the result.
    ///
    /// This method performs the expensive text shaping and layout computation,
    /// stores the result in the LRU cache, and returns measurement information.
    /// The cached result can later be retrieved using [`TextData::get()`].
    ///
    /// # Parameters
    /// - `text`: The text string.
    /// - `color`: The text color.
    /// - `font_size`: Font size.
    /// - `line_height`: Line height.
    /// - `constraint`: Text constraint for layout.
    pub fn measure(
        text: String,
        color: Color,
        font_size: f32,
        line_height: f32,
        constraint: TextConstraint,
    ) -> TextMeasureInfo {
        let (text_buffer, bounds, first_baseline, last_baseline, line_count) =
            Self::build_buffer(&text, color, font_size, line_height, &constraint);

        // Build cache key using bounds (not constraint)
        let key = LruKey {
            text: text.clone(),
            color,
            font_size,
            line_height,
            bounds,
        };

        // Store in cache
        let data = Self {
            text_buffer,
            size: bounds,
            first_baseline,
            last_baseline,
            line_count,
            base_color: color,
            current_color: color,
            text,
            font_size,
            line_height,
        };
        write_lru_cache().put(key, data);

        TextMeasureInfo {
            size: bounds,
            first_baseline,
            last_baseline,
            line_count,
        }
    }

    /// Retrieves cached text data using the computed bounds.
    ///
    /// This method attempts to retrieve cached data from a prior
    /// [`TextData::measure()`] call. If the cache entry was evicted (due to LRU
    /// limits), it will automatically recompute the text layout using the
    /// bounds as the constraint.
    ///
    /// # Parameters
    /// - `text`: The text string.
    /// - `color`: The text color.
    /// - `font_size`: Font size.
    /// - `line_height`: Line height.
    /// - `bounds`: The computed bounds from measurement (width, height).
    pub fn get(
        text: String,
        color: Color,
        font_size: f32,
        line_height: f32,
        bounds: [u32; 2],
    ) -> Self {
        let key = LruKey {
            text: text.clone(),
            color,
            font_size,
            line_height,
            bounds,
        };

        // Try to get from cache first
        if let Some(cached) = write_lru_cache().get(&key).cloned() {
            return cached;
        }

        // Cache miss (possibly evicted by LRU), recompute using bounds as constraint
        let constraint = TextConstraint {
            max_width: Some(bounds[0] as f32),
            max_height: Some(bounds[1] as f32),
        };
        let (text_buffer, computed_bounds, first_baseline, last_baseline, line_count) =
            Self::build_buffer(&text, color, font_size, line_height, &constraint);

        let data = Self {
            text_buffer,
            size: computed_bounds,
            first_baseline,
            last_baseline,
            line_count,
            base_color: color,
            current_color: color,
            text: text.clone(),
            font_size,
            line_height,
        };

        // Store back in cache
        write_lru_cache().put(key, data.clone());
        data
    }

    /// Prepares text data for rendering (legacy API, combines measure + get).
    ///
    /// # Parameters
    /// Builds [`TextData`] directly from a pre-shaped glyphon buffer.
    pub fn from_buffer(text_buffer: glyphon::Buffer) -> Self {
        // Calculate total height including descender for the last line
        let metrics = text_buffer.metrics();
        // Calculate text bounds
        let mut run_width: f32 = 0.0;
        let mut first_baseline = 0.0;
        let mut last_baseline = 0.0;
        let mut line_count: u32 = 0;
        for run in text_buffer.layout_runs() {
            // Take the max. width of all lines.
            run_width = run_width.max(run.line_w);
            if line_count == 0 {
                first_baseline = run.line_y;
            }
            last_baseline = run.line_y;
            line_count += 1;
        }
        let descent_amount = (metrics.line_height - metrics.font_size).max(0.0);
        let total_height = line_count as f32 * metrics.line_height + descent_amount;
        // build text data
        Self {
            text_buffer,
            size: [run_width as u32, total_height.ceil() as u32],
            first_baseline,
            last_baseline,
            line_count,
            base_color: Color::WHITE,
            current_color: Color::WHITE,
            text: String::new(),
            font_size: metrics.font_size,
            line_height: metrics.line_height,
        }
    }

    /// Get the glyphon text area from the text data
    fn text_area(&'_ self, start_pos: PxPosition) -> glyphon::TextArea<'_> {
        let bounds = glyphon::TextBounds {
            left: start_pos.x.raw(),
            top: start_pos.y.raw(),
            right: start_pos.x.raw() + self.size[0] as i32,
            bottom: start_pos.y.raw() + self.size[1] as i32,
        };
        glyphon::TextArea {
            buffer: &self.text_buffer,
            left: start_pos.x.to_f32(),
            top: start_pos.y.to_f32(),
            scale: 1.0,
            bounds,
            default_color: glyphon::Color::rgba(
                (self.current_color.r * 255.0) as u8,
                (self.current_color.g * 255.0) as u8,
                (self.current_color.b * 255.0) as u8,
                (self.current_color.a * 255.0) as u8,
            ),
            custom_glyphs: &[],
        }
    }

    fn build_buffer(
        text: &str,
        color: Color,
        size: f32,
        line_height: f32,
        constraint: &TextConstraint,
    ) -> (glyphon::Buffer, [u32; 2], f32, f32, u32) {
        // Create text buffer
        let mut text_buffer = glyphon::Buffer::new(
            &mut write_font_system(),
            glyphon::Metrics::new(size, line_height),
        );
        let color = glyphon::Color::rgba(
            (color.r * 255.0) as u8,
            (color.g * 255.0) as u8,
            (color.b * 255.0) as u8,
            (color.a * 255.0) as u8,
        );
        text_buffer.set_wrap(&mut write_font_system(), glyphon::Wrap::Glyph);
        text_buffer.set_size(
            &mut write_font_system(),
            constraint.max_width,
            constraint.max_height,
        );
        text_buffer.set_text(
            &mut write_font_system(),
            text,
            &glyphon::Attrs::new()
                .family(fontdb::Family::SansSerif)
                .color(color),
            glyphon::Shaping::Advanced,
            None,
        );
        text_buffer.shape_until_scroll(&mut write_font_system(), false);
        // Calculate text bounds and baselines.
        let mut run_width: f32 = 0.0;
        let metrics = text_buffer.metrics();
        let mut first_baseline = 0.0;
        let mut last_baseline = 0.0;
        let mut line_count: u32 = 0;
        for run in text_buffer.layout_runs() {
            run_width = run_width.max(run.line_w);
            if line_count == 0 {
                first_baseline = run.line_y;
            }
            last_baseline = run.line_y;
            line_count += 1;
        }
        let descent_amount = (metrics.line_height - metrics.font_size).max(0.0);
        let total_height = line_count as f32 * metrics.line_height + descent_amount;
        (
            text_buffer,
            [run_width as u32, total_height.ceil() as u32],
            first_baseline,
            last_baseline,
            line_count,
        )
    }

    pub(crate) fn apply_opacity(&mut self, opacity: f32) {
        let target_alpha = (self.base_color.a * opacity).clamp(0.0, 1.0);
        let target_color = self.base_color.with_alpha(target_alpha);
        if (target_color.a - self.current_color.a).abs() <= f32::EPSILON
            && (target_color.r - self.current_color.r).abs() <= f32::EPSILON
            && (target_color.g - self.current_color.g).abs() <= f32::EPSILON
            && (target_color.b - self.current_color.b).abs() <= f32::EPSILON
        {
            return;
        }

        // Use the current size as constraint for rebuilding with new color
        let constraint = TextConstraint {
            max_width: Some(self.size[0] as f32),
            max_height: Some(self.size[1] as f32),
        };
        let (buffer, bounds, first_baseline, last_baseline, line_count) = Self::build_buffer(
            &self.text,
            target_color,
            self.font_size,
            self.line_height,
            &constraint,
        );
        self.text_buffer = buffer;
        self.size = bounds;
        self.first_baseline = first_baseline;
        self.last_baseline = last_baseline;
        self.line_count = line_count;
        self.current_color = target_color;
    }
}