rpdfium_render/

cfx_glyphcache.rs

// Derived from PDFium's rasterized glyph cache concepts
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! Rasterized glyph cache — caches pre-rendered glyph bitmaps for fast
//! text rendering at common sizes.
//!
//! Glyph outlines are rasterized to small alpha bitmaps and cached by
//! (font identity, glyph ID, quantized size). This avoids re-rasterizing
//! the same glyph at the same size for every occurrence.

use std::collections::HashMap;

/// Maximum number of entries in the rasterized glyph cache.
const MAX_RASTER_CACHE: usize = 2048;

/// Maximum font size (in points) for which rasterized glyphs are cached.
/// Larger sizes benefit less from caching and use more memory per glyph.
pub const MAX_CACHED_SIZE: f32 = 48.0;

/// Cache key identifying a specific glyph at a specific size.
#[derive(Hash, PartialEq, Eq, Clone, Copy, Debug)]
pub struct RasterGlyphKey {
    /// Identity of the font (pointer address or hash).
    pub font_id: usize,
    /// Glyph ID within the font.
    pub glyph_id: u16,
    /// Quantized size (to nearest 0.5pt, encoded as `(size * 2).round() as u32`).
    pub size_q: u32,
}

/// A pre-rasterized glyph bitmap (alpha channel only).
#[derive(Debug, Clone)]
pub struct RasterGlyph {
    /// Width of the rasterized bitmap in pixels.
    pub width: u32,
    /// Height of the rasterized bitmap in pixels.
    pub height: u32,
    /// Horizontal bearing (x offset from pen position to left edge of bitmap).
    pub bearing_x: i32,
    /// Vertical bearing (y offset from pen position to top edge of bitmap).
    pub bearing_y: i32,
    /// Alpha channel data, row-major, one byte per pixel.
    pub alpha: Vec<u8>,
}

/// Cache for pre-rasterized glyph alpha bitmaps.
///
/// Stores rendered glyphs indexed by font, glyph ID, and quantized size.
/// `None` entries mean "this glyph was looked up but has no outline" (negative cache).
#[derive(Debug)]
pub struct RasterizedGlyphCache {
    cache: HashMap<RasterGlyphKey, Option<RasterGlyph>>,
}

impl Default for RasterizedGlyphCache {
    fn default() -> Self {
        Self::new()
    }
}

impl RasterizedGlyphCache {
    /// Create a new empty cache.
    pub fn new() -> Self {
        Self {
            cache: HashMap::new(),
        }
    }

    /// Quantize a font size to the nearest 0.5pt for cache key generation.
    pub fn quantize_size(size: f32) -> u32 {
        (size * 2.0).round() as u32
    }

    /// Look up a cached glyph. Returns:
    /// - `Some(Some(glyph))` — cached rasterized glyph
    /// - `Some(None)` — negative cache hit (glyph has no outline)
    /// - `None` — cache miss
    pub fn get(&self, key: &RasterGlyphKey) -> Option<&Option<RasterGlyph>> {
        self.cache.get(key)
    }

    /// Insert a rasterized glyph (or negative cache entry) into the cache.
    ///
    /// If the cache is full, evicts approximately 25% of entries.
    pub fn insert(&mut self, key: RasterGlyphKey, glyph: Option<RasterGlyph>) {
        if self.cache.len() >= MAX_RASTER_CACHE {
            self.evict();
        }
        self.cache.insert(key, glyph);
    }

    /// Returns the number of entries in the cache.
    pub fn len(&self) -> usize {
        self.cache.len()
    }

    /// Returns `true` if the cache is empty.
    pub fn is_empty(&self) -> bool {
        self.cache.is_empty()
    }

