onedrop_renderer/

text_pipeline.rs

//! Text overlay (§6) GPU pipeline.
//!
//! Renders `MILK_MSG.INI` message strings as 2D glyph quads atop the
//! comp output. Glyphs are rasterised on-demand by `ab_glyph` into a
//! shared `Rgba8Unorm` atlas (alpha stored in `.r`), and the pipeline
//! emits one draw per frame from a dynamic vertex buffer holding every
//! glyph of every active message.
//!
//! Two bundled fonts come from `epaint_default_fonts`:
//! - **0 (default)**: `Ubuntu-Light` — clean sans the MD2 default
//!   message font (`Arial`) maps to.
//! - **1 (mono)**: `Hack-Regular` — covers presets that ask for a
//!   monospace face. Mapping ignores bold/italic; MD2 only exposes
//!   those as `font=...; bold=1` toggles and most preset packs author
//!   for the default sans anyway.
//!
//! The atlas grows append-only inside a fixed `1024×1024` texture; if
//! a glyph doesn't fit, the renderer falls back to the existing slot
//! pool (logged once). 1024² is enough for a few thousand glyphs at
//! `32 px` body size — well above what `MILK_MSG.INI` files use in the
//! wild (≤ 8 messages).

use std::collections::HashMap;

use ab_glyph::{Font, FontArc, FontVec, Glyph, PxScale, ScaleFont, point};
use bytemuck::{Pod, Zeroable};

use crate::pipeline_helpers::load_wgsl;

/// Atlas texture side (square). 1024² fits ~3K glyphs at 32px body —
/// well above typical `MILK_MSG.INI` usage. The atlas grows
/// append-only inside this footprint; once full, new glyph requests
/// fall back to existing nearest-size slots.
pub const TEXT_ATLAS_SIZE: u32 = 1024;

/// Per-glyph vertex pushed to the GPU vertex buffer.
#[repr(C)]
#[derive(Debug, Clone, Copy, Default)]
pub struct TextQuadVertex {
    /// Clip-space position (`[-1, 1]` per axis). CPU side does the
    /// `[0, 1]` screen → clip + aspect-correction so the vertex
    /// shader stays a pass-through.
    pub pos_clip: [f32; 2],
    /// Atlas UV (`[0, 1]`).
    pub uv: [f32; 2],
    /// Tint colour (`r, g, b, a`). The fragment shader multiplies the
    /// sampled atlas alpha by `a` to produce a premultiplied output.
    pub rgba: [f32; 4],
}

unsafe impl Pod for TextQuadVertex {}
unsafe impl Zeroable for TextQuadVertex {}

/// One message the engine asks the renderer to draw this frame. POD —
/// the text/layout/font lookup all happens host-side in
/// [`TextPipeline::record`].
#[derive(Debug, Clone)]
pub struct TextFrame {
    pub text: String,
    /// `0` = Ubuntu-Light (default), `1` = Hack mono. Anything else
    /// snaps to `0`.
    pub font: u32,
    /// Body size in pixels of render height. The CPU layout step
    /// turns this into an `ab_glyph::PxScale`.
    pub size_px: f32,
    /// Anchor centre in `[0, 1]` screen coords (top-left origin).
    pub x: f32,
    pub y: f32,
    /// Tint colour. Alpha drives the fade phase (engine-side).
    pub rgba: [f32; 4],
}

/// One rasterised glyph's slot in the atlas.
#[derive(Debug, Clone, Copy)]
struct GlyphSlot {
    /// Atlas UV bounds.
    uv_min: [f32; 2],
    uv_max: [f32; 2],
    /// Rasterised pixel dimensions inside the atlas.
    px_w: u32,
    px_h: u32,
    /// Pixel offsets from the glyph's pen origin to the top-left
    /// corner of the rasterised cell. Equivalent to FreeType's
    /// `(bearing_x, -bearing_y)`. Used at layout time to position the
    /// quad against the line's baseline.
    bearing_x: f32,
    bearing_y: f32,
    /// Horizontal advance for the next glyph on the same line, in px.
    advance: f32,
}

/// Cache key for one rasterised glyph.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct GlyphKey {
    font: u32,
    /// `ab_glyph` uses `f32` for px size but maps it to an integer
    /// PxScale internally; we quantise so the cache hit-rate stays high.
    /// Half-pixel steps give plenty of fidelity at the sizes MD2 uses
    /// (`16..80`).
    size_q: u16,
    glyph_id: u16,
}

