## 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 ()
void | hb_face_destroy ()
hb_face_t * | hb_face_get_empty ()
unsigned int | hb_face_get_table_tags ()
unsigned int | hb_face_get_glyph_count ()
unsigned int | hb_face_get_index ()
unsigned int | hb_face_get_upem ()
void * | hb_face_get_user_data ()
hb_bool_t | hb_face_is_immutable ()
void | hb_face_make_immutable ()
hb_face_t * | hb_face_reference ()
hb_blob_t * | hb_face_reference_blob ()
hb_blob_t * | hb_face_reference_table ()
void | hb_face_set_glyph_count ()
void | hb_face_set_index ()
void | hb_face_set_upem ()
hb_bool_t | hb_face_set_user_data ()
void | hb_face_collect_unicodes ()
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 ()

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