Struct FontFallbackChain 

pub struct FontFallbackChain {
    pub css_fallbacks: Vec<CssFallbackGroup>,
    pub unicode_fallbacks: Vec<FontMatch>,
    pub original_stack: Vec<String>,
}

Resolved font fallback chain for a CSS font-family stack This represents the complete chain of fonts to use for rendering text

Fields

css_fallbacks: Vec<CssFallbackGroup>

CSS-based fallbacks: Each CSS font expanded to its system fallbacks Example: [“NotoSansJP” -> [Hiragino Sans, PingFang SC], “sans-serif” -> [Helvetica]]

unicode_fallbacks: Vec<FontMatch>

Unicode-based fallbacks: Fonts added to cover missing Unicode ranges Only populated if css_fallbacks don’t cover all requested characters

original_stack: Vec<String>

The original CSS font-family stack that was requested

Implementations

impl FontFallbackChain

pub fn resolve_char( &self, cache: &FcFontCache, ch: char, ) -> Option<(FontId, String)>

Resolve which font should be used for a specific character Returns (FontId, css_source_name) where css_source_name indicates which CSS font matched Returns None if no font in the chain can render this character

pub fn resolve_text( &self, cache: &FcFontCache, text: &str, ) -> Vec<(char, Option<(FontId, String)>)>

Resolve all characters in a text string to their fonts Returns a vector of (character, FontId, css_source) tuples

Examples found in repository

examples/unicode_aware_fonts.rs (line 73)

fn print_text_resolution(
    cache: &FcFontCache,
    chain: &rust_fontconfig::FontFallbackChain,
    text: &str,
) {
    let resolved = chain.resolve_text(cache, text);
    
    // Group consecutive characters by font
    let mut current_font: Option<String> = None;
    let mut current_segment = String::new();
    
    for (ch, font_info) in resolved {
        let font_name = font_info.map(|(id, _)| {
            cache.get_metadata_by_id(&id)
                .and_then(|p| p.name.clone().or(p.family.clone()))
                .unwrap_or_else(|| format!("{:?}", id))
        });
        
        if font_name != current_font {
            if !current_segment.is_empty() {
                println!("  '{}' -> {}", 
                         current_segment, 
                         current_font.as_deref().unwrap_or("[NO FONT]"));
                current_segment.clear();
            }
            current_font = font_name;
        }
        current_segment.push(ch);
    }
    
    if !current_segment.is_empty() {
        println!("  '{}' -> {}", 
                 current_segment, 
                 current_font.as_deref().unwrap_or("[NO FONT]"));
    }
}

examples/character_resolution.rs (line 56)