/// GPU + CPU text atlas. Owned by [`TextPipeline`].
pub struct TextAtlas {
    texture: wgpu::Texture,
    view: wgpu::TextureView,
    sampler: wgpu::Sampler,
    width: u32,
    height: u32,
    /// CPU-side shadow of the atlas pixels — keeps the atlas
    /// resident as a single Rgba8 buffer so partial updates don't
    /// require GPU-side readback. Alpha lands in `.r`, other channels
    /// stay zero.
    cpu_pixels: Vec<u8>,
    /// Next free pixel inside the current row.
    cursor_x: u32,
    /// Top of the current row.
    cursor_y: u32,
    /// Height of the tallest glyph placed in the current row — used
    /// to advance `cursor_y` when the row fills up.
    row_h: u32,
    glyphs: HashMap<GlyphKey, GlyphSlot>,
    fonts: Vec<FontArc>,
    /// Set when [`Self::ensure_glyph`] grew the CPU pixel buffer.
    /// Drives the queue.write_texture call on the next render.
    dirty: bool,
}

impl TextAtlas {
    pub fn new(device: &wgpu::Device, queue: &wgpu::Queue) -> Self {
        let width = TEXT_ATLAS_SIZE;
        let height = TEXT_ATLAS_SIZE;
        let texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("Text Atlas"),
            size: wgpu::Extent3d {
                width,
                height,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8Unorm,
            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
            view_formats: &[],
        });
        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
        let sampler = device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("Text Atlas Sampler"),
            address_mode_u: wgpu::AddressMode::ClampToEdge,
            address_mode_v: wgpu::AddressMode::ClampToEdge,
            mag_filter: wgpu::FilterMode::Linear,
            min_filter: wgpu::FilterMode::Linear,
            ..Default::default()
        });
        let cpu_pixels = vec![0u8; (width * height * 4) as usize];
        // Upload an initial zero buffer so a render with no glyphs
        // still has defined atlas contents (avoids undefined-read
        // warnings in validation layers).
        queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: &texture,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &cpu_pixels,
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(width * 4),
                rows_per_image: Some(height),
            },
            wgpu::Extent3d {
                width,
                height,
                depth_or_array_layers: 1,
            },
        );

        let fonts = bundled_fonts();
        Self {
            texture,
            view,
            sampler,
            width,
            height,
            cpu_pixels,
            cursor_x: 1,
            cursor_y: 1,
            row_h: 0,
            glyphs: HashMap::new(),
            fonts,
            dirty: false,
        }
    }

    /// Rasterise a glyph into the atlas if not already cached. Returns
    /// the cached slot — or `None` if rasterising failed (out-of-atlas
    /// or zero-extent glyph like a space).
    fn ensure_glyph(
        &mut self,
        font: u32,
        size_px: f32,
        glyph_id: u16,
        ch: char,
    ) -> Option<GlyphSlot> {
        let font_idx = (font as usize).min(self.fonts.len().saturating_sub(1));
        let font_arc = self.fonts.get(font_idx)?.clone();
        let size_q = (size_px * 2.0).round().clamp(8.0, 4096.0) as u16;
        let key = GlyphKey {
            font: font_idx as u32,
            size_q,
            glyph_id,
        };
        if let Some(slot) = self.glyphs.get(&key) {
            return Some(*slot);
        }

        let scale = PxScale::from(size_px.max(8.0));
        let scaled = font_arc.as_scaled(scale);
        let glyph: Glyph = font_arc
            .glyph_id(ch)
            .with_scale_and_position(scale, point(0.0, 0.0));
        let advance = scaled.h_advance(glyph.id);
        let v_metrics = scaled.ascent();
        let Some(outlined) = font_arc.outline_glyph(glyph) else {
            // Whitespace / no outline — cache an empty slot so the
            // layout step still walks the advance.
            let slot = GlyphSlot {
                uv_min: [0.0, 0.0],
                uv_max: [0.0, 0.0],
                px_w: 0,
                px_h: 0,
                bearing_x: 0.0,
                bearing_y: v_metrics,
                advance,
            };
            self.glyphs.insert(key, slot);
            return Some(slot);
        };

        let bbox = outlined.px_bounds();
        let w = bbox.width().ceil() as u32;
        let h = bbox.height().ceil() as u32;
        if w == 0 || h == 0 {
            let slot = GlyphSlot {
                uv_min: [0.0, 0.0],
                uv_max: [0.0, 0.0],
                px_w: 0,
                px_h: 0,
                bearing_x: 0.0,
                bearing_y: v_metrics,
                advance,
            };
            self.glyphs.insert(key, slot);
            return Some(slot);
        }

        // Advance the atlas cursor; wrap to a new row if needed.
        if self.cursor_x + w + 1 > self.width {
            self.cursor_x = 1;
            self.cursor_y += self.row_h + 1;
            self.row_h = 0;
        }
        if self.cursor_y + h + 1 > self.height {
            log::warn!("text atlas exhausted; new glyph dropped");
            // Reuse the topmost empty slot — produces a square placeholder.
            let slot = GlyphSlot {
                uv_min: [0.0, 0.0],
                uv_max: [0.0, 0.0],
                px_w: 0,
                px_h: 0,
                bearing_x: 0.0,
                bearing_y: v_metrics,
                advance,
            };
            self.glyphs.insert(key, slot);
            return Some(slot);
        }

        let dst_x = self.cursor_x;
        let dst_y = self.cursor_y;
        outlined.draw(|gx, gy, cov| {
            let px = dst_x + gx;
            let py = dst_y + gy;
            if px < self.width && py < self.height {
                let i = ((py * self.width + px) * 4) as usize;
                let a = (cov.clamp(0.0, 1.0) * 255.0) as u8;
                self.cpu_pixels[i] = a.max(self.cpu_pixels[i]);
            }
        });
        self.cursor_x += w + 1;
        self.row_h = self.row_h.max(h);
        self.dirty = true;

        let inv_w = 1.0 / self.width as f32;
        let inv_h = 1.0 / self.height as f32;
        let slot = GlyphSlot {
            uv_min: [dst_x as f32 * inv_w, dst_y as f32 * inv_h],
            uv_max: [(dst_x + w) as f32 * inv_w, (dst_y + h) as f32 * inv_h],
            px_w: w,
            px_h: h,
            bearing_x: bbox.min.x,
            bearing_y: bbox.min.y + v_metrics,
            advance,
        };
        self.glyphs.insert(key, slot);
        Some(slot)
    }

    /// Push any pending atlas-pixel updates to the GPU. Cheap when
    /// `dirty == false` (no-op, common case after warm-up).
    fn flush(&mut self, queue: &wgpu::Queue) {
        if !self.dirty {
            return;
        }
        queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: &self.texture,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &self.cpu_pixels,
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(self.width * 4),
                rows_per_image: Some(self.height),
            },
            wgpu::Extent3d {
                width: self.width,
                height: self.height,
                depth_or_array_layers: 1,
            },
        );
        self.dirty = false;
    }

    /// Number of glyphs currently cached. Test surface.
    pub fn glyph_count(&self) -> usize {
        self.glyphs.len()
    }
}

