hb-face: HarfBuzz Manual

## hb-face hb-face — Font face objects |

## Functions

unsigned int | hb_face_count ()
hb_face_t * | hb_face_create ()
hb_face_t * | hb_face_create_or_fail ()
hb_face_t * | hb_face_create_or_fail_using ()
hb_face_t * | hb_face_create_from_file_or_fail ()
hb_face_t * | hb_face_create_from_file_or_fail_using ()
const char ** | hb_face_list_loaders ()
hb_blob_t * | (*hb_reference_table_func_t) ()
hb_face_t * | hb_face_create_for_tables ()
hb_face_t * | hb_face_get_empty ()
hb_face_t * | hb_face_reference ()
void | hb_face_destroy ()
hb_bool_t | hb_face_set_user_data ()
void * | hb_face_get_user_data ()
void | hb_face_make_immutable ()
hb_bool_t | hb_face_is_immutable ()
unsigned int | (*hb_get_table_tags_func_t) ()
void | hb_face_set_get_table_tags_func ()
unsigned int | hb_face_get_table_tags ()
void | hb_face_set_glyph_count ()
unsigned int | hb_face_get_glyph_count ()
void | hb_face_set_index ()
unsigned int | hb_face_get_index ()
void | hb_face_set_upem ()
unsigned int | hb_face_get_upem ()
hb_blob_t * | hb_face_reference_blob ()
hb_blob_t * | hb_face_reference_table ()
void | hb_face_collect_unicodes ()
void | hb_face_collect_nominal_glyph_mapping ()
void | hb_face_collect_variation_selectors ()
void | hb_face_collect_variation_unicodes ()
hb_face_t * | hb_face_builder_create ()
hb_bool_t | hb_face_builder_add_table ()
void | hb_face_builder_sort_tables ()

## Types and Values

typedef | hb_face_t

## Includes

    #include <hb.h>

## Description

A font face is an object that represents a single face from within a font family.

More precisely, a font face represents a single face in a binary font file. Font faces are typically built from a binary blob and a face index. Font faces are used to create fonts.

A font face can be created from a binary blob using `hb_face_create()`. The face index is used to select a face from a binary blob that contains multiple faces. For example, a binary blob that contains both a regular and a bold face can be used to create two font faces, one for each face index.

## Functions

### hb_face_count ()

    unsigned int
    hb_face_count (hb_blob_t *blob);

Fetches the number of faces in a blob.

#### Parameters

blob | a blob. |

#### Returns

Number of faces in `blob`

Since: 1.7.7

### hb_face_create ()

    hb_face_t *
    hb_face_create (hb_blob_t *blob,
                    unsigned int index);

Constructs a new face object from the specified blob and a face index into that blob.

The face index is used for blobs of file formats such as TTC and DFont that can contain more than one face. Face indices within such collections are zero-based.

Note: If the blob font format is not a collection, `index` is ignored. Otherwise, only the lower 16-bits of `index` are used. The unmodified `index` can be accessed via `hb_face_get_index()`.
Note: The high 16-bits of `index`, if non-zero, are used by `hb_font_create()` to load named-instances in variable fonts. See `hb_font_create()` for details.

#### Parameters

blob | hb_blob_t to work upon |
index | The index of the face within `blob` |

#### Returns

The new face object.

[transfer full]

Since: 0.9.2

### hb_face_create_or_fail ()

    hb_face_t *
    hb_face_create_or_fail (hb_blob_t *blob,
                            unsigned int index);

Like `hb_face_create()`, but returns `NULL` if the blob data contains no usable font face at the specified index.

#### Parameters

blob | hb_blob_t to work upon |
index | The index of the face within `blob` |

#### Returns

The new face object, or `NULL` if no face is found at the specified index.

[transfer full]

Since: 10.1.0

### hb_face_create_or_fail_using ()

    hb_face_t *
    hb_face_create_or_fail_using (hb_blob_t *blob,
                                  unsigned int index,
                                  const char *loader_name);

A thin wrapper around the face loader functions registered with HarfBuzz. If `loader_name` is `NULL` or the empty string, the first available loader is used.

For example, the FreeType ("ft") loader might be able to load WOFF and WOFF2 files if FreeType is built with those features, whereas the OpenType ("ot") loader will not.

#### Parameters

blob | hb_blob_t to work upon |
index | The index of the face within `blob` |
loader_name | The name of the loader to use, or `NULL`. | [nullable]

