hb-subset: HarfBuzz Manual

## hb-subset hb-subset — Subsets font files. |

## Functions

hb_subset_input_t * | hb_subset_input_create_or_fail ()
hb_subset_input_t * | hb_subset_input_reference ()
void | hb_subset_input_destroy ()
hb_bool_t | hb_subset_input_set_user_data ()
void * | hb_subset_input_get_user_data ()
void | hb_subset_input_keep_everything ()
void | hb_subset_input_set_flags ()
hb_subset_flags_t | hb_subset_input_get_flags ()
hb_set_t * | hb_subset_input_unicode_set ()
hb_set_t * | hb_subset_input_glyph_set ()
hb_set_t * | hb_subset_input_set ()
hb_map_t * | hb_subset_input_old_to_new_glyph_mapping ()
hb_bool_t | hb_subset_input_pin_all_axes_to_default ()
hb_bool_t | hb_subset_input_pin_axis_location ()
hb_bool_t | hb_subset_input_pin_axis_to_default ()
hb_bool_t | hb_subset_input_get_axis_range ()
hb_bool_t | hb_subset_input_set_axis_range ()
hb_bool_t | hb_subset_axis_range_from_string ()
void | hb_subset_axis_range_to_string ()
hb_face_t * | hb_subset_or_fail ()
hb_subset_plan_t * | hb_subset_plan_create_or_fail ()
hb_subset_plan_t * | hb_subset_plan_reference ()
void | hb_subset_plan_destroy ()
hb_bool_t | hb_subset_plan_set_user_data ()
void * | hb_subset_plan_get_user_data ()
hb_face_t * | hb_subset_plan_execute_or_fail ()
hb_map_t * | hb_subset_plan_unicode_to_old_glyph_mapping ()
hb_map_t * | hb_subset_plan_new_to_old_glyph_mapping ()
hb_map_t * | hb_subset_plan_old_to_new_glyph_mapping ()
hb_face_t * | hb_subset_preprocess ()
hb_blob_t * | hb_subset_serialize_or_fail ()

## Types and Values

enum | hb_subset_flags_t
typedef | hb_subset_input_t
enum | hb_subset_sets_t
typedef | hb_subset_plan_t
| hb_subset_serialize_link_t
| hb_subset_serialize_object_t

## Includes

    #include <hb-subset.h>

## Description

Subsetting reduces the codepoint coverage of font files and removes all data that is no longer needed. A subset input describes the desired subset. The input is provided along with a font to the subsetting operation. Output is a new font file containing only the data specified in the input.

Currently most outline and bitmap tables are supported: glyf, CFF, CFF2, sbix, COLR, and CBDT/CBLC. This also includes fonts with variable outlines via OpenType variations. Notably EBDT/EBLC and SVG are not supported. Layout subsetting is supported only for OpenType Layout tables (GSUB, GPOS, GDEF). Notably subsetting of graphite or AAT tables is not yet supported.

Fonts with graphite or AAT tables may still be subsetted but will likely need to use the retain glyph ids option and configure the subset to pass through the layout tables untouched.

## Functions

### hb_subset_input_create_or_fail ()

    hb_subset_input_t *
    hb_subset_input_create_or_fail (void);

Creates a new subset input object.

#### Returns

New subset input, or `NULL` if failed. Destroy with `hb_subset_input_destroy()`.

[transfer full]

Since: 1.8.0

### hb_subset_input_reference ()

    hb_subset_input_t *
    hb_subset_input_reference (hb_subset_input_t *input);

Increases the reference count on `input` .

[skip]

#### Parameters

input | a hb_subset_input_t object. |

#### Returns

`input` .

Since: 1.8.0

### hb_subset_input_destroy ()

    void
    hb_subset_input_destroy (hb_subset_input_t *input);

Decreases the reference count on `input` , and if it reaches zero, destroys `input` , freeing all memory.

#### Parameters

input | a hb_subset_input_t object. |

Since: 1.8.0

### hb_subset_input_set_user_data ()

    hb_bool_t
    hb_subset_input_set_user_data (hb_subset_input_t *input,
                                   hb_user_data_key_t *key,
                                   void *data,
                                   hb_destroy_func_t destroy,
                                   hb_bool_t replace);