/// Text GPU pipeline. One render pipeline + a growable vertex buffer.
pub struct TextPipeline {
    pipeline: wgpu::RenderPipeline,
    bgl: wgpu::BindGroupLayout,
    vertex_buffer: wgpu::Buffer,
    vertex_capacity: u64,
    atlas: TextAtlas,
}

impl TextPipeline {
    pub fn new(device: &wgpu::Device, queue: &wgpu::Queue, format: wgpu::TextureFormat) -> Self {
        let shader = load_wgsl(device, "Text Shader", include_str!("../shaders/text.wgsl"));

        let bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("Text BGL"),
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: true },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
                    count: None,
                },
            ],
        });

        let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("Text Layout"),
            bind_group_layouts: &[Some(&bgl)],
            immediate_size: 0,
        });

        let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("Text Pipeline"),
            layout: Some(&layout),
            vertex: wgpu::VertexState {
                module: &shader,
                entry_point: Some("vs_main"),
                buffers: &[wgpu::VertexBufferLayout {
                    array_stride: std::mem::size_of::<TextQuadVertex>() as u64,
                    step_mode: wgpu::VertexStepMode::Vertex,
                    attributes: &[
                        wgpu::VertexAttribute {
                            format: wgpu::VertexFormat::Float32x2,
                            offset: 0,
                            shader_location: 0,
                        },
                        wgpu::VertexAttribute {
                            format: wgpu::VertexFormat::Float32x2,
                            offset: 8,
                            shader_location: 1,
                        },
                        wgpu::VertexAttribute {
                            format: wgpu::VertexFormat::Float32x4,
                            offset: 16,
                            shader_location: 2,
                        },
                    ],
                }],
                compilation_options: Default::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format,
                    blend: Some(wgpu::BlendState {
                        // Premultiplied alpha — the fragment shader
                        // already multiplies `rgb` by the effective
                        // alpha, so source factor is `One`.
                        color: wgpu::BlendComponent {
                            src_factor: wgpu::BlendFactor::One,
                            dst_factor: wgpu::BlendFactor::OneMinusSrcAlpha,
                            operation: wgpu::BlendOperation::Add,
                        },
                        alpha: wgpu::BlendComponent {
                            src_factor: wgpu::BlendFactor::One,
                            dst_factor: wgpu::BlendFactor::OneMinusSrcAlpha,
                            operation: wgpu::BlendOperation::Add,
                        },
                    }),
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: Default::default(),
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                ..Default::default()
            },
            depth_stencil: None,
            multisample: wgpu::MultisampleState::default(),
            multiview_mask: None,
            cache: None,
        });

        // Initial vertex buffer: 256 glyphs × 6 verts ≈ 49 KiB. Grows
        // on demand inside `record`.
        let vertex_capacity = 256 * 6 * std::mem::size_of::<TextQuadVertex>() as u64;
        let vertex_buffer = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("Text Vertex Buffer"),
            size: vertex_capacity,
            usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });

        let atlas = TextAtlas::new(device, queue);

        Self {
            pipeline,
            bgl,
            vertex_buffer,
            vertex_capacity,
            atlas,
        }
    }

    /// Borrow the atlas. Test surface.
    pub fn atlas(&self) -> &TextAtlas {
        &self.atlas
    }

    /// Render every queued text frame into `target`. No-op when the
    /// frame list is empty.
    #[allow(clippy::too_many_arguments)]
    pub fn record(
        &mut self,
        encoder: &mut wgpu::CommandEncoder,
        queue: &wgpu::Queue,
        device: &wgpu::Device,
        target: &wgpu::TextureView,
        frames: &[TextFrame],
        render_w: u32,
        render_h: u32,
    ) {
        if frames.is_empty() {
            return;
        }
        let mut verts: Vec<TextQuadVertex> = Vec::with_capacity(frames.len() * 32 * 6);
        for f in frames {
            self.append_text(&mut verts, f, render_w, render_h);
        }
        if verts.is_empty() {
            return;
        }
        self.atlas.flush(queue);

        // Grow vertex buffer if needed.
        let needed = (verts.len() * std::mem::size_of::<TextQuadVertex>()) as u64;
        if needed > self.vertex_capacity {
            let mut new_cap = self.vertex_capacity.max(1);
            while new_cap < needed {
                new_cap *= 2;
            }
            self.vertex_buffer = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("Text Vertex Buffer"),
                size: new_cap,
                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            self.vertex_capacity = new_cap;
        }
        queue.write_buffer(&self.vertex_buffer, 0, bytemuck::cast_slice(&verts));

        let bg = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("Text BG"),
            layout: &self.bgl,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&self.atlas.view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&self.atlas.sampler),
                },
            ],
        });

        let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("Text Pass"),
            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                view: target,
                resolve_target: None,
                ops: wgpu::Operations {
                    load: wgpu::LoadOp::Load,
                    store: wgpu::StoreOp::Store,
                },
                depth_slice: None,
            })],
            depth_stencil_attachment: None,
            timestamp_writes: None,
            occlusion_query_set: None,
            multiview_mask: None,
        });
        pass.set_pipeline(&self.pipeline);
        pass.set_bind_group(0, Some(&bg), &[]);
        pass.set_vertex_buffer(0, self.vertex_buffer.slice(..needed));
        pass.draw(0..verts.len() as u32, 0..1);
    }

    /// Layout one text frame and append its glyph quads to `verts`.
    /// Lines are split on `\n`; horizontal anchor centres each line on
    /// `frame.x`, vertical anchor centres the whole block on `frame.y`.
    fn append_text(
        &mut self,
        verts: &mut Vec<TextQuadVertex>,
        frame: &TextFrame,
        render_w: u32,
        render_h: u32,
    ) {
        if frame.text.is_empty() || render_w == 0 || render_h == 0 {
            return;
        }
        let size_px = frame.size_px.max(8.0);

        // Pre-pass: compute per-line widths so we can centre them.
        let lines: Vec<&str> = frame.text.split('\n').collect();
        let mut line_widths: Vec<f32> = Vec::with_capacity(lines.len());
        for line in &lines {
            let mut w = 0.0_f32;
            for ch in line.chars() {
                let gid = self
                    .atlas
                    .fonts
                    .get(frame.font.min(self.atlas.fonts.len() as u32 - 1) as usize)
                    .map(|f| f.glyph_id(ch).0)
                    .unwrap_or(0);
                if let Some(slot) = self.atlas.ensure_glyph(frame.font, size_px, gid, ch) {
                    w += slot.advance;
                }
            }
            line_widths.push(w);
        }
        let line_h = size_px * 1.25;
        let total_h = line_h * lines.len() as f32;

        // Convert anchor centre `[0,1]` screen → pixel.
        let anchor_px_x = frame.x * render_w as f32;
        let anchor_px_y = frame.y * render_h as f32;
        let mut pen_y = anchor_px_y - total_h * 0.5 + size_px;

        for (line, line_w) in lines.iter().zip(line_widths.iter()) {
            let mut pen_x = anchor_px_x - line_w * 0.5;
            for ch in line.chars() {
                let gid = self
                    .atlas
                    .fonts
                    .get(frame.font.min(self.atlas.fonts.len() as u32 - 1) as usize)
                    .map(|f| f.glyph_id(ch).0)
                    .unwrap_or(0);
                let Some(slot) = self.atlas.ensure_glyph(frame.font, size_px, gid, ch) else {
                    continue;
                };
                if slot.px_w > 0 && slot.px_h > 0 {
                    let x0_px = pen_x + slot.bearing_x;
                    let y0_px = pen_y + slot.bearing_y;
                    let x1_px = x0_px + slot.px_w as f32;
                    let y1_px = y0_px + slot.px_h as f32;
                    let x0 = (x0_px / render_w as f32) * 2.0 - 1.0;
                    let x1 = (x1_px / render_w as f32) * 2.0 - 1.0;
                    let y0 = 1.0 - (y0_px / render_h as f32) * 2.0;
                    let y1 = 1.0 - (y1_px / render_h as f32) * 2.0;
                    let [u0, v0] = slot.uv_min;
                    let [u1, v1] = slot.uv_max;
                    let rgba = frame.rgba;
                    let tl = TextQuadVertex {
                        pos_clip: [x0, y0],
                        uv: [u0, v0],
                        rgba,
                    };
                    let tr = TextQuadVertex {
                        pos_clip: [x1, y0],
                        uv: [u1, v0],
                        rgba,
                    };
                    let bl = TextQuadVertex {
                        pos_clip: [x0, y1],
                        uv: [u0, v1],
                        rgba,
                    };
                    let br = TextQuadVertex {
                        pos_clip: [x1, y1],
                        uv: [u1, v1],
                        rgba,
                    };
                    verts.extend_from_slice(&[tl, tr, bl, tr, br, bl]);
                }
                pen_x += slot.advance;
            }
            pen_y += line_h;
        }
    }
}

/// Load the two bundled fonts: `Ubuntu-Light` (index `0`) + `Hack-Regular`
/// (index `1`). Failures collapse to a one-font vec so the pipeline
/// always has something to lay out against; the dropped font logs once.
fn bundled_fonts() -> Vec<FontArc> {
    use epaint_default_fonts::{HACK_REGULAR, UBUNTU_LIGHT};
    let mut out = Vec::new();
    match FontVec::try_from_vec(UBUNTU_LIGHT.to_vec()) {
        Ok(f) => out.push(FontArc::from(f)),
        Err(e) => log::warn!("default font (Ubuntu-Light) load failed: {e}"),
    }
    match FontVec::try_from_vec(HACK_REGULAR.to_vec()) {
        Ok(f) => out.push(FontArc::from(f)),
        Err(e) => log::warn!("mono font (Hack-Regular) load failed: {e}"),
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn bundled_fonts_load_two_faces() {
        let fonts = bundled_fonts();
        assert_eq!(fonts.len(), 2, "expected Ubuntu-Light + Hack-Regular");
    }
}