#### Returns

The new face object, or `NULL` if the loader fails to load the face.

[transfer full]

Since: 11.0.0

### hb_face_create_from_file_or_fail ()

    hb_face_t *
    hb_face_create_from_file_or_fail (const char *file_name,
                                      unsigned int index);

A thin wrapper around `hb_blob_create_from_file_or_fail()` followed by `hb_face_create_or_fail()`.

#### Parameters

file_name | A font filename |
index | The index of the face within the file |

#### Returns

The new face object, or `NULL` if no face is found at the specified index or the file cannot be read.

[transfer full]

Since: 10.1.0

### hb_face_create_from_file_or_fail_using ()

    hb_face_t *
    hb_face_create_from_file_or_fail_using
                                   (const char *file_name,
                                    unsigned int index,
                                    const char *loader_name);

A thin wrapper around the face loader functions registered with HarfBuzz. If `loader_name` is `NULL` or the empty string, the first available loader is used.

For example, the FreeType ("ft") loader might be able to load WOFF and WOFF2 files if FreeType is built with those features, whereas the OpenType ("ot") loader will not.

#### Parameters

file_name | A font filename |
index | The index of the face within the file |
loader_name | The name of the loader to use, or `NULL`. | [nullable]

#### Returns

The new face object, or `NULL` if the file cannot be read or the loader fails to load the face.

[transfer full]

Since: 11.0.0

### hb_face_list_loaders ()

    const char **
    hb_face_list_loaders (void);

Retrieves the list of face loaders supported by HarfBuzz.

#### Returns

a `NULL`-terminated array of supported face loaders constant strings. The returned array is owned by HarfBuzz and should not be modified or freed.

[transfer none][array zero-terminated=1]

Since: 11.0.0

### hb_reference_table_func_t ()

    hb_blob_t *
    (*hb_reference_table_func_t) (hb_face_t *face,
                                  hb_tag_t tag,
                                  void *user_data);

Callback function for `hb_face_create_for_tables()`. The `tag` is the tag of the table to reference, and the special tag HB_TAG_NONE is used to reference the blob of the face itself. If referencing the face blob is not possible, it is recommended to set hb_get_table_tags_func_t on the `face` to allow `hb_face_reference_blob()` to create a face blob out of individual table blobs.

#### Parameters

face | an hb_face_t to reference table for |
tag | the tag of the table to reference |
user_data | User data pointer passed by the caller |

#### Returns

A pointer to the `tag` table within `face` or `NULL` if the table is not found or cannot be referenced.

[transfer full]

Since: 0.9.2

### hb_face_create_for_tables ()

    hb_face_t *
    hb_face_create_for_tables (hb_reference_table_func_t reference_table_func,
                               void *user_data,
                               hb_destroy_func_t destroy);

Variant of `hb_face_create()`, built for those cases where it is more convenient to provide data for individual tables instead of the whole font data. With the caveat that `hb_face_get_table_tags()` would not work with faces created this way. You can address that by calling the `hb_face_set_get_table_tags_func()` function and setting the appropriate callback.

Creates a new face object from the specified `user_data` and `reference_table_func` , with the `destroy` callback.

#### Parameters

reference_table_func | Table-referencing function. | [closure user_data][destroy destroy][scope notified]
user_data | A pointer to the user data |
destroy | A callback to call when `data` is not needed anymore. | [nullable]

#### Returns

The new face object.

[transfer full]

Since: 0.9.2

### hb_face_get_empty ()

    hb_face_t *
    hb_face_get_empty (void);

Fetches the singleton empty face object.

#### Returns

The empty face object.

[transfer full]

Since: 0.9.2

### hb_face_reference ()

    hb_face_t *
    hb_face_reference (hb_face_t *face);

Increases the reference count on a face object.

[skip]

#### Parameters

face | A face object |

#### Returns

The `face` object

Since: 0.9.2

### hb_face_destroy ()

    void
    hb_face_destroy (hb_face_t *face);

Decreases the reference count on a face object. When the reference count reaches zero, the face is destroyed, freeing all memory.

[skip]

#### Parameters

face | A face object |

Since: 0.9.2

