hb-ft: HarfBuzz Manual

## hb-ft hb-ft — FreeType integration |

## Functions

hb_face_t * | hb_ft_face_create ()
hb_face_t * | hb_ft_face_create_cached ()
hb_face_t * | hb_ft_face_create_referenced ()
hb_face_t * | hb_ft_face_create_from_file_or_fail ()
hb_face_t * | hb_ft_face_create_from_blob_or_fail ()
hb_font_t * | hb_ft_font_create ()
hb_font_t * | hb_ft_font_create_referenced ()
void | hb_ft_font_changed ()
FT_Face | hb_ft_font_get_ft_face ()
FT_Face | hb_ft_font_lock_face ()
void | hb_ft_font_unlock_face ()
void | hb_ft_font_set_load_flags ()
int | hb_ft_font_get_load_flags ()
void | hb_ft_font_set_funcs ()
hb_bool_t | hb_ft_hb_font_changed ()

## Includes

    #include <hb-ft.h>

## Description

Functions for using HarfBuzz with the FreeType library.

HarfBuzz supports using FreeType to provide face and font data.

Note that FreeType is not thread-safe, therefore these functions are not thread-safe either.

## Functions

### hb_ft_face_create ()

    hb_face_t *
    hb_ft_face_create (FT_Face ft_face,
                       hb_destroy_func_t destroy);

Creates an hb_face_t face object from the specified FT_Face.

Note that this is using the FT_Face object just to get at the underlying font data, and fonts created from the returned hb_face_t will use the native HarfBuzz font implementation, unless you call `hb_ft_font_set_funcs()` on them.

This variant of the function does not provide any life-cycle management.

Most client programs should use `hb_ft_face_create_referenced()` (or, perhaps, `hb_ft_face_create_cached()`) instead.

If you know you have valid reasons not to use `hb_ft_face_create_referenced()`, then it is the client program's responsibility to destroy `ft_face` after the hb_face_t face object has been destroyed.

#### Parameters

ft_face | FT_Face to work upon. | [destroy destroy][scope notified]
destroy | A callback to call when the face object is not needed anymore. | [nullable]

#### Returns

the new hb_face_t face object.

[transfer full]

Since: 0.9.2

### hb_ft_face_create_cached ()

    hb_face_t *
    hb_ft_face_create_cached (FT_Face ft_face);

Creates an hb_face_t face object from the specified FT_Face.

Note that this is using the FT_Face object just to get at the underlying font data, and fonts created from the returned hb_face_t will use the native HarfBuzz font implementation, unless you call `hb_ft_font_set_funcs()` on them.

This variant of the function caches the newly created hb_face_t face object, using the `generic` pointer of `ft_face` . Subsequent function calls that are passed the same `ft_face` parameter will have the same hb_face_t returned to them, and that hb_face_t will be correctly reference counted.

However, client programs are still responsible for destroying `ft_face` after the last hb_face_t face object has been destroyed.

#### Parameters

ft_face | FT_Face to work upon |

#### Returns

the new hb_face_t face object.

[transfer full]

Since: 0.9.2

### hb_ft_face_create_referenced ()

    hb_face_t *
    hb_ft_face_create_referenced (FT_Face ft_face);

Creates an hb_face_t face object from the specified FT_Face.

Note that this is using the FT_Face object just to get at the underlying font data, and fonts created from the returned hb_face_t will use the native HarfBuzz font implementation, unless you call `hb_ft_font_set_funcs()` on them.

This is the preferred variant of the hb_ft_face_create* function family, because it calls `FT_Reference_Face()` on `ft_face` , ensuring that `ft_face` remains alive as long as the resulting hb_face_t face object remains alive. Also calls `FT_Done_Face()` when the hb_face_t face object is destroyed.

Use this version unless you know you have good reasons not to.

#### Parameters

ft_face | FT_Face to work upon |

#### Returns

the new hb_face_t face object.

[transfer full]

Since: 0.9.38

### hb_ft_face_create_from_file_or_fail ()

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

Creates an hb_face_t face object from the specified font file and face index.

This is similar in functionality to `hb_face_create_from_file_or_fail()`, but uses the FreeType library for loading the font file. This can be useful, for example, to load WOFF and WOFF2 font data.

#### 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_ft_face_create_from_blob_or_fail ()

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

Creates an hb_face_t face object from the specified font blob and face index.

This is similar in functionality to `hb_face_create_from_blob_or_fail()`, but uses the FreeType library for loading the font blob. This can be useful, for example, to load WOFF and WOFF2 font data.

#### Parameters

blob | A blob |
index | The index of the face within the blob |

#### Returns

The new face object, or `NULL` if loading fails (eg. blob does not contain valid font data).

[transfer full]

Since: 11.0.0

### hb_ft_font_create ()

    hb_font_t *
    hb_ft_font_create (FT_Face ft_face,
                       hb_destroy_func_t destroy);

Creates an hb_font_t font object from the specified FT_Face.

Note: You must set the face size on `ft_face` before calling `hb_ft_font_create()` on it. HarfBuzz assumes size is always set and will access `size` member of FT_Face unconditionally.

This variant of the function does not provide any life-cycle management.

Most client programs should use `hb_ft_font_create_referenced()` instead.

If you know you have valid reasons not to use `hb_ft_font_create_referenced()`, then it is the client program's responsibility to destroy `ft_face` only after the hb_font_t font object has been destroyed.

