hb-face

hb-face — Font face objects

Functions

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.

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 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_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_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_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_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_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_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.

Parameters

face

A face object

 

Returns

The upem value of face

Since: 0.9.2


hb_face_get_user_data ()

void *
hb_face_get_user_data (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_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_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_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_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_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.

Parameters

face

A face object

 

glyph_count

The glyph-count value to assign

 

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_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.

Parameters

face

A face object

 

upem

The units-per-em value to assign

 

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_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

 

Since: 1.9.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

 

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

 

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

Types and Values

hb_face_t

typedef struct hb_face_t hb_face_t;

Data type for holding font faces.