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. This is used for blobs of file formats such as Dfont and TTC that can contain more than one face.

[Xconstructor]

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 (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_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: face indices within a collection are zero-based.

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.