Attaches a user-data key/data pair to the given subset input object.

[skip]

#### Parameters

input | a hb_subset_input_t object. |
key | The user-data key to set |
data | A pointer to the user data |
destroy | A callback to call when `data` is not needed anymore. | [nullable]
replace | Whether to replace an existing data with the same key |

#### Returns

`true` if success, `false` otherwise

Since: 2.9.0

### hb_subset_input_get_user_data ()

    void *
    hb_subset_input_get_user_data (const hb_subset_input_t *input,
                                   hb_user_data_key_t *key);

Fetches the user data associated with the specified key, attached to the specified subset input object.

[skip]

#### Parameters

input | a hb_subset_input_t object. |
key | The user-data key to query |

#### Returns

A pointer to the user data.

[transfer none]

Since: 2.9.0

### hb_subset_input_keep_everything ()

    void
    hb_subset_input_keep_everything (hb_subset_input_t *input);

Configure input object to keep everything in the font face. That is, all Unicodes, glyphs, names, layout items, glyph names, etc.

The input can be tailored afterwards by the caller.

#### Parameters

input | a hb_subset_input_t object |

Since: 7.0.0

### hb_subset_input_set_flags ()

    void
    hb_subset_input_set_flags (hb_subset_input_t *input,
                               unsigned  value);

Sets all of the flags in the input object to the values specified by the bit field.

#### Parameters

input | a hb_subset_input_t object. |
value | bit field of flags |

Since: 2.9.0

### hb_subset_input_get_flags ()

    hb_subset_flags_t
    hb_subset_input_get_flags (hb_subset_input_t *input);

Gets all of the subsetting flags in the input object.

#### Parameters

input | a hb_subset_input_t object. |

#### Returns

the subsetting flags bit field.

Since: 2.9.0

### hb_subset_input_unicode_set ()

    hb_set_t *
    hb_subset_input_unicode_set (hb_subset_input_t *input);

Gets the set of Unicode code points to retain, the caller should modify the set as needed.

#### Parameters

input | a hb_subset_input_t object. |

#### Returns

pointer to the hb_set_t of Unicode code points.

[transfer none]

Since: 1.8.0

### hb_subset_input_glyph_set ()

    hb_set_t *
    hb_subset_input_glyph_set (hb_subset_input_t *input);

Gets the set of glyph IDs to retain, the caller should modify the set as needed.

#### Parameters

input | a hb_subset_input_t object. |

#### Returns

pointer to the hb_set_t of glyph IDs.

[transfer none]

Since: 1.8.0

### hb_subset_input_set ()

    hb_set_t *
    hb_subset_input_set (hb_subset_input_t *input,
                         hb_subset_sets_t set_type);

Gets the set of the specified type.

#### Parameters

input | a hb_subset_input_t object. |
set_type | a hb_subset_sets_t set type. |

#### Returns

pointer to the hb_set_t of the specified type.

[transfer none]

Since: 2.9.1

### hb_subset_input_old_to_new_glyph_mapping ()

    hb_map_t *
    hb_subset_input_old_to_new_glyph_mapping
                                   (hb_subset_input_t *input);

Returns a map which can be used to provide an explicit mapping from old to new glyph id's in the produced subset. The caller should populate the map as desired. If this map is left empty then glyph ids will be automatically mapped to new values by the subsetter. If populated, the mapping must be unique. That is no two original glyph ids can be mapped to the same new id. Additionally, if a mapping is provided then the retain gids option cannot be enabled.

Any glyphs that are retained in the subset which are not specified in this mapping will be assigned glyph ids after the highest glyph id in the mapping.

Note: this will accept and apply non-monotonic mappings, however this may result in unsorted Coverage tables. Such fonts may not work for all use cases (for example ots will reject unsorted coverage tables). So it's recommended, if possible, to supply a monotonic mapping.

#### Parameters

input | a hb_subset_input_t object. |

#### Returns

pointer to the hb_map_t of the custom glyphs ID map.

[transfer none]

Since: 7.3.0

