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_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_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_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() does not currently work with faces created this way.

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 (const 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_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]

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. Returns an empty blob if referencing face data is not possible.

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.

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.