dexterior_visuals/pipelines/

text.rs

use glyphon as gh;
use nalgebra as na;
use std::sync::Arc;

use crate::{
    camera::Camera2D,
    layout::Viewport,
    render_window::{ActiveRenderWindow, RenderContext},
};

pub use gh::Color as TextColor;

pub(crate) struct TextPipeline {
    font_system: gh::FontSystem,
    swash_cache: gh::SwashCache,
    viewport: gh::Viewport,
    atlas: gh::TextAtlas,
    renderer: gh::TextRenderer,
    /// Glyphon requires us to draw all the text in one call,
    /// so we collect each text request into a queue and flush it at the end of a frame.
    pub draw_queue: Vec<TextBuffer>,
}

/// Parameters for displaying text.
#[derive(Clone, Debug)]
pub struct TextParams<'a> {
    /// Content of the text to be displayed. Default: "".
    pub text: &'a str,
    /// Position of the anchor point in simulation space. Default: origin.
    pub position: na::Vector2<f64>,
    /// Placement of the anchor point relative to the text. Default: center.
    pub anchor: TextAnchor,
    /// Fixed width for the text area in pixels. Default: None.
    /// If not given, the text is laid out based on its own dimensions.
    pub area_width: Option<f32>,
    /// Fixed height for the text area in pixels. Default: None.
    /// If not given, the text is laid out based on its own dimensions.
    pub area_height: Option<f32>,
    /// Font size of the text. Default: 30.
    pub font_size: f32,
    /// Line height of the text. Default: 42.
    pub line_height: f32,
    /// Color of the text. Default: black.
    pub color: palette::LinSrgb,
    /// Set of cosmic-text attributes for the text buffer.
    /// Default: [`default_text_attrs`].
    ///
    /// Types for the fields can be accessed through the library's re-export of [`glyphon`].
    pub attrs: gh::Attrs<'a>,
}

impl<'a> Default for TextParams<'a> {
    fn default() -> Self {
        Self {
            text: "",
            position: na::SVector::zeros(),
            anchor: TextAnchor::Center,
            area_width: None,
            area_height: None,
            font_size: 30.,
            line_height: 42.,
            color: palette::named::BLACK.into(),
            attrs: default_text_attrs(),
        }
    }
}

/// The default [`Attrs`][gh::Attrs] used for text rendering.
///
/// These are the `cosmic_text` defaults,
/// except with the font family changed to `JetBrains Mono`.
/// This font is shipped with the library
/// (under the SIL Open Font License 1.1)
/// and therefore works also in WebAssembly builds,
/// where you don't have access to system fonts.
/// On native platforms you can change the font to anything
/// that you have installed on your system;
/// on the web we don't currently have a way to supply custom fonts
/// (outside of forking and modifying the `TextPipeline::new` function).
pub fn default_text_attrs() -> gh::Attrs<'static> {
    gh::Attrs::new().family(gh::Family::Name("JetBrains Mono"))
}

/// Convert a `palette` color to a `glyphon` color.
/// We should use `palette` colors in public APIs
/// and use this for conversions internally.
fn color_to_text_color(color: palette::LinSrgb) -> gh::Color {
    let col_u8 = palette::Srgb::<u8>::from(color);
    gh::Color::rgb(col_u8.red, col_u8.green, col_u8.blue)
}

/// Where to place a text field
/// relative to the position given in [`TextParams`].
///
/// For example, with an anchor of `TopMid`, the text will be placed
/// relative to position `x` as follows:
/// ```text
/// ----x----
/// |content|
/// ---------
/// ```
#[derive(Clone, Copy, Debug)]
#[allow(missing_docs)]
pub enum TextAnchor {
    TopLeft,
    TopMid,
    TopRight,
    MidLeft,
    Center,
    MidRight,
    BottomLeft,
    BottomMid,
    BottomRight,
}

/// A text buffer ready for rendering, created with [`TextPipeline::create_buffer`].
pub(crate) struct TextBuffer {
    buffer: gh::Buffer,
    /// position of the top left corner in screen space
    position: na::Vector2<f32>,
    width: f32,
    height: f32,
    color: TextColor,
}