### hb_subset_input_pin_all_axes_to_default ()

    hb_bool_t
    hb_subset_input_pin_all_axes_to_default
                                   (hb_subset_input_t *input,
                                    hb_face_t *face);

Pin all axes to default locations in the given subset input object.

All axes in a font must be pinned. Additionally, `CFF2` table, if present, will be de-subroutinized.

[skip]

#### Parameters

input | a hb_subset_input_t object. |
face | a hb_face_t object. |

#### Returns

`true` if success, `false` otherwise

Since: 8.3.1

### hb_subset_input_pin_axis_location ()

    hb_bool_t
    hb_subset_input_pin_axis_location (hb_subset_input_t *input,
                                       hb_face_t *face,
                                       hb_tag_t axis_tag,
                                       float axis_value);

Pin an axis to a fixed location in the given subset input object.

All axes in a font must be pinned. Additionally, `CFF2` table, if present, will be de-subroutinized.

[skip]

#### Parameters

input | a hb_subset_input_t object. |
face | a hb_face_t object. |
axis_tag | Tag of the axis to be pinned |
axis_value | Location on the axis to be pinned at |

#### Returns

`true` if success, `false` otherwise

Since: 6.0.0

### hb_subset_input_pin_axis_to_default ()

    hb_bool_t
    hb_subset_input_pin_axis_to_default (hb_subset_input_t *input,
                                         hb_face_t *face,
                                         hb_tag_t axis_tag);

Pin an axis to its default location in the given subset input object.

All axes in a font must be pinned. Additionally, `CFF2` table, if present, will be de-subroutinized.

[skip]

#### Parameters

input | a hb_subset_input_t object. |
face | a hb_face_t object. |
axis_tag | Tag of the axis to be pinned |

#### Returns

`true` if success, `false` otherwise

Since: 6.0.0

### hb_subset_input_get_axis_range ()

    hb_bool_t
    hb_subset_input_get_axis_range (hb_subset_input_t *input,
                                    hb_tag_t axis_tag,
                                    float *axis_min_value,
                                    float *axis_max_value,
                                    float *axis_def_value);

Gets the axis range assigned by previous calls to hb_subset_input_set_axis_range.

[skip]

#### Parameters

input | a hb_subset_input_t object. |
axis_tag | Tag of the axis |
axis_min_value | Set to the previously configured minimum value of the axis variation range. |
axis_max_value | Set to the previously configured maximum value of the axis variation range. |
axis_def_value | Set to the previously configured default value of the axis variation range. |

#### Returns

`true` if a range has been set for this axis tag, `false` otherwise.

Since: 8.5.0

### hb_subset_input_set_axis_range ()

    hb_bool_t
    hb_subset_input_set_axis_range (hb_subset_input_t *input,
                                    hb_face_t *face,
                                    hb_tag_t axis_tag,
                                    float axis_min_value,
                                    float axis_max_value,
                                    float axis_def_value);

Restricting the range of variation on an axis in the given subset input object. New min/default/max values will be clamped if they're not within the fvar axis range.

If the fvar axis default value is not within the new range, the new default value will be changed to the new min or max value, whichever is closer to the fvar axis default.

Note: input min value can not be bigger than input max value. If the input default value is not within the new min/max range, it'll be clamped.

[skip]

#### Parameters

input | a hb_subset_input_t object. |
face | a hb_face_t object. |
axis_tag | Tag of the axis |
axis_min_value | Minimum value of the axis variation range to set, if NaN the existing min will be used. |
axis_max_value | Maximum value of the axis variation range to set if NaN the existing max will be used. |
axis_def_value | Default value of the axis variation range to set, if NaN the existing default will be used. |

#### Returns

`true` if success, `false` otherwise

Since: 8.5.0

### hb_subset_axis_range_from_string ()

    hb_bool_t
    hb_subset_axis_range_from_string (const char *str,
                                      int len,
                                      float *axis_min_value,
                                      float *axis_max_value,
                                      float *axis_def_value);

Parses a string into a subset axis range(min, def, max). Axis positions string is in the format of min:def:max or min:max When parsing axis positions, empty values as meaning the existing value for that part E.g: :300:500 Specifies min = existing, def = 300, max = 500 In the output axis_range, if a value should be set to it's default value, then it will be set to NaN