### hb_face_set_user_data ()

    hb_bool_t
    hb_face_set_user_data (hb_face_t *face,
                           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 face object.

[skip]

#### Parameters

face | A face 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: 0.9.2

### hb_face_get_user_data ()

    void *
    hb_face_get_user_data (const hb_face_t *face,
                           hb_user_data_key_t *key);

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

[skip]

#### Parameters

face | A face object |
key | The user-data key to query |

#### Returns

A pointer to the user data.

[transfer none]

Since: 0.9.2

### hb_face_make_immutable ()

    void
    hb_face_make_immutable (hb_face_t *face);

Makes the given face object immutable.

#### Parameters

face | A face object |

Since: 0.9.2

### hb_face_is_immutable ()

    hb_bool_t
    hb_face_is_immutable (hb_face_t *face);

Tests whether the given face object is immutable.

#### Parameters

face | A face object |

#### Returns

`true` is `face` is immutable, `false` otherwise

Since: 0.9.2

### hb_get_table_tags_func_t ()

    unsigned int
    (*hb_get_table_tags_func_t) (const hb_face_t *face,
                                 unsigned int start_offset,
                                 unsigned int *table_count,
                                 hb_tag_t *table_tags,
                                 void *user_data);

Callback function for `hb_face_get_table_tags()`.

#### Parameters

face | A face object |
start_offset | The index of first table tag to retrieve |
table_count | Input = the maximum number of table tags to return; Output = the actual number of table tags returned (may be zero). | [inout]
table_tags | The array of table tags found. | [out][array length=table_count][nullable]
user_data | User data pointer passed by the caller |

#### Returns

Total number of tables, or zero if it is not possible to list

Since: 10.0.0

### hb_face_set_get_table_tags_func ()

    void
    hb_face_set_get_table_tags_func (hb_face_t *face,
                                     hb_get_table_tags_func_t func,
                                     void *user_data,
                                     hb_destroy_func_t destroy);

Sets the table-tag-fetching function for the specified face object.

#### Parameters

face | A face object |
func | The table-tag-fetching function. | [closure user_data][destroy destroy][scope notified]
user_data | A pointer to the user data, to be destroyed by `destroy` when not needed anymore |
destroy | A callback to call when `func` is not needed anymore. | [nullable]

Since: 10.0.0

### hb_face_get_table_tags ()

    unsigned int
    hb_face_get_table_tags (const hb_face_t *face,
                            unsigned int start_offset,
                            unsigned int *table_count,
                            hb_tag_t *table_tags);

Fetches a list of all table tags for a face, if possible. The list returned will begin at the offset provided

#### Parameters

face | A face object |
start_offset | The index of first table tag to retrieve |
table_count | Input = the maximum number of table tags to return; Output = the actual number of table tags returned (may be zero). | [inout]
table_tags | The array of table tags found. | [out][array length=table_count][nullable]

#### Returns

Total number of tables, or zero if it is not possible to list

Since: 1.6.0

### hb_face_set_glyph_count ()

    void
    hb_face_set_glyph_count (hb_face_t *face,
                             unsigned int glyph_count);

Sets the glyph count for a face object to the specified value.

This API is used in rare circumstances.

#### Parameters

face | A face object |
glyph_count | The glyph-count value to assign |

Since: 0.9.7

### hb_face_get_glyph_count ()

    unsigned int
    hb_face_get_glyph_count (const hb_face_t *face);

Fetches the glyph-count value of the specified face object.

#### Parameters

face | A face object |

#### Returns

The glyph-count value of `face`

Since: 0.9.7

### hb_face_set_index ()

    void
    hb_face_set_index (hb_face_t *face,
                       unsigned int index);

Assigns the specified face-index to `face` . Fails if the face is immutable.

Note: changing the index has no effect on the face itself This only changes the value returned by `hb_face_get_index()`.

#### Parameters

face | A face object |
index | The index to assign |

Since: 0.9.2

### hb_face_get_index ()

    unsigned int
    hb_face_get_index (const hb_face_t *face);

Fetches the face-index corresponding to the given face.

Note: face indices within a collection are zero-based.

#### Parameters

face | A face object |

#### Returns

The index of `face` .

Since: 0.9.2

### hb_face_set_upem ()

    void
    hb_face_set_upem (hb_face_t *face,
                      unsigned int upem);

Sets the units-per-em (upem) for a face object to the specified value.

This API is used in rare circumstances.

#### Parameters

face | A face object |
upem | The units-per-em value to assign |

Since: 0.9.2

### hb_face_get_upem ()

    unsigned int
    hb_face_get_upem (const hb_face_t *face);

Fetches the units-per-em (UPEM) value of the specified face object.

Typical UPEM values for fonts are 1000, or 2048, but any value in between 16 and 16,384 is allowed for OpenType fonts.

#### Parameters

face | A face object |

#### Returns

The upem value of `face`

Since: 0.9.2

### hb_face_reference_blob ()

    hb_blob_t *
    hb_face_reference_blob (hb_face_t *face);

Fetches a pointer to the binary blob that contains the specified face. If referencing the face data is not possible, this function creates a blob out of individual table blobs if `hb_face_get_table_tags()` works with this face, otherwise it returns an empty blob.

#### Parameters

face | A face object |

#### Returns

A pointer to the blob for `face` .

[transfer full]

Since: 0.9.2

### hb_face_reference_table ()

    hb_blob_t *
    hb_face_reference_table (const hb_face_t *face,
                             hb_tag_t tag);

Fetches a reference to the specified table within the specified face. Returns an empty blob if referencing table data is not possible.

#### Parameters

face | A face object |
tag | The hb_tag_t of the table to query |

#### Returns

A pointer to the `tag` table within `face` .

[transfer full]

Since: 0.9.2

### hb_face_collect_unicodes ()

    void
    hb_face_collect_unicodes (hb_face_t *face,
                              hb_set_t *out);

Collects all of the Unicode characters covered by `face` and adds them to the hb_set_t set `out` .

#### Parameters

face | A face object |
out | The set to add Unicode characters to. | [out]

Since: 1.9.0

### hb_face_collect_nominal_glyph_mapping ()

    void
    hb_face_collect_nominal_glyph_mapping (hb_face_t *face,
                                           hb_map_t *mapping,
                                           hb_set_t *unicodes);

Collects the mapping from Unicode characters to nominal glyphs of the `face` , and optionally all of the Unicode characters covered by `face` .

#### Parameters

face | A face object |
mapping | The map to add Unicode-to-glyph mapping to. | [out]
unicodes | The set to add Unicode characters to, or `NULL`. | [nullable][out]

Since: 7.0.0

### hb_face_collect_variation_selectors ()

    void
    hb_face_collect_variation_selectors (hb_face_t *face,
                                         hb_set_t *out);

Collects all Unicode "Variation Selector" characters covered by `face` and adds them to the hb_set_t set `out` .

#### Parameters

face | A face object |
out | The set to add Variation Selector characters to. | [out]

Since: 1.9.0

### hb_face_collect_variation_unicodes ()

    void
    hb_face_collect_variation_unicodes (hb_face_t *face,
                                        hb_codepoint_t variation_selector,
                                        hb_set_t *out);

Collects all Unicode characters for `variation_selector` covered by `face` and adds them to the hb_set_t set `out` .

#### Parameters

face | A face object |
variation_selector | The Variation Selector to query |
out | The set to add Unicode characters to. | [out]

Since: 1.9.0

### hb_face_builder_create ()

    hb_face_t *
    hb_face_builder_create (void);

Creates a hb_face_t that can be used with `hb_face_builder_add_table()`. After tables are added to the face, it can be compiled to a binary font file by calling `hb_face_reference_blob()`.

#### Returns

New face.

[transfer full]

Since: 1.9.0

### hb_face_builder_add_table ()

    hb_bool_t
    hb_face_builder_add_table (hb_face_t *face,
                               hb_tag_t tag,
                               hb_blob_t *blob);

Add table for `tag` with data provided by `blob` to the face. `face` must be created using `hb_face_builder_create()`.

#### Parameters

face | A face object created with `hb_face_builder_create()` |
tag | The hb_tag_t of the table to add |
blob | The blob containing the table data to add |

Since: 1.9.0

### hb_face_builder_sort_tables ()

    void
    hb_face_builder_sort_tables (hb_face_t *face,
                                 const hb_tag_t *tags);

Set the ordering of tables for serialization. Any tables not specified in the tags list will be ordered after the tables in tags, ordered by the default sort ordering.

#### Parameters

face | A face object created with `hb_face_builder_create()` |
tags | ordered list of table tags terminated by `HB_TAG_NONE`. | [array zero-terminated=1]

Since: 5.3.0

## Types and Values

### hb_face_t

    typedef struct hb_face_t hb_face_t;

Data type for holding font faces.