Files
harfbuzz/test/api/fonts/ContextFormat2-Depend-Test.ttf
Skef Iterum 29cf3aa519 Add depend API: graph extraction with contextual filtering
This commit implements the experimental depend API for extracting glyph
dependency graphs from OpenType fonts. The depend API provides the foundation
for computing glyph closures and analyzing font structure.

The implementation significantly improves upon the initial draft (commit
3f59433d5) by adding contextual filtering to reduce over-approximation while
still capturing complete dependency graphs.

Core Architecture
-----------------

The depend implementation operates in graph extraction mode: it walks all font
tables once to build a complete dependency graph. The key innovation is
contextual filtering that reduces over-approximation compared to the naive
approach.

Contextual Filtering for Reduced Over-Approximation
----------------------------------------------------

The initial implementation (3f59433d5) recorded dependencies for ALL glyphs in
every lookup's coverage, leading to significant over-approximation. The current
implementation filters dependencies based on context:

**Individual Lookups**: Each lookup's depend() method filters by active glyphs:

  // Old approach (3f59433d5)
  + hb_iter (this+coverage)  // ALL coverage glyphs
  | hb_apply (record_dependency)

  // New approach
  hb_set_t intersection;
  (this+coverage).intersect_set (c->parent_active_glyphs(), intersection);
  + hb_iter (intersection)  // ONLY contextually relevant glyphs
  | hb_apply (record_dependency)

**Contextual Lookups**: ContextFormat1/2/3 and ChainContextFormat1/2/3 set up
active glyph contexts for nested lookups:

  hb_set_t* cur_active_glyphs = c->push_cur_active_glyphs();
  get_coverage().intersect_set(*c->glyphs, *cur_active_glyphs);

  // Process rules with filtered coverage
  + hb_zip (this+coverage, ruleSet)
  | hb_filter ([&] (hb_codepoint_t g) {
      return c->parent_active_glyphs().has(g);
    }, hb_first)
  | hb_apply (process_rule)

This significantly reduces over-approximation for simple cases while maintaining
complete graph coverage.

**Intentional Over-Approximation at Nested Boundaries**: When contextual rules
invoke nested lookups, we pass ALL glyphs to ensure no edges are missed:

  // In context_depend_recurse_lookups()
  cur_active_glyphs->set (*c->glyphs);  // Universe for nested lookups

This design choice prioritizes completeness over precision at contextual
boundaries, which is appropriate for graph extraction.

Edge Deduplication and Performance
-----------------------------------

Dependency extraction can generate millions of potential edges. To maintain
acceptable performance:

- Edge hashing (compute_edge_hash): O(1) duplicate detection via hash table
  keyed on (source, table_tag, layout_tag, dependent, ligature_set_contents)
- Hash collision handling: Falls back to O(n) linear search through glyph's
  existing dependencies only on collision (rare)
- Component vectors: Stores edge components for collision detection
- Post-extraction cleanup: Frees temporary structures (edge_hashes,
  lookup_features) to reduce memory footprint

Table-Specific Extraction
--------------------------

- **cmap**: Unicode → glyph mappings including UVS (Unicode Variation Sequences)
- **GSUB**: All substitution rules with feature tags and ligature set tracking
  - Handles all 8 GSUB lookup types including Extension (type 7)
  - Records which features reference each dependency
  - Groups ligature alternatives via ligature_set indices
- **glyf**: TrueType composite glyph components
- **CFF**: CFF1 SEAC (Standard Encoding Accented Character) composites
- **COLR**: Color layer dependencies for both COLRv0 and COLRv1
  - Filters self-referential PaintGlyph to prevent trivial cycles
- **MATH**: Mathematical variant glyphs and assembly components

CFF SEAC dependencies use table_tag='CFF ' with layout_tag=0 and
ligature_set=HB_CODEPOINT_INVALID, matching the pattern used for glyf.

Data Structure: hb_depend_data_record_t
----------------------------------------

Each dependency edge contains:
- table_tag: Source table (GSUB, glyf, CFF, COLR, MATH, cmap)
- dependent: Target glyph ID
- layout_tag: Feature tag (for GSUB) or UVS codepoint (for cmap), else 0
- ligature_set: Index into sets array for ligature alternatives, else INVALID
- context_set: Reserved for future contextual filtering (currently unused)

Graph stored as vector indexed by glyph ID, each containing vector of records.

Testing and Documentation
--------------------------

- test/api/test-ot-depend.c: Comprehensive test suite (645 lines)
  - Tests all table types and GSUB substitution formats
  - Includes regression tests for edge cases
  - Uses ContextFormat2-Depend-Test.ttf (minimized from 486KB to 85KB)

- test/fuzzing/hb-depend-fuzzer.cc: Production-quality closure implementation
  - Demonstrates correct ligature set handling
  - Includes feature filtering and over-approximation analysis
  - Reference implementation for depend-based closure computation

- docs/depend-api.md: Public API documentation with usage examples
- docs/depend-for-closure.md: Guide to using depend for closure computation
- docs/depend-implementation.md: Implementation details and architecture

Build System
-------------

- Meson option: -Ddepend_api=true
- Compile flag: -DHB_DEPEND_API
- Symbols in libharfbuzz-subset.dylib (applications must link both
  libharfbuzz and libharfbuzz-subset)

Status: Experimental API, subject to change.
2026-06-05 15:09:11 -07:00

85 KiB