#### Parameters

str | a string to parse |
len | length of `str` , or -1 if str is NULL terminated |
axis_min_value | the axis min value to initialize with the parsed value. | [out]
axis_max_value | the axis max value to initialize with the parsed value. | [out]
axis_def_value | the axis default value to initialize with the parse value. | [out]

#### Returns

`true` if `str` is successfully parsed, `false` otherwise

Since: 10.2.0

### hb_subset_axis_range_to_string ()

    void
    hb_subset_axis_range_to_string (hb_subset_input_t *input,
                                    hb_tag_t axis_tag,
                                    char *buf,
                                    unsigned  size);

Converts an axis range into a `NULL`-terminated string in the format understood by `hb_subset_axis_range_from_string()`. The client in responsible for allocating big enough size for `buf` , 128 bytes is more than enough.

#### Parameters

input | a hb_subset_input_t object. |
axis_tag | an axis to convert |
buf | output string. | [array length=size][out caller-allocates]
size | the allocated size of `buf` |

Since: 10.2.0

### hb_subset_or_fail ()

    hb_face_t *
    hb_subset_or_fail (hb_face_t *source,
                       const hb_subset_input_t *input);

Subsets a font according to provided input. Returns nullptr if the subset operation fails or the face has no glyphs.

#### Parameters

source | font face data to be subset. |
input | input to use for the subsetting. |

Since: 2.9.0

### hb_subset_plan_create_or_fail ()

    hb_subset_plan_t *
    hb_subset_plan_create_or_fail (hb_face_t *face,
                                   const hb_subset_input_t *input);

Computes a plan for subsetting the supplied face according to a provided input. The plan describes which tables and glyphs should be retained.

#### Parameters

face | font face to create the plan for. |
input | a hb_subset_input_t input. |

#### Returns

New subset plan. Destroy with `hb_subset_plan_destroy()`. If there is a failure creating the plan nullptr will be returned.

[transfer full]

Since: 4.0.0

### hb_subset_plan_reference ()

    hb_subset_plan_t *
    hb_subset_plan_reference (hb_subset_plan_t *plan);

Increases the reference count on `plan` .

[skip]

#### Parameters

plan | a hb_subset_plan_t object. |

#### Returns

`plan` .

Since: 4.0.0

### hb_subset_plan_destroy ()

    void
    hb_subset_plan_destroy (hb_subset_plan_t *plan);

Decreases the reference count on `plan` , and if it reaches zero, destroys `plan` , freeing all memory.

#### Parameters

plan | a hb_subset_plan_t |

Since: 4.0.0

### hb_subset_plan_set_user_data ()

    hb_bool_t
    hb_subset_plan_set_user_data (hb_subset_plan_t *plan,
                                  hb_user_data_key_t *key,
                                  void *data,
                                  hb_destroy_func_t destroy,
                                  hb_bool_t replace);

Attaches a user-data key/data pair to the given subset plan object.

[skip]

#### Parameters

plan | a hb_subset_plan_t object. |
key | The user-data key to set |
data | A pointer to the user data |
destroy | A callback to call when `data` is not needed anymore. | [nullable]
replace | Whether to replace an existing data with the same key |

#### Returns

`true` if success, `false` otherwise

Since: 4.0.0

### hb_subset_plan_get_user_data ()

    void *
    hb_subset_plan_get_user_data (const hb_subset_plan_t *plan,
                                  hb_user_data_key_t *key);

Fetches the user data associated with the specified key, attached to the specified subset plan object.

[skip]

#### Parameters

plan | a hb_subset_plan_t object. |
key | The user-data key to query |

#### Returns

A pointer to the user data.

[transfer none]

Since: 4.0.0

### hb_subset_plan_execute_or_fail ()

    hb_face_t *
    hb_subset_plan_execute_or_fail (hb_subset_plan_t *plan);

Executes the provided subsetting `plan` .

#### Parameters

plan | a subsetting plan. |

#### Returns

on success returns a reference to generated font subset. If the subsetting operation fails returns nullptr.

Since: 4.0.0

