Add comprehensive documentation for depend API

This commit adds complete documentation for the dependency analysis API
at all levels: public API, internal structures, and implementation.

Public API documentation (src/hb-depend.cc, src/hb-depend.h):
- Replaced "XXX Todo" placeholder in SECTION comment with detailed
  module description explaining dependency graphs and use cases
- Fixed misleading hb_depend_t description (was only mentioning UVS)
- Added full documentation for hb_depend_print() with debugging notes
- Added usage examples to all three public functions
- Updated all version tags from "?.0.0" to "REPLACEME"
- Added experimental API warnings throughout

Internal documentation (src/hb-depend-data.hh, src/hb-depend.hh):
- Documented 5 internal structures with purpose and ownership semantics
- Added comments explaining data relationships and lifecycle

Algorithm documentation (src/hb-depend.cc):
- Added detailed algorithm comments to 5 extraction methods explaining
  how dependencies are collected from each OpenType table (cmap, GSUB,
  glyf, COLR, MATH)

User guide (docs/depend-api.md):
- Created comprehensive 250-line API guide with:
  * Introduction with mechanism overview
  * Basic usage example (iterating dependencies)
  * Advanced examples (computing reachable glyphs, ligature sets)
  * API details and compilation instructions
  * Implementation notes including ownership semantics
  * Use cases (subsetting, coverage analysis, binning, testing)
- Prominent experimental API warnings

Build configuration (meson_options.txt):
- Updated option description to emphasize experimental status

All documentation follows HarfBuzz conventions and includes gtk-doc
formatting for API reference generation.
This commit is contained in:
Skef Iterum committed 2026-06-05 15:09:11 -07:00
1 parent 8299b0b2d1
commit 4ea82e1afc
6 files changed
+432 -20

No files matched your search

+250
View File
@@ -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 <hb.h>
#include <hb-depend.h>
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.
+1 -1
View File
@@ -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',
+35
View File
@@ -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<hb_depend_data_record_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 () {}
+131 -17
View File
@@ -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.
* <warning>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.</warning>
*
* 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<OT::Layout::GSUB> (face);
auto table = gsub_blob->as<OT::Layout::GSUB> ();
@@ -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<OT::MATH> (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)
+5 -2
View File
@@ -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.
*
* <warning>Highly experimental API. Subject to change.</warning>
*
* Since: REPLACEME
*/
typedef struct hb_depend_t hb_depend_t;
+10
View File
@@ -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);