fn main() {
    let cache = FcFontCache::build();
        
    // Create a font chain with typical web defaults
    let families = vec![
        "system-ui".to_string(),
        "sans-serif".to_string(),
    ];
    
    let mut trace = Vec::new();
    let chain = cache.resolve_font_chain(
        &families,
        FcWeight::Normal,
        PatternMatch::False,
        PatternMatch::False,
        &mut trace,
    );
    
    // Test characters from different Unicode blocks
    let test_chars = vec![
        ('A', "Latin Capital Letter A"),
        ('a', "Latin Small Letter A"),
        ('0', "Digit Zero"),
        ('€', "Euro Sign"),
        ('→', "Rightwards Arrow"),
        ('中', "CJK Ideograph - China"),
        ('日', "CJK Ideograph - Sun/Day"),
        ('あ', "Hiragana Letter A"),
        ('ア', "Katakana Letter A"),
        ('한', "Hangul Syllable Han"),
        ('א', "Hebrew Letter Alef"),
        ('ا', "Arabic Letter Alef"),
        ('α', "Greek Small Letter Alpha"),
        ('Σ', "Greek Capital Letter Sigma"),
        ('я', "Cyrillic Small Letter Ya"),
        ('🙂', "Slightly Smiling Face"),
        ('♠', "Black Spade Suit"),
        ('∑', "N-ary Summation"),
        ('∞', "Infinity"),
        ('℃', "Degree Celsius"),
    ];
    
    println!("Character resolution results:\n");
    println!("{:<6} {:<30} {:<40}", "Char", "Description", "Font");
    println!("{}", "-".repeat(80));
    
    for (ch, description) in test_chars {
        let text = ch.to_string();
        let resolved = chain.resolve_text(&cache, &text);
        
        let font_name = resolved.first()
            .and_then(|(_, info)| info.as_ref())
            .and_then(|(id, _)| cache.get_metadata_by_id(id))
            .and_then(|m| m.name.clone().or(m.family.clone()))
            .unwrap_or_else(|| "⚠ NOT FOUND".to_string());
        
        println!("{:<6} {:<30} {}", ch, description, font_name);
    }
    
    // Show how to check if a specific font covers a character
    println!("\n\nFont Coverage Check\n");
    
    let pattern = rust_fontconfig::FcPattern {
        family: Some("Arial".to_string()),
        ..Default::default()
    };
    
    if let Some(match_result) = cache.query(&pattern, &mut Vec::new()) {
        println!("Checking Arial coverage:");
        
        // Create a chain just for Arial
        let arial_chain = cache.resolve_font_chain(
            &vec!["Arial".to_string()],
            FcWeight::Normal,
            PatternMatch::False,
            PatternMatch::False,
            &mut Vec::new(),
        );
        
        let check_chars = ['A', '中', '🙂', '→'];
        for ch in check_chars {
            let resolved = arial_chain.resolve_text(&cache, &ch.to_string());
            let found_in_arial = resolved.first()
                .and_then(|(_, info)| info.as_ref())
                .map(|(id, _)| id == &match_result.id)
                .unwrap_or(false);
            
            let status = if found_in_arial { "✓" } else { "✗" };
            println!("  {} '{}' (U+{:04X})", status, ch, ch as u32);
        }
    }
    
    // Show codepoint ranges supported
    println!("\n\nUnicode Block Coverage Summary\n");
    
    let blocks = [
        ("Basic Latin", 0x0020..0x007F),
        ("Latin Extended-A", 0x0100..0x017F),
        ("Greek", 0x0370..0x03FF),
        ("Cyrillic", 0x0400..0x04FF),
        ("Arabic", 0x0600..0x06FF),
        ("CJK Unified Ideographs", 0x4E00..0x9FFF),
        ("Hiragana", 0x3040..0x309F),
        ("Katakana", 0x30A0..0x30FF),
    ];
    
    for (name, range) in blocks {
        // Sample a few codepoints from each block
        let sample_points: Vec<char> = range.clone()
            .step_by(range.len() / 5)
            .take(5)
            .filter_map(|cp| char::from_u32(cp))
            .collect();
        
        let sample_text: String = sample_points.iter().collect();
        let resolved = chain.resolve_text(&cache, &sample_text);
        
        let fonts_used: std::collections::HashSet<_> = resolved.iter()
            .filter_map(|(_, info)| info.as_ref())
            .map(|(id, _)| id.clone())
            .collect();
        
        let coverage = resolved.iter()
            .filter(|(_, info)| info.is_some())
            .count() as f32 / resolved.len() as f32 * 100.0;
        
        println!("{:<30} {:>6.1}% coverage ({} fonts)", name, coverage, fonts_used.len());
    }
}

examples/integration_api.rs (line 67)