HarfBuzz will use the `destroy` callback on the hb_font_t font object if it is supplied when you use this function. However, even if `destroy` is provided, it is the client program's responsibility to destroy `ft_face` , and it is the client program's responsibility to ensure that `ft_face` is destroyed only after the hb_font_t font object has been destroyed.

#### Parameters

ft_face | FT_Face to work upon. | [destroy destroy][scope notified]
destroy | A callback to call when the font object is not needed anymore. | [nullable]

#### Returns

the new hb_font_t font object.

[transfer full]

Since: 0.9.2

### hb_ft_font_create_referenced ()

    hb_font_t *
    hb_ft_font_create_referenced (FT_Face ft_face);

Creates an hb_font_t font object from the specified FT_Face.

Note: You must set the face size on `ft_face` before calling `hb_ft_font_create_referenced()` on it. HarfBuzz assumes size is always set and will access `size` member of FT_Face unconditionally.

This is the preferred variant of the hb_ft_font_create* function family, because it calls `FT_Reference_Face()` on `ft_face` , ensuring that `ft_face` remains alive as long as the resulting hb_font_t font object remains alive.

Use this version unless you know you have good reasons not to.

#### Parameters

ft_face | FT_Face to work upon |

#### Returns

the new hb_font_t font object.

[transfer full]

Since: 0.9.38

### hb_ft_font_changed ()

    void
    hb_ft_font_changed (hb_font_t *font);

Refreshes the state of `font` when the underlying FT_Face has changed. This function should be called after changing the size or variation-axis settings on the FT_Face.

#### Parameters

font | hb_font_t to work upon |

Since: 1.0.5

### hb_ft_font_get_ft_face ()

    FT_Face
    hb_ft_font_get_ft_face (hb_font_t *font);

Fetches the FT_Face associated with the specified hb_font_t font object.

This function works with hb_font_t objects created by `hb_ft_font_create()` or `hb_ft_font_create_referenced()`.

[skip]

#### Parameters

font | hb_font_t to work upon |

#### Returns

the FT_Face found or `NULL`.

[nullable]

Since: 10.4.0

### hb_ft_font_lock_face ()

    FT_Face
    hb_ft_font_lock_face (hb_font_t *font);

Gets the FT_Face associated with `font` .

This face will be kept around and access to the FT_Face object from other HarfBuzz API wil be blocked until you call `hb_ft_font_unlock_face()`.

This function works with hb_font_t objects created by `hb_ft_font_create()` or `hb_ft_font_create_referenced()`.

[skip]

#### Parameters

font | hb_font_t to work upon |

#### Returns

the FT_Face associated with `font` or `NULL`.

[nullable][transfer none]

Since: 2.6.5

### hb_ft_font_unlock_face ()

    void
    hb_ft_font_unlock_face (hb_font_t *font);

Releases an FT_Face previously obtained with `hb_ft_font_lock_face()`.

[skip]

#### Parameters

font | hb_font_t to work upon |

Since: 2.6.5

### hb_ft_font_set_load_flags ()

    void
    hb_ft_font_set_load_flags (hb_font_t *font,
                               int load_flags);

Sets the FT_Load_Glyph load flags for the specified hb_font_t.

For more information, see https://freetype.org/freetype2/docs/reference/ft2-glyph_retrieval.html#ft_load_xxx

This function works with hb_font_t objects created by `hb_ft_font_create()` or `hb_ft_font_create_referenced()`.

#### Parameters

font | hb_font_t to work upon |
load_flags | The FreeType load flags to set |

Since: 1.0.5

### hb_ft_font_get_load_flags ()

    int
    hb_ft_font_get_load_flags (hb_font_t *font);

Fetches the FT_Load_Glyph load flags of the specified hb_font_t.

For more information, see https://freetype.org/freetype2/docs/reference/ft2-glyph_retrieval.html#ft_load_xxx

This function works with hb_font_t objects created by `hb_ft_font_create()` or `hb_ft_font_create_referenced()`.

#### Parameters

font | hb_font_t to work upon |

#### Returns

FT_Load_Glyph flags found, or 0

Since: 1.0.5

### hb_ft_font_set_funcs ()

    void
    hb_ft_font_set_funcs (hb_font_t *font);

Configures the font-functions structure of the specified hb_font_t font object to use FreeType font functions.

In particular, you can use this function to configure an existing hb_face_t face object for use with FreeType font functions even if that hb_face_t face object was initially created with `hb_face_create()`, and therefore was not initially configured to use FreeType font functions.

An hb_font_t object created with `hb_ft_font_create()` is preconfigured for FreeType font functions and does not require this function to be used.

Note that if you modify the underlying hb_font_t after calling this function, you need to call `hb_ft_hb_font_changed()` to update the underlying FT_Face.

Note: Internally, this function creates an FT_Face.

#### Parameters

font | hb_font_t to work upon |

Since: 1.0.5

### hb_ft_hb_font_changed ()

    hb_bool_t
    hb_ft_hb_font_changed (hb_font_t *font);

Refreshes the state of the underlying FT_Face of `font` when the hb_font_t `font` has changed. This function should be called after changing the size or variation-axis settings on the `font` . This call is fast if nothing has changed on `font` .

Note that as of version 11.0.0, calling this function is not necessary, as HarfBuzz will automatically detect changes to the font and update the underlying FT_Face as needed.

#### Parameters

font | hb_font_t to work upon |

#### Returns

true if changed, false otherwise

Since: 4.4.0