impl TextPipeline {
    pub fn new(window: &ActiveRenderWindow) -> Self {
        // we need to include fonts in the binary
        // for this to work on the web,
        // since the wasm target doesn't have access to system fonts
        let font_system = gh::FontSystem::new_with_fonts([
            gh::fontdb::Source::Binary(Arc::new(include_bytes!(
                "../../fonts/JetBrainsMono-Regular.ttf"
            ))),
            gh::fontdb::Source::Binary(Arc::new(include_bytes!(
                "../../fonts/JetBrainsMono-Italic.ttf"
            ))),
            gh::fontdb::Source::Binary(Arc::new(include_bytes!(
                "../../fonts/JetBrainsMono-Bold.ttf"
            ))),
        ]);

        let swash_cache = gh::SwashCache::new();
        let cache = gh::Cache::new(&window.device);
        let viewport = gh::Viewport::new(&window.device, &cache);
        let mut atlas = gh::TextAtlas::new(
            &window.device,
            &window.queue,
            &cache,
            window.swapchain_format(),
        );
        let renderer =
            gh::TextRenderer::new(&mut atlas, &window.device, window.multisample_state(), None);

        Self {
            font_system,
            swash_cache,
            viewport,
            atlas,
            renderer,
            draw_queue: Vec::new(),
        }
    }

    /// Queue a text buffer for rendering this frame.
    ///
    /// We redo layout each frame because caching doesn't interact well
    /// with the immediate mode user API.
    /// This hasn't been a performance issue so far;
    /// look into caching again if it becomes one.
    pub fn queue_text(&mut self, viewport: Viewport, camera: &Camera2D, params: TextParams<'_>) {
        let mut buffer = gh::Buffer::new(
            &mut self.font_system,
            gh::Metrics {
                font_size: params.font_size,
                line_height: params.line_height,
            },
        );

        buffer.set_size(&mut self.font_system, params.area_width, params.area_height);
        buffer.set_text(
            &mut self.font_system,
            params.text,
            &params.attrs,
            gh::Shaping::Advanced,
        );
        buffer.shape_until_scroll(&mut self.font_system, false);

        // compute buffer positioning on the screen

        let view_proj = camera.view_projection_matrix(viewport.size());
        let half_vp = (viewport.width as f32 / 2., viewport.height as f32 / 2.);

        // TODO: option to position text in screen space
        let anchor_pos_ndc = view_proj
            * na::Vector4::new(params.position[0] as f32, params.position[1] as f32, 0., 1.);
        let anchor_pixel = na::Vector2::new(
            anchor_pos_ndc.x * half_vp.0 + half_vp.0,
            -anchor_pos_ndc.y * half_vp.1 + half_vp.1,
        );

        let (width, height) = buffer.size();
        let width = match width {
            Some(w) => w,
            // no explicit width given, compute from layout
            None => buffer
                .layout_runs()
                .map(|l| l.line_w)
                .max_by(f32::total_cmp)
                .unwrap_or(0.),
        };
        let height = match height {
            Some(h) => h,
            None => buffer
                .layout_runs()
                .last()
                .map(|l| l.line_top + l.line_height)
                .unwrap_or(0.),
        };

        use TextAnchor::*;
        let top_left_pixel = anchor_pixel
            - match params.anchor {
                TopLeft => na::Vector2::zeros(),
                TopMid => na::Vector2::new(width / 2., 0.),
                TopRight => na::Vector2::new(width, 0.),
                MidLeft => na::Vector2::new(0., height / 2.),
                Center => na::Vector2::new(width / 2., height / 2.),
                MidRight => na::Vector2::new(width, height / 2.),
                BottomLeft => na::Vector2::new(0., height),
                BottomMid => na::Vector2::new(width / 2., height),
                BottomRight => na::Vector2::new(width, height),
            };

        let vp_offset = na::Vector2::new(viewport.x as f32, viewport.y as f32);

        self.draw_queue.push(TextBuffer {
            buffer,
            position: vp_offset + top_left_pixel,
            width,
            height,
            color: color_to_text_color(params.color),
        });
    }

    /// Draw all text buffers that have been queued during this frame.
    pub fn draw(&mut self, ctx: &mut RenderContext<'_>) {
        self.viewport.update(
            ctx.queue,
            gh::Resolution {
                width: ctx.viewport_size.0,
                height: ctx.viewport_size.1,
            },
        );

        let areas = self.draw_queue.iter().map(|buf| gh::TextArea {
            buffer: &buf.buffer,
            left: buf.position.x,
            top: buf.position.y,
            scale: 1.,
            bounds: gh::TextBounds {
                left: buf.position.x as i32,
                top: buf.position.y as i32,
                right: (buf.position.x + buf.width + 1.) as i32,
                bottom: (buf.position.y + buf.height + 1.) as i32,
            },
            default_color: buf.color,
            custom_glyphs: &[],
        });

        self.renderer
            .prepare(
                ctx.device,
                ctx.queue,
                &mut self.font_system,
                &mut self.atlas,
                &self.viewport,
                areas,
                &mut self.swash_cache,
            )
            .expect("Failed to render text");

        self.renderer
            .render(&self.atlas, &self.viewport, &mut ctx.pass)
            .expect("Failed to render text");

        self.draw_queue.clear();
    }
}