### hb_subset_plan_unicode_to_old_glyph_mapping ()

    hb_map_t *
    hb_subset_plan_unicode_to_old_glyph_mapping
                                   (const hb_subset_plan_t *plan);

Returns the mapping between codepoints in the original font and the associated glyph id in the original font.

#### Parameters

plan | a subsetting plan. |

#### Returns

A pointer to the hb_map_t of the mapping.

[transfer none]

Since: 4.0.0

### hb_subset_plan_new_to_old_glyph_mapping ()

    hb_map_t *
    hb_subset_plan_new_to_old_glyph_mapping
                                   (const hb_subset_plan_t *plan);

Returns the mapping between glyphs in the subset that will be produced by `plan` and the glyph in the original font.

#### Parameters

plan | a subsetting plan. |

#### Returns

A pointer to the hb_map_t of the mapping.

[transfer none]

Since: 4.0.0

### hb_subset_plan_old_to_new_glyph_mapping ()

    hb_map_t *
    hb_subset_plan_old_to_new_glyph_mapping
                                   (const hb_subset_plan_t *plan);

Returns the mapping between glyphs in the original font to glyphs in the subset that will be produced by `plan`

#### Parameters

plan | a subsetting plan. |

#### Returns

A pointer to the hb_map_t of the mapping.

[transfer none]

Since: 4.0.0

### hb_subset_preprocess ()

    hb_face_t *
    hb_subset_preprocess (hb_face_t *source);

Preprocesses the face and attaches data that will be needed by the subsetter. Future subsetting operations can then use the precomputed data to speed up the subsetting operation.

See subset-preprocessing for more information.

Note: the preprocessed face may contain sub-blobs that reference the memory backing the source hb_face_t. Therefore in the case that this memory is not owned by the source face you will need to ensure that memory lives as long as the returned hb_face_t.

#### Parameters

source | a hb_face_t object. |

#### Returns

a new hb_face_t.

Since: 6.0.0

### hb_subset_serialize_or_fail ()

    hb_blob_t *
    hb_subset_serialize_or_fail (hb_tag_t table_tag,
                                 hb_subset_serialize_object_t *hb_objects,
                                 unsigned  num_hb_objs);

Given the input object graph info, repack a table to eliminate offset overflows and serialize it into a continuous array of bytes. A nullptr is returned if the serializing attempt fails. Table specific optimizations (eg. extension promotion in GSUB/GPOS) may be performed. Passing HB_TAG_NONE will disable table specific optimizations.

#### Parameters

table_tag | tag of the table being packed, needed to allow table specific optimizations. |
hb_objects | raw array of struct hb_subset_serialize_object_t, which provides object graph info |
num_hb_objs | number of hb_subset_serialize_object_t in the hb_objects array. |

Since: 10.2.0

## Types and Values

### enum hb_subset_flags_t

List of boolean properties that can be configured on the subset input.

#### Members