    /// Evict approximately 25% of entries when the cache is full.
    fn evict(&mut self) {
        let target = self.cache.len() / 4;
        let keys: Vec<RasterGlyphKey> = self.cache.keys().take(target).copied().collect();
        for key in keys {
            self.cache.remove(&key);
        }
    }
}

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

    #[test]
    fn test_quantize_size_rounds() {
        assert_eq!(RasterizedGlyphCache::quantize_size(12.0), 24);
        assert_eq!(RasterizedGlyphCache::quantize_size(12.5), 25);
        assert_eq!(RasterizedGlyphCache::quantize_size(12.25), 25); // rounds to 12.5
        assert_eq!(RasterizedGlyphCache::quantize_size(12.74), 25);
        assert_eq!(RasterizedGlyphCache::quantize_size(0.0), 0);
    }

    #[test]
    fn test_cache_miss_returns_none() {
        let cache = RasterizedGlyphCache::new();
        let key = RasterGlyphKey {
            font_id: 1,
            glyph_id: 42,
            size_q: 24,
        };
        assert!(cache.get(&key).is_none());
    }

    #[test]
    fn test_cache_insert_and_hit() {
        let mut cache = RasterizedGlyphCache::new();
        let key = RasterGlyphKey {
            font_id: 1,
            glyph_id: 42,
            size_q: 24,
        };
        let glyph = RasterGlyph {
            width: 10,
            height: 12,
            bearing_x: 1,
            bearing_y: 11,
            alpha: vec![128; 120],
        };
        cache.insert(key, Some(glyph));
        assert_eq!(cache.len(), 1);
        let result = cache.get(&key);
        assert!(result.is_some());
        let glyph = result.unwrap().as_ref().unwrap();
        assert_eq!(glyph.width, 10);
        assert_eq!(glyph.height, 12);
    }

    #[test]
    fn test_negative_cache_entry() {
        let mut cache = RasterizedGlyphCache::new();
        let key = RasterGlyphKey {
            font_id: 1,
            glyph_id: 999,
            size_q: 24,
        };
        cache.insert(key, None);
        assert_eq!(cache.len(), 1);
        let result = cache.get(&key);
        assert!(result.is_some());
        assert!(result.unwrap().is_none());
    }

    #[test]
    fn test_cache_eviction() {
        let mut cache = RasterizedGlyphCache::new();
        // Fill beyond MAX_RASTER_CACHE
        for i in 0..MAX_RASTER_CACHE + 10 {
            let key = RasterGlyphKey {
                font_id: 1,
                glyph_id: i as u16,
                size_q: 24,
            };
            cache.insert(key, None);
        }
        // After eviction, cache should be smaller than MAX_RASTER_CACHE + 10
        assert!(cache.len() <= MAX_RASTER_CACHE);
    }

    #[test]
    fn test_cache_empty_and_len() {
        let mut cache = RasterizedGlyphCache::new();
        assert!(cache.is_empty());
        assert_eq!(cache.len(), 0);
        let key = RasterGlyphKey {
            font_id: 1,
            glyph_id: 1,
            size_q: 24,
        };
        cache.insert(key, None);
        assert!(!cache.is_empty());
        assert_eq!(cache.len(), 1);
    }

    #[test]
    fn test_different_sizes_different_keys() {
        let mut cache = RasterizedGlyphCache::new();
        let key1 = RasterGlyphKey {
            font_id: 1,
            glyph_id: 42,
            size_q: 24, // 12pt
        };
        let key2 = RasterGlyphKey {
            font_id: 1,
            glyph_id: 42,
            size_q: 48, // 24pt
        };
        cache.insert(
            key1,
            Some(RasterGlyph {
                width: 10,
                height: 12,
                bearing_x: 1,
                bearing_y: 11,
                alpha: vec![],
            }),
        );
        cache.insert(
            key2,
            Some(RasterGlyph {
                width: 20,
                height: 24,
                bearing_x: 2,
                bearing_y: 22,
                alpha: vec![],
            }),
        );
        assert_eq!(cache.len(), 2);
        assert_eq!(cache.get(&key1).unwrap().as_ref().unwrap().width, 10);
        assert_eq!(cache.get(&key2).unwrap().as_ref().unwrap().width, 20);
    }

    #[test]
    fn test_raster_glyph_key_eq_and_hash() {
        let key1 = RasterGlyphKey {
            font_id: 1,
            glyph_id: 42,
            size_q: 24,
        };
        let key2 = RasterGlyphKey {
            font_id: 1,
            glyph_id: 42,
            size_q: 24,
        };
        assert_eq!(key1, key2);

        let mut set = std::collections::HashSet::new();
        set.insert(key1);
        assert!(set.contains(&key2));
    }

    #[test]
    fn test_max_cached_size_constant() {
        assert_eq!(MAX_CACHED_SIZE, 48.0);
    }
}