Struct FcFontCache 

pub struct FcFontCache { /* private fields */ }

Font cache, initialized at startup

Implementations

impl FcFontCache

pub fn with_memory_fonts( &mut self, fonts: Vec<(FcPattern, FcFont)>, ) -> &mut Self

Adds in-memory font files

pub fn with_memory_font_with_id( &mut self, id: FontId, pattern: FcPattern, font: FcFont, ) -> &mut Self

Adds a memory font with a specific ID (for testing)

pub fn get_font_by_id<'a>(&'a self, id: &FontId) -> Option<FontSource<'a>>

Get font data for a given font ID

pub fn get_metadata_by_id(&self, id: &FontId) -> Option<&FcPattern>

Get metadata directly from an ID

pub fn get_font_bytes_arc(&self, id: &FontId) -> Option<Arc<[u8]>>

Get font bytes as a shared Arc<[u8]>.

When bytes_hash != 0, multiple FontIds backed by the same file content (e.g. every face of a .ttc, or two disk paths holding identical bytes) get the same Arc<[u8]> — so the underlying bytes are allocated and read from disk exactly once for as long as any consumer keeps an Arc alive.

When bytes_hash == 0 (legacy fallback, filename-only scan, v1 disk cache), this degrades to a fresh Arc::from(Vec<u8>) with no sharing. Correct, just not deduplicated.

Prefer this over FcFontCache::get_font_bytes in any long-lived parser that might otherwise hold many copies of the same file in memory.

Implementation note (mmap follow-up): We deliberately stay on the heap-backed fs::read path instead of returning mmapio::Mmap-backed bytes. The two reasons:

1. The public return type is Arc<[u8]> — a fat-pointer to an inline allocation. Constructing one from a Mmap without a copy requires either (a) an unsafe fat-pointer cast that leaks the Mmap, or (b) a wrapping trait object like Arc<dyn AsRef<[u8]> + Send + Sync> which is a breaking API change.
2. On macOS / Linux the kernel page cache already deduplicates the underlying file pages across processes, so fs::read only pays for the heap copy — and downstream LocaGlyf::load walks the whole glyf table anyway, so every page would be faulted in regardless of mmap-vs-heap. The current Arc-shared dedup (one Arc<[u8]> per unique bytes_hash, weak-ref tracked) already eliminates the “5 faces of HelveticaNeue.ttc each allocate 4.27 MiB” duplication. Switching to mmap is a follow-up worth revisiting if a use case shows up where touched-pages-only is meaningfully smaller than full-file (e.g. shaping with only ~hundreds of glyphs out of ~thousands).

pub fn get_font_bytes(&self, id: &FontId) -> Option<Vec<u8>>

Get font bytes (either from disk or memory) as an owned Vec<u8>.

Back-compat wrapper around FcFontCache::get_font_bytes_arc; clones the shared buffer. New call sites that might hold the result for more than a brief parse should prefer the _arc variant so the bytes get deduplicated across faces.

pub fn build() -> Self

Scans system font directories using filename heuristics (no allsorts).

pub fn is_memory_font(&self, id: &FontId) -> bool

Check if a font ID is a memory font (preferred over disk fonts)

pub fn list(&self) -> Vec<(&FcPattern, FontId)>

Returns the list of fonts and font patterns

pub fn is_empty(&self) -> bool

Returns true if the cache contains no font patterns

pub fn len(&self) -> usize

Returns the number of font patterns in the cache

pub fn query( &self, pattern: &FcPattern, trace: &mut Vec<TraceMsg>, ) -> Option<FontMatch>

Queries a font from the in-memory cache, returns the first found font (early return) Memory fonts are always preferred over disk fonts with the same match quality.

pub fn compute_fallbacks( &self, font_id: &FontId, trace: &mut Vec<TraceMsg>, ) -> Vec<FontMatchNoFallback>

Compute fallback fonts for a given font This is a lazy operation that can be expensive - only call when actually needed (e.g., for FFI or debugging, not needed for resolve_char)

pub fn get_memory_font(&self, id: &FontId) -> Option<&FcFont>

Get in-memory font data

pub fn query_matches_internal( k: &FcPattern, pattern: &FcPattern, trace: &mut Vec<TraceMsg>, ) -> bool

pub fn resolve_font_chain( &self, font_families: &[String], weight: FcWeight, italic: PatternMatch, oblique: PatternMatch, trace: &mut Vec<TraceMsg>, ) -> FontFallbackChain

Resolve a complete font fallback chain for a CSS font-family stack This is the main entry point for font resolution with caching Automatically expands generic CSS families (serif, sans-serif, monospace) to OS-specific fonts

Arguments

• font_families - CSS font-family stack (e.g., [“Arial”, “sans-serif”])
• text - The text to render (used to extract Unicode ranges)
• weight - Font weight
• italic - Italic style requirement
• oblique - Oblique style requirement
• trace - Debug trace messages

Returns

A complete font fallback chain with CSS fallbacks and Unicode fallbacks

Example

let cache = FcFontCache::build();
let families = vec!["Arial".to_string(), "sans-serif".to_string()];
let chain = cache.resolve_font_chain(&families, FcWeight::Normal, 
                                      PatternMatch::DontCare, PatternMatch::DontCare, 
                                      &mut Vec::new());
// On macOS: families expanded to ["Arial", "San Francisco", "Helvetica Neue", "Lucida Grande"]

pub fn resolve_font_chain_with_os( &self, font_families: &[String], weight: FcWeight, italic: PatternMatch, oblique: PatternMatch, trace: &mut Vec<TraceMsg>, os: OperatingSystem, ) -> FontFallbackChain

Resolve font chain with explicit OS specification (useful for testing)

pub fn resolve_font_chain_with_scripts( &self, font_families: &[String], weight: FcWeight, italic: PatternMatch, oblique: PatternMatch, scripts_hint: Option<&[UnicodeRange]>, trace: &mut Vec<TraceMsg>, ) -> FontFallbackChain

Resolve a font fallback chain, restricting Unicode fallbacks to the caller-supplied set of scripts (usually derived from the actual text content of the document).

• scripts_hint: None → back-compat behaviour, equivalent to FcFontCache::resolve_font_chain: pulls in fallback fonts for the full DEFAULT_UNICODE_FALLBACK_SCRIPTS set.
• scripts_hint: Some(&[]) → no Unicode fallbacks attached. For an ASCII-only page this avoids pulling Arial Unicode MS, CJK fonts, etc. into memory when they’re not needed.
• scripts_hint: Some(&[CJK]) → only CJK fallback attached.

The chain cache is keyed so an ASCII-only resolution cannot be served from a slot populated by a default/all-scripts resolution.

pub fn extract_font_name_tokens(name: &str) -> Vec<String>

Extract tokens from a font name E.g., “NotoSansJP” -> [“Noto”, “Sans”, “JP”] E.g., “Noto Sans CJK JP” -> [“Noto”, “Sans”, “CJK”, “JP”]

pub fn calculate_unicode_coverage(ranges: &[UnicodeRange]) -> u64

Find fallback fonts for a given pattern

pub fn calculate_unicode_compatibility( requested: &[UnicodeRange], available: &[UnicodeRange], ) -> i32

Calculate how well a font’s Unicode ranges cover the requested ranges Returns a compatibility score (higher is better, 0 means no overlap)

pub fn calculate_style_score(original: &FcPattern, candidate: &FcPattern) -> i32

Trait Implementations

impl Clone for FcFontCache

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FcFontCache

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FcFontCache

fn default() -> Self

Returns the “default value” for a type.