fn main() {
    println!("Font Integration API Example\n");
    
    // Step 1: Build the font cache once at application startup
    println!("Step 1: Building font cache...");
    let cache = FcFontCache::build();
    println!("  Loaded {} fonts\n", cache.list().len());
    
    // Step 2: Simulate CSS font-family resolution
    // This is what a browser/text renderer would do
    println!("Step 2: Resolving CSS font-family: 'Helvetica, Arial, sans-serif'\n");
    
    let css_families = vec![
        "Helvetica".to_string(),
        "Arial".to_string(),
        "sans-serif".to_string(),
    ];
    
    let mut trace = Vec::new();
    let chain = cache.resolve_font_chain(
        &css_families,
        FcWeight::Normal,
        PatternMatch::False,  // italic
        PatternMatch::False,  // oblique
        &mut trace,
    );
    
    println!("  CSS fallback groups: {}", chain.css_fallbacks.len());
    for (i, group) in chain.css_fallbacks.iter().enumerate() {
        println!("    {}: CSS '{}' -> {} fonts", i + 1, group.css_name, group.fonts.len());
        for font in group.fonts.iter().take(2) {
            if let Some(meta) = cache.get_metadata_by_id(&font.id) {
                let name = meta.name.as_ref().or(meta.family.as_ref());
                println!("       - {:?}", name);
            }
        }
        if group.fonts.len() > 2 {
            println!("       ... and {} more", group.fonts.len() - 2);
        }
    }
    
    println!("\n  Unicode fallback fonts: {}", chain.unicode_fallbacks.len());
    for (i, font) in chain.unicode_fallbacks.iter().take(3).enumerate() {
        if let Some(meta) = cache.get_metadata_by_id(&font.id) {
            println!("    {}: {:?}", 
                     i + 1, 
                     meta.name.as_ref().or(meta.family.as_ref()));
        }
    }
    if chain.unicode_fallbacks.len() > 3 {
        println!("    ... and {} more", chain.unicode_fallbacks.len() - 3);
    }
    
    // Step 3: Resolve text to fonts
    // This maps each character to a specific font
    println!("\n\nStep 3: Resolve text to fonts");
    
    let text = "Hello 世界! Привет мир";
    println!("  Input text: '{}'\n", text);
    
    let resolved = chain.resolve_text(&cache, text);
    
    // Group by runs of same font
    let mut runs = Vec::new();
    let mut current_run_text = String::new();
    let mut current_font_id: Option<FontId> = None;
    
    for (ch, font_info) in &resolved {
        let this_font_id = font_info.as_ref().map(|(id, _)| *id);
        
        if this_font_id != current_font_id {
            if !current_run_text.is_empty() {
                runs.push((current_run_text.clone(), current_font_id));
                current_run_text.clear();
            }
            current_font_id = this_font_id;
        }
        current_run_text.push(*ch);
    }
    if !current_run_text.is_empty() {
        runs.push((current_run_text, current_font_id));
    }
    
    println!("  Font runs:");
    for (run_text, font_id) in &runs {
        let font_name = font_id.as_ref()
            .and_then(|id| cache.get_metadata_by_id(id))
            .and_then(|m| m.name.clone().or(m.family.clone()))
            .unwrap_or_else(|| "[NO FONT]".to_string());
        println!("    '{}' -> {}", run_text, font_name);
    }
    
    // Step 4: Load font data for shaping
    // In a real application, you'd load font bytes here
    println!("\n\nStep 4: Loading fonts for shaping");
    
    // Collect unique font IDs needed for this text
    let unique_fonts: std::collections::HashSet<_> = runs.iter()
        .filter_map(|(_, id)| *id)
        .collect();
    
    println!("  Unique fonts needed: {}", unique_fonts.len());
    
    for font_id in &unique_fonts {
        if let Some(meta) = cache.get_metadata_by_id(font_id) {
            println!("    - {:?}", meta.name.as_ref().or(meta.family.as_ref()));
            // Get font path via get_font_by_id
            if let Some(source) = cache.get_font_by_id(font_id) {
                match source {
                    rust_fontconfig::FontSource::Disk(path) => {
                        // In real code, you'd load the font file here:
                        // let bytes = std::fs::read(&path.path)?;
                        // let parsed = ttf_parser::Face::parse(&bytes, path.font_index as u32)?;
                        println!("      Path: {}", path.path);
                    }
                    rust_fontconfig::FontSource::Memory(font) => {
                        println!("      Memory font (id: {})", font.id);
                    }
                }
            }
        }
    }
    
    println!("\nWorkflow summary:");
    println!("");
    println!("1. FcFontCache::build() - once at startup");
    println!("2. cache.resolve_font_chain() - per CSS font-family declaration");
    println!("3. chain.resolve_text(\"abc\") -> [Run {{ font, glyphs: \"abc\" }}] - per text string to shape");
    println!("4. Load font bytes and shape each run with its font");
}

pub fn query_for_text( &self, cache: &FcFontCache, text: &str, ) -> Vec<ResolvedFontRun>

Query which fonts should be used for a text string, grouped by font Returns runs of consecutive characters that use the same font This is the main API for text shaping - call this to get font runs, then shape each run

Trait Implementations

impl Clone for FontFallbackChain

fn clone(&self) -> FontFallbackChain

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for FontFallbackChain

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

Formats the value using the given formatter.

impl PartialEq for FontFallbackChain

fn eq(&self, other: &FontFallbackChain) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for FontFallbackChain

impl StructuralPartialEq for FontFallbackChain