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 54)

fn print_resolution(cache: &FcFontCache, chain: &FontFallbackChain, text: &str) {
    let resolved = chain.resolve_text(cache, text);

    let mut current_font: Option<String> = None;
    let mut segment = String::new();

    for (ch, info) in &resolved {
        let font_name = info.as_ref().and_then(|(id, _)| {
            cache
                .get_metadata_by_id(id)
                .and_then(|m| m.name.clone().or(m.family.clone()))
        });
        if font_name != current_font {
            if !segment.is_empty() {
                println!(
                    "  '{}' -> {}",
                    segment,
                    current_font.as_deref().unwrap_or("[NO FONT]")
                );
                segment.clear();
            }
            current_font = font_name;
        }
        segment.push(*ch);
    }
    if !segment.is_empty() {
        println!(
            "  '{}' -> {}",
            segment,
            current_font.as_deref().unwrap_or("[NO FONT]")
        );
    }
}

examples/character_resolution.rs (line 53)

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 chain = cache.resolve_font_chain(
        &families,
        FcWeight::Normal,
        PatternMatch::False,
        PatternMatch::False,
        &mut Vec::new(),
    );

    // Test characters from different Unicode blocks
    let test_chars = [
        ('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"),
        ('я', "Cyrillic Small Letter Ya"),
        ('🙂', "Slightly Smiling Face"),
        ('♠', "Black Spade Suit"),
        ('∑', "N-ary Summation"),
        ('∞', "Infinity"),
    ];

    println!("Character resolution results:\n");
    println!("{:<6} {:<30} {:<40}", "Char", "Description", "Font");
    println!("{}", "-".repeat(76));

    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);
    }

    // Check specific font coverage
    println!("\n\nArial coverage check:");
    let arial_chain = cache.resolve_font_chain(
        &["Arial".to_string()],
        FcWeight::Normal,
        PatternMatch::False,
        PatternMatch::False,
        &mut Vec::new(),
    );

    let arial_result = cache.query(
        &rust_fontconfig::FcPattern {
            family: Some("Arial".to_string()),
            ..Default::default()
        },
        &mut Vec::new(),
    );

    if let Some(arial_match) = arial_result {
        for ch in ['A', '中', '🙂', '→'] {
            let resolved = arial_chain.resolve_text(&cache, &ch.to_string());
            let in_arial = resolved
                .first()
                .and_then(|(_, info)| info.as_ref())
                .map(|(id, _)| id == &arial_match.id)
                .unwrap_or(false);

            println!(
                "  {} '{}' (U+{:04X})",
                if in_arial { "✓" } else { "✗" },
                ch,
                ch as u32
            );
        }
    } else {
        println!("  Arial not found on this system");
    }
}

examples/integration_api.rs (line 56)

fn main() {
    println!("=== Font Integration Pipeline ===\n");

    // ── Step 1: Build font cache ──
    println!("Step 1: Build font cache");
    let cache = FcFontCache::build();
    println!("  {} fonts loaded\n", cache.list().len());

    // ── Step 2: Resolve CSS font-family ──
    let css_families = vec![
        "Helvetica".to_string(),
        "Arial".to_string(),
        "sans-serif".to_string(),
    ];
    println!("Step 2: Resolve font-family: {:?}\n", css_families);

    let chain = cache.resolve_font_chain(
        &css_families,
        FcWeight::Normal,
        PatternMatch::False,
        PatternMatch::False,
        &mut Vec::new(),
    );

    for (i, group) in chain.css_fallbacks.iter().enumerate() {
        print!("  [{}] '{}': {} fonts", i + 1, group.css_name, group.fonts.len());
        if let Some(first) = group.fonts.first() {
            if let Some(meta) = cache.get_metadata_by_id(&first.id) {
                print!(
                    " (first: {:?})",
                    meta.name.as_ref().or(meta.family.as_ref())
                );
            }
        }
        println!();
    }
    println!(
        "  + {} unicode fallback fonts\n",
        chain.unicode_fallbacks.len()
    );

    // ── Step 3: Resolve text to font runs ──
    let text = "Hello 世界! Привет мир";
    println!("Step 3: Resolve text: '{}'\n", text);

    let resolved = chain.resolve_text(&cache, text);

    // Group by runs of same font
    let mut runs: Vec<(String, Option<FontId>)> = Vec::new();
    let mut current_text = String::new();
    let mut current_id: Option<FontId> = None;

    for (ch, info) in &resolved {
        let this_id = info.as_ref().map(|(id, _)| *id);
        if this_id != current_id {
            if !current_text.is_empty() {
                runs.push((current_text.clone(), current_id));
                current_text.clear();
            }
            current_id = this_id;
        }
        current_text.push(*ch);
    }
    if !current_text.is_empty() {
        runs.push((current_text, current_id));
    }

    println!("  Font runs:");
    for (run_text, font_id) in &runs {
        let 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]".into());
        println!("    '{}' -> {}", run_text, name);
    }

    // ── Step 4: Load font bytes ──
    let unique_fonts: std::collections::HashSet<_> =
        runs.iter().filter_map(|(_, id)| *id).collect();

    println!(
        "\nStep 4: Load fonts ({} unique needed)\n",
        unique_fonts.len()
    );
    for font_id in &unique_fonts {
        if let Some(meta) = cache.get_metadata_by_id(font_id) {
            let name = meta
                .name
                .as_ref()
                .or(meta.family.as_ref())
                .map(|s| s.as_str())
                .unwrap_or("?");
            if let Some(source) = cache.get_font_by_id(font_id) {
                match source {
                    rust_fontconfig::FontSource::Disk(path) => {
                        println!("  {} -> {}", name, path.path);
                    }
                    rust_fontconfig::FontSource::Memory(font) => {
                        println!("  {} -> memory (id: {})", name, font.id);
                    }
                }
            }
        }
    }

    println!("\nPipeline summary:");
    println!("  1. FcFontCache::build()       — once at startup");
    println!("  2. cache.resolve_font_chain() — per CSS font-family");
    println!("  3. chain.resolve_text()       — per text run");
    println!("  4. cache.get_font_by_id()     — load bytes for shaping");
}

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