diff --git a/docs/depend-api.md b/docs/depend-api.md new file mode 100644 index 000000000..17f82d4b2 --- /dev/null +++ b/docs/depend-api.md @@ -0,0 +1,250 @@ +# Introduction + +**⚠️ WARNING: This API is highly experimental and subject to change. It is not +enabled by default and should not be used in production without understanding +the stability implications. The API may change significantly in future releases.** + +The dependency API provides access to a glyph dependency graph that represents +how glyphs in an OpenType font reference or produce other glyphs. The graph +maps input glyphs to output glyphs through various OpenType mechanisms: + +- **Character mapping (cmap)**: Maps Unicode codepoints to glyphs, including + Unicode Variation Sequences (UVS) +- **Glyph substitution (GSUB)**: Tracks which glyphs can be substituted for + other glyphs through OpenType Layout features +- **Composite glyphs (glyf)**: Records component glyphs used in composite glyph + construction +- **Color layers (COLR)**: Identifies glyphs used as color layers +- **Math variants (MATH)**: Tracks mathematical variant glyphs + +The dependency graph enables finding the transitive closure of all glyphs +reachable from a given input set, which is useful for font subsetting, +analyzing glyph coverage, and optimizing font delivery. + +# Usage + +## Basic Example + +```c +#include +#include + +hb_blob_t *blob = hb_blob_create_from_file("font.ttf"); +hb_face_t *face = hb_face_create(blob, 0); + +// Extract dependency graph +hb_depend_t *depend = hb_depend_from_face(face); + +// Query dependencies for a specific glyph +hb_codepoint_t gid = 42; // Glyph to query +hb_codepoint_t index = 0; + +hb_tag_t table_tag; +hb_codepoint_t dependent; +hb_tag_t layout_tag; +hb_codepoint_t ligature_set; + +printf("Dependencies for glyph %u:\n", gid); +while (hb_depend_get_glyph_entry(depend, gid, index++, + &table_tag, &dependent, + &layout_tag, &ligature_set)) { + printf(" -> glyph %u via %c%c%c%c\n", + dependent, HB_UNTAG(table_tag)); +} + +// Clean up +hb_depend_destroy(depend); +hb_face_destroy(face); +hb_blob_destroy(blob); +``` + +## Iterating Dependencies + +To programmatically access dependency information for a specific glyph: + +```c +hb_codepoint_t gid = 42; // Glyph ID to query +hb_codepoint_t index = 0; // Dependency entry index + +hb_tag_t table_tag; +hb_codepoint_t dependent; +hb_tag_t layout_tag; +hb_codepoint_t ligature_set; + +// Iterate through all dependencies for this glyph +while (hb_depend_get_glyph_entry(depend, gid, index, + &table_tag, &dependent, + &layout_tag, &ligature_set)) { + // Process dependency information + if (table_tag == HB_OT_TAG_GSUB) { + // GSUB dependency: layout_tag contains feature tag + printf("GID %u -> %u via GSUB feature '%c%c%c%c'\n", + gid, dependent, HB_UNTAG(layout_tag)); + } else if (table_tag == HB_TAG('c','m','a','p')) { + // cmap dependency: layout_tag contains UVS codepoint if applicable + printf("GID %u -> %u via cmap\n", gid, dependent); + } else { + // Other dependencies (glyf, COLR, MATH) + printf("GID %u -> %u via %c%c%c%c\n", + gid, dependent, HB_UNTAG(table_tag)); + } + + index++; +} +``` + +## Finding Reachable Glyphs + +To compute all glyphs reachable from a starting set (transitive closure): + +```c +void find_reachable_glyphs(hb_depend_t *depend, hb_set_t *reachable) +{ + hb_set_t *to_process = hb_set_create(); + hb_set_union(to_process, reachable); + + // Process glyphs until none remain + while (!hb_set_is_empty(to_process)) { + hb_codepoint_t gid = hb_set_get_min(to_process); + hb_set_del(to_process, gid); + + hb_codepoint_t index = 0; + hb_tag_t table_tag; + hb_codepoint_t dependent; + hb_tag_t layout_tag; + hb_codepoint_t ligature_set; + + while (hb_depend_get_glyph_entry(depend, gid, index++, + &table_tag, &dependent, + &layout_tag, &ligature_set)) { + if (!hb_set_has(reachable, dependent)) { + hb_set_add(reachable, dependent); + hb_set_add(to_process, dependent); + } + } + } + + hb_set_destroy(to_process); +} + +// Usage: +hb_set_t *reachable = hb_set_create(); +hb_set_add(reachable, 100); +hb_set_add(reachable, 101); + +find_reachable_glyphs(depend, reachable); + +printf("Found %u reachable glyphs\n", hb_set_get_population(reachable)); +hb_set_destroy(reachable); +``` + +## Working with Ligature Sets + +When a dependency entry belongs to a ligature set, you can find all other members +of that set using `hb_depend_get_set_from_index()`: + +```c +// After finding ligature_set != HB_CODEPOINT_INVALID from hb_depend_get_glyph_entry()... + +// Get all glyphs in this ligature set +hb_set_t *ligature_glyphs = hb_set_create(); +if (hb_depend_get_set_from_index(depend, ligature_set, ligature_glyphs)) { + hb_codepoint_t lig_gid = HB_SET_VALUE_INVALID; + + printf("Members of ligature set %u:\n", ligature_set); + while (hb_set_next(ligature_glyphs, &lig_gid)) { + // Find the dependency entry index for this glyph in this ligature set + hb_codepoint_t lig_index = 0; + hb_tag_t lig_table_tag; + hb_codepoint_t lig_dependent; + hb_tag_t lig_layout_tag; + hb_codepoint_t lig_ligature_set; + + while (hb_depend_get_glyph_entry(depend, lig_gid, lig_index++, + &lig_table_tag, &lig_dependent, + &lig_layout_tag, &lig_ligature_set)) { + if (lig_ligature_set == ligature_set) { + printf(" gid=%u, index=%u\n", lig_gid, lig_index - 1); + break; + } + } + } +} +hb_set_destroy(ligature_glyphs); +``` + +# API Details + +## Dependency Entry Fields + +Each dependency entry returned by `hb_depend_get_glyph_entry()` contains: + +- **table_tag**: Source table (e.g., `HB_OT_TAG_GSUB`, `HB_TAG('c','m','a','p')`, + `HB_TAG('g','l','y','f')`, `HB_TAG('C','O','L','R')`, `HB_TAG('M','A','T','H')`) +- **dependent**: The dependent glyph ID +- **layout_tag**: + - For GSUB: the feature tag (e.g., `HB_TAG('l','i','g','a')`) + - For cmap with UVS: the variation selector codepoint + - Otherwise: `HB_CODEPOINT_INVALID` +- **ligature_set**: For ligatures, identifies which ligature set; otherwise + `HB_CODEPOINT_INVALID` + +## Compilation + +The dependency API is optional and controlled by the `depend_api` build option. +**This is a highly experimental feature and disabled by default.** + +```bash +meson setup build -Ddepend_api=true +meson compile -C build +``` + +In code, check for availability: + +```c +#ifdef HB_DEPEND_API + // Use dependency API +#endif +``` + +**Important:** This API is experimental and may change without notice. Do not +use in production applications without being prepared for breaking changes in +future HarfBuzz releases. + +# Implementation Notes + +- The dependency graph is computed once when `hb_depend_from_face()` is called + and cached for the lifetime of the `hb_depend_t` object +- Dependencies are stored per-glyph and indexed sequentially starting from 0 +- For GSUB dependencies, the graph includes all potential substitutions that + could occur through layout features, not just those active for a particular + shaping operation +- The `hb_depend_print()` function is primarily for debugging; use + `hb_depend_get_glyph_entry()` for programmatic access +- Sets returned by `hb_depend_get_set_from_index()` are copied into the + provided set parameter. The original sets remain referenced in the + `hb_depend_t` object and are freed when the depend object is destroyed. + The caller owns the output set and is responsible for destroying it after use + +# Use Cases + +## Font Subsetting + +Determine which glyphs must be retained to properly render a specific set of +characters, accounting for all OpenType substitutions and compositions. + +## Coverage Analysis + +Analyze which features or scripts require which glyphs, useful for font +optimization and planning. + +## Font Binning + +Partition a font into smaller subsets where each bin contains glyphs reachable +from a specific set of input characters, enabling more efficient font delivery +for web applications. + +## Testing + +Verify that font modifications haven't inadvertently broken glyph references or +substitution chains. diff --git a/meson_options.txt b/meson_options.txt index 4e1f50b3b..522e21389 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -65,7 +65,7 @@ option('with_libstdcxx', type: 'boolean', value: false, option('experimental_api', type: 'boolean', value: false, description: 'Enable experimental APIs') option('depend_api', type: 'boolean', value: false, - description: 'Enable dependency analysis APIs') + description: 'Enable dependency analysis APIs (highly experimental, API will change)') option('ragel_subproject', type: 'boolean', value: false, description: 'Build Ragel subproject if no suitable version is found') option('fuzzer_ldflags', type: 'string', diff --git a/src/hb-depend-data.hh b/src/hb-depend-data.hh index 0d9bb0e2e..5f1518731 100644 --- a/src/hb-depend-data.hh +++ b/src/hb-depend-data.hh @@ -33,6 +33,14 @@ #ifdef HB_DEPEND_API +/** + * hb_depend_data_record_t: + * + * Internal structure representing a single dependency relationship. + * Records that glyph A depends on glyph B through a specific OpenType + * mechanism (table_tag), optionally with additional context (layout_tag, + * ligature_set). + */ struct hb_depend_data_record_t { hb_depend_data_record_t() = delete; hb_depend_data_record_t(hb_tag_t table_tag, @@ -56,10 +64,24 @@ struct hb_depend_data_record_t { // bool fv_only {false}; }; +/** + * hb_glyph_depend_record_t: + * + * Internal structure holding all dependency records for a single glyph. + * Contains a vector of hb_depend_data_record_t entries, indexed sequentially + * starting from 0. + */ struct hb_glyph_depend_record_t { hb_vector_t dependencies; }; +/** + * hb_lookup_feature_record_t: + * + * Internal structure tracking which features are associated with a lookup. + * Used during GSUB dependency analysis to record the feature tags that + * activate each lookup. + */ struct hb_lookup_feature_record_t { hb_lookup_feature_record_t () = default; explicit hb_lookup_feature_record_t (bool full) : full (full) {} @@ -78,6 +100,19 @@ struct hb_lookup_feature_record_t { hb_set_t fv_indexes; }; +/** + * hb_depend_data_t: + * + * Internal container for all dependency graph data. Stores: + * - Per-glyph dependency records (glyph_dependencies) + * - Ligature sets indexed by set ID (sets) + * - Nominal glyph mapping from Unicode codepoints (nominal_glyphs) + * - Set of all Unicode codepoints in the font (unicodes) + * - Lookup to feature mapping (lookup_features) + * + * This structure is owned by hb_depend_t and freed when the depend + * object is destroyed. + */ struct hb_depend_data_t { hb_depend_data_t () {} diff --git a/src/hb-depend.cc b/src/hb-depend.cc index 74786876b..0f1672c69 100644 --- a/src/hb-depend.cc +++ b/src/hb-depend.cc @@ -41,10 +41,24 @@ /** * SECTION:hb-depend * @title: hb-depend - * @short_description: Represents dependencies between glyphs in an OpenType font + * @short_description: Glyph dependency graph for font optimization * @include: hb-depend.h * - * XXX Todo. + * This API is highly experimental and subject to change. It is not + * enabled by default and should not be used in production code without + * understanding the stability implications. + * + * Functions for extracting a glyph dependency graph. + * + * A dependency graph represents the relationships between glyphs in a font, + * tracking which glyphs reference or produce other glyphs through OpenType + * mechanisms such as character mapping, glyph substitution, composite + * construction, color layering, and math variants. + * + * Dependency graphs enable finding all glyphs reachable from a given input set. + * This is useful for font subsetting, analyzing glyph coverage, optimizing + * font delivery, and determining which glyphs are needed to render specific + * characters. */ hb_depend_t::hb_depend_t (hb_face_t *f) @@ -60,6 +74,7 @@ hb_depend_t::hb_depend_t (hb_face_t *f) } successful = true; + /* Extract dependencies from all relevant OpenType tables */ get_cmap_dependencies(); get_gsub_dependencies(); get_math_dependencies(); @@ -67,6 +82,14 @@ hb_depend_t::hb_depend_t (hb_face_t *f) get_glyf_dependencies(); } +/* + * Algorithm: Character Map (cmap) Dependencies + * + * Collects nominal glyph mappings (Unicode codepoint -> glyph ID) and + * Unicode Variation Sequence mappings (codepoint + selector -> glyph ID). + * These form the base layer of dependencies showing which glyphs are directly + * reachable from character input. + */ void hb_depend_t::get_cmap_dependencies() { hb_face_collect_nominal_glyph_mapping(face, &data.nominal_glyphs, &data.unicodes); @@ -74,6 +97,21 @@ void hb_depend_t::get_cmap_dependencies() { cmap.table->depend(&data); } +/* + * Algorithm: Glyph Substitution (GSUB) Dependencies + * + * For each lookup in the GSUB table: + * 1. Determine which features reference the lookup + * 2. Call the lookup's depend() method which: + * - Iterates through covered glyphs (input glyphs) + * - Records each substitution (input -> output) as a dependency + * - Tags with the feature tag and table tag (GSUB) + * - For ligatures, assigns a ligature_set ID to group alternatives + * + * The result is a complete graph of all possible glyph substitutions + * that could occur through OpenType Layout features, regardless of + * script, language, or shaping context. + */ void hb_depend_t::get_gsub_dependencies() { hb_blob_t *gsub_blob = hb_sanitize_context_t ().reference_table (face); auto table = gsub_blob->as (); @@ -139,6 +177,13 @@ void hb_depend_t::get_gsub_dependencies() { } } +/* + * Algorithm: Math Variants (MATH) Dependencies + * + * Extracts dependencies from the MATH table for mathematical typesetting. + * Records which glyphs are used as size variants or assembly components + * for other glyphs, enabling proper rendering of mathematical expressions. + */ void hb_depend_t::get_math_dependencies() { hb_blob_t *math_blob = hb_sanitize_context_t ().reference_table (face); @@ -146,6 +191,14 @@ void hb_depend_t::get_math_dependencies() math->depend (&data); } +/* + * Algorithm: Color Layers (COLR) Dependencies + * + * For fonts with color glyph support, records which glyphs are used as + * color layers for other glyphs. Both COLRv0 (simple layers) and COLRv1 + * (gradient/transform-based) are supported. Each base glyph depends on + * its layer glyphs. + */ void hb_depend_t::get_colr_dependencies() { OT::COLR::accelerator_t colr (face); @@ -153,6 +206,14 @@ void hb_depend_t::get_colr_dependencies() colr.depend (&data); } +/* + * Algorithm: Composite Glyph (glyf) Dependencies + * + * For TrueType fonts, iterates through all glyphs and records component + * dependencies for composite glyphs. A composite glyph depends on each + * of its component glyphs. This is essential for subset operations to + * preserve glyph integrity. + */ void hb_depend_t::get_glyf_dependencies() { OT::glyf_accelerator_t glyf (face); @@ -175,13 +236,22 @@ hb_depend_t::~hb_depend_t () * hb_depend_from_face: * @face: font face to collect dependencies from * - * Calculates the dependencies between glyphs in the supplied face + * Calculates the dependencies between glyphs in the supplied face. + * Extracts dependency information from cmap, GSUB, glyf, COLR, and + * MATH tables. + * + * Example: + * ```c + * hb_depend_t *depend = hb_depend_from_face (face); + * // ... use depend ... + * hb_depend_destroy (depend); + * ``` * * Return value: (transfer full): New depend object. Destroy with * hb_depend_destroy(). If there is a failure creating the depend - * object * nullptr will be returned. + * object nullptr will be returned. * - * Since: ?.0.0 + * Since: REPLACEME **/ hb_depend_t * hb_depend_from_face (hb_face_t *face) @@ -202,21 +272,37 @@ hb_depend_from_face (hb_face_t *face) /** * hb_depend_get_glyph_entry: * @depend: depend object - * @gid: GID to retrive dependencies from + * @gid: GID to retrieve dependencies from * @index: The index of the entry values to retrieve - * @table_tag: Returns the tag of the table associated with the entry - * @dependent: Returns the GID of the dependent glyph - * @layout_tag: Returns the layout tag associated with the dependency - * (when table_tag is GSUB) or the UVS codepoint (when table_tag is cmap) + * @table_tag: (out): Returns the tag of the table associated with the entry + * @dependent: (out): Returns the GID of the dependent glyph + * @layout_tag: (out): Returns the layout tag associated with the dependency + * (when table_tag is GSUB) or the UVS codepoint (when table_tag is cmap). * Otherwise is HB_CODEPOINT_INVALID - * @ligature_set: Returns the index of the ligature set for this entry, or + * @ligature_set: (out): Returns the index of the ligature set for this entry, or * HB_CODEPOINT_INVALID if there is no such set * - * Get the values associated with a dependency entry for a glyph + * Get the values associated with a dependency entry for a glyph. + * Dependencies are indexed sequentially starting from 0. + * + * Example: + * ```c + * hb_codepoint_t index = 0; + * hb_tag_t table_tag; + * hb_codepoint_t dependent; + * hb_tag_t layout_tag; + * hb_codepoint_t ligature_set; + * + * while (hb_depend_get_glyph_entry (depend, gid, index++, + * &table_tag, &dependent, + * &layout_tag, &ligature_set)) { + * // Process dependency... + * } + * ``` * * Return value: true if there is such an entry, false otherwise * - * Since: ?.0.0 + * Since: REPLACEME **/ hb_bool_t hb_depend_get_glyph_entry(hb_depend_t *depend, hb_codepoint_t gid, @@ -232,11 +318,24 @@ hb_depend_get_glyph_entry(hb_depend_t *depend, hb_codepoint_t gid, * hb_depend_get_set_from_index: * @depend: depend object * @index: the index of the set - * @out: A pointer to a set to copy into + * @out: (out): A pointer to a set to copy into * - * Return value: true if there is such an entry, false otherwise + * Get all glyphs in a ligature set identified by @index. + * The ligature set index comes from the ligature_set field + * returned by hb_depend_get_glyph_entry(). * - * Since: ?.0.0 + * Example: + * ```c + * hb_set_t *ligature_glyphs = hb_set_create (); + * if (hb_depend_get_set_from_index (depend, ligature_set, ligature_glyphs)) { + * // Process glyphs in the set... + * } + * hb_set_destroy (ligature_glyphs); + * ``` + * + * Return value: true if there is such a set, false otherwise + * + * Since: REPLACEME **/ hb_bool_t hb_depend_get_set_from_index(hb_depend_t *depend, hb_codepoint_t index, @@ -244,6 +343,21 @@ hb_depend_get_set_from_index(hb_depend_t *depend, hb_codepoint_t index, return depend->get_set_from_index(index, out); } +/** + * hb_depend_print: + * @depend: a #hb_depend_t + * + * Prints the dependency graph to standard output for debugging purposes. + * For each glyph that has dependencies, prints the glyph ID followed by + * its dependent glyphs, including the source table (cmap, GSUB, glyf, + * COLR, MATH) and any relevant feature tags or variant information. + * + * Note: This function is primarily for debugging and testing. The output + * format is not stable and may change in future versions. For programmatic + * access to dependency information, use hb_depend_get_glyph_entry(). + * + * Since: REPLACEME + **/ void hb_depend_print (hb_depend_t *depend) { @@ -257,7 +371,7 @@ hb_depend_print (hb_depend_t *depend) * Decreases the reference count on @depend, and if it reaches zero, destroys * @depend, freeing all memory. * - * Since: ?.0.0 + * Since: REPLACEME **/ void hb_depend_destroy (hb_depend_t *depend) diff --git a/src/hb-depend.h b/src/hb-depend.h index 59d834f93..6042d9e9c 100644 --- a/src/hb-depend.h +++ b/src/hb-depend.h @@ -39,8 +39,11 @@ HB_BEGIN_DECLS /** * hb_depend_t: * - * Contains information about dependencies between UVS codepoints - * and glyphs. + * Data type for holding glyph dependency graphs. + * + * Highly experimental API. Subject to change. + * + * Since: REPLACEME */ typedef struct hb_depend_t hb_depend_t; diff --git a/src/hb-depend.hh b/src/hb-depend.hh index 1a2b35a59..1eb459dd8 100644 --- a/src/hb-depend.hh +++ b/src/hb-depend.hh @@ -34,6 +34,16 @@ #ifdef HB_DEPEND_API +/** + * hb_depend_t: + * + * Internal structure implementing the dependency graph API. + * Contains the dependency data (data), the source font face (face), + * and the set of features referenced by dependencies (features). + * + * Initialized via hb_depend_from_face() which computes the dependency + * graph once. The graph remains immutable for the lifetime of the object. + */ struct hb_depend_t { HB_INTERNAL hb_depend_t (hb_face_t *face);