HB_SUBSET_FLAGS_DEFAULT | all flags at their default value of false. |
HB_SUBSET_FLAGS_NO_HINTING | If set hinting instructions will be dropped in the produced subset. Otherwise hinting instructions will be retained. |
HB_SUBSET_FLAGS_RETAIN_GIDS | If set glyph indices will not be modified in the produced subset. If glyphs are dropped their indices will be retained as an empty glyph. |
HB_SUBSET_FLAGS_DESUBROUTINIZE | If set and subsetting a CFF font the subsetter will attempt to remove subroutines from the CFF glyphs. |
HB_SUBSET_FLAGS_NAME_LEGACY | If set non-unicode name records will be retained in the subset. |
HB_SUBSET_FLAGS_SET_OVERLAPS_FLAG | If set the subsetter will set the OVERLAP_SIMPLE flag on each simple glyph. |
HB_SUBSET_FLAGS_PASSTHROUGH_UNRECOGNIZED | If set the subsetter will not drop unrecognized tables and instead pass them through untouched. |
HB_SUBSET_FLAGS_NOTDEF_OUTLINE | If set the notdef glyph outline will be retained in the final subset. |
HB_SUBSET_FLAGS_GLYPH_NAMES | If set the PS glyph names will be retained in the final subset. |
HB_SUBSET_FLAGS_NO_PRUNE_UNICODE_RANGES | If set then the unicode ranges in OS/2 will not be recalculated. |
HB_SUBSET_FLAGS_NO_LAYOUT_CLOSURE | If set do not perform glyph closure on layout substitution rules (GSUB). Since: 7.2.0. |
HB_SUBSET_FLAGS_OPTIMIZE_IUP_DELTAS | If set perform IUP delta optimization on the remaining gvar table's deltas. Since: 8.5.0 |
HB_SUBSET_FLAGS_NO_BIDI_CLOSURE | If set do not pull mirrored versions of input codepoints into the subset. Since: 11.1.0 |
HB_SUBSET_FLAGS_IFTB_REQUIREMENTS | If set enforce requirements on the output subset to allow it to be used with incremental font transfer IFTB patches. Primarily, this forces all outline data to use long (32 bit) offsets. Since: EXPERIMENTAL |
HB_SUBSET_FLAGS_RETAIN_NUM_GLYPHS | If this flag is set along side HB_SUBSET_FLAGS_RETAIN_GIDS then the number of glyphs in the font won't be reduced as a result of subsetting. If necessary empty glyphs will be included at the end of the font to keep the number of glyphs unchanged. |
HB_SUBSET_FLAGS_DOWNGRADE_CFF2 | If set and instantiating a variable font, convert the output CFF2 table to CFF1. This enables compatibility with older renderers that don't support CFF2. Since: 13.0.0 |

Since: 2.9.0

### hb_subset_input_t

    typedef struct hb_subset_input_t hb_subset_input_t;

Things that change based on the input. Characters to keep, etc.

### enum hb_subset_sets_t

List of sets that can be configured on the subset input.

#### Members

HB_SUBSET_SETS_GLYPH_INDEX | the set of glyph indexes to retain in the subset. |
HB_SUBSET_SETS_UNICODE | the set of unicode codepoints to retain in the subset. |
HB_SUBSET_SETS_NO_SUBSET_TABLE_TAG | the set of table tags which specifies tables that should not be subsetted. |
HB_SUBSET_SETS_DROP_TABLE_TAG | the set of table tags which specifies tables which will be dropped in the subset. |
HB_SUBSET_SETS_NAME_ID | the set of name ids that will be retained. |
HB_SUBSET_SETS_NAME_LANG_ID | the set of name lang ids that will be retained. |
HB_SUBSET_SETS_LAYOUT_FEATURE_TAG | the set of layout feature tags that will be retained in the subset. |
HB_SUBSET_SETS_LAYOUT_SCRIPT_TAG | the set of layout script tags that will be retained in the subset. Defaults to all tags. Since: 5.0.0 |

Since: 2.9.1

### hb_subset_plan_t

    typedef struct hb_subset_plan_t hb_subset_plan_t;

Contains information about how the subset operation will be executed. Such as mappings from the old glyph ids to the new ones in the subset.

### hb_subset_serialize_link_t

    typedef struct {
      unsigned int width;
      unsigned int position;
      unsigned int objidx;
    } hb_subset_serialize_link_t;

Represents a link between two objects in the object graph to be serialized.

#### Members

unsigned int `width`; | offsetSize in bytes |
unsigned int `position`; | position of the offset field in bytes from beginning of subtable |
unsigned int `objidx`; | index of subtable |

Since: 10.2.0

### hb_subset_serialize_object_t

    typedef struct {
      char *head;
      char *tail;
      unsigned int num_real_links;
      hb_subset_serialize_link_t *real_links;
      unsigned int num_virtual_links;
      hb_subset_serialize_link_t *virtual_links;
    } hb_subset_serialize_object_t;

Represents an object in the object graph to be serialized.

#### Members

char *`head`; | start of object data |
char *`tail`; | end of object data |
unsigned int `num_real_links`; | number of offset field in the object |
hb_subset_serialize_link_t *`real_links`; | array of offset info |
unsigned int `num_virtual_links`; | number of objects that must be packed after current object in the final serialized order |
hb_subset_serialize_link_t *`virtual_links`; | array of virtual link info |

Since: 10.2.0