Functions

aat_layout_feature_type_get_name_id(face: face_t, feature_type: aat_layout_feature_type_t) → int

Fetches the name identifier of the specified feature type in the face’s name table.

Added in version 2.2.0.

Parameters:
Returns:

Name identifier of the requested feature type

aat_layout_feature_type_get_selector_infos(face: face_t, feature_type: aat_layout_feature_type_t, start_offset: int) → tuple[int, list[aat_layout_feature_selector_info_t], int]

Fetches a list of the selectors available for the specified feature in the given face.

If upon return, default_index is set to HB_AAT_LAYOUT_NO_SELECTOR_INDEX, then the feature type is non-exclusive. Otherwise, default_index is the index of the selector that is selected by default.

Added in version 2.2.0.

Parameters:

  • face – face_t to work upon

  • feature_type – The aat_layout_feature_type_t of the requested feature type

  • start_offset – offset of the first feature type to retrieve

Returns:

Number of all available feature selectors

aat_layout_get_feature_types(face: face_t, start_offset: int) → tuple[int, list[aat_layout_feature_type_t]]

Fetches a list of the AAT feature types included in the specified face.

Added in version 2.2.0.

Parameters:

  • face – face_t to work upon

  • start_offset – offset of the first feature type to retrieve

Returns:

Number of all available feature types.

aat_layout_has_positioning(face: face_t) → int

Tests whether the specified face includes any positioning information in the kerx table.

<note>Note: does not examine the GPOS table.</note>

Added in version 2.3.0.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

aat_layout_has_substitution(face: face_t) → int

Tests whether the specified face includes any substitutions in the morx or mort tables.

<note>Note: does not examine the GSUB table.</note>

Added in version 2.3.0.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

aat_layout_has_tracking(face: face_t) → int

Tests whether the specified face includes any tracking information in the trak table.

Added in version 2.3.0.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

blob_create_from_file(file_name: str) → blob_t

Creates a new blob containing the data from the specified binary font file.

Added in version 1.7.7.

Parameters:

file_name – A font filename

Returns:

An blob_t pointer with the content of the file, or blob_get_empty() if failed.

blob_create_from_file_or_fail(file_name: str) → blob_t

Creates a new blob containing the data from the specified binary font file.

Added in version 2.8.2.

Parameters:

file_name – A font filename

Returns:

An blob_t pointer with the content of the file, or NULL if failed.

blob_create_sub_blob(parent: blob_t, offset: int, length: int) → blob_t

Returns a blob that represents a range of bytes in parent. The new blob is always created with HB_MEMORY_MODE_READONLY, meaning that it will never modify data in the parent blob. The parent data is not expected to be modified, and will result in undefined behavior if it is.

Makes parent immutable.

Added in version 0.9.2.

Parameters:

  • parent – Parent blob.

  • offset – Start offset of sub-blob within parent, in bytes.

  • length – Length of sub-blob.

Returns:

New blob, or the empty blob if something failed or if length is zero or offset is beyond the end of parent’s data. Destroy with blob_destroy().

blob_get_data(blob: blob_t) → list[str] | None

Fetches the data from a blob.

Added in version 0.9.2.

Parameters:

blob – a blob.

Returns:

the byte data of blob.

blob_get_data_writable(blob: blob_t) → list[str]

Tries to make blob data writable (possibly copying it) and return pointer to data.

Fails if blob has been made immutable, or if memory allocation fails.

Added in version 0.9.2.

Parameters:

blob – a blob.

Returns:

Writable blob data, or NULL if failed.

blob_get_empty() → blob_t

Returns the singleton empty blob.

See TODO:link object types for more information.

Added in version 0.9.2.

Returns:

The empty blob.

blob_get_length(blob: blob_t) → int

Fetches the length of a blob’s data.

Added in version 0.9.2.

Parameters:

blob – a blob.

Returns:

the length of blob data in bytes.

blob_is_immutable(blob: blob_t) → int

Tests whether a blob is immutable.

Added in version 0.9.2.

Parameters:

blob – a blob.

Returns:

true if blob is immutable, false otherwise

blob_make_immutable(blob: blob_t) → None

Makes a blob immutable.

Added in version 0.9.2.

Parameters:

blob – a blob

buffer_add(buffer: buffer_t, codepoint: int, cluster: int) → None

Appends a character with the Unicode value of codepoint to buffer, and gives it the initial cluster value of cluster. Clusters can be any thing the client wants, they are usually used to refer to the index of the character in the input text stream and are output in glyph_info_t.cluster field.

This function does not check the validity of codepoint, it is up to the caller to ensure it is a valid Unicode code point.

Added in version 0.9.7.

Parameters:

  • buffer – An buffer_t

  • codepoint – A Unicode code point.

  • cluster – The cluster value of codepoint.

buffer_add_codepoints(buffer: buffer_t, text: Sequence[int], item_offset: int, item_length: int) → None

Appends characters from text array to buffer. The item_offset is the position of the first character from text that will be appended, and item_length is the number of character. When shaping part of a larger text (e.g. a run of text from a paragraph), instead of passing just the substring corresponding to the run, it is preferable to pass the whole paragraph and specify the run start and length as item_offset and item_length, respectively, to give HarfBuzz the full context to be able, for example, to do cross-run Arabic shaping or properly handle combining marks at stat of run.

This function does not check the validity of text, it is up to the caller to ensure it contains a valid Unicode scalar values. In contrast, buffer_add_utf32() can be used that takes similar input but performs sanity-check on the input.

Added in version 0.9.31.

Parameters:

  • buffer – a buffer_t to append characters to.

  • text – an array of Unicode code points to append.

  • item_offset – the offset of the first code point to add to the buffer.

  • item_length – the number of code points to add to the buffer, or -1 for the end of text (assuming it is NULL terminated).

buffer_add_latin1(buffer: buffer_t, text: Sequence[int], item_offset: int, item_length: int) → None

Similar to buffer_add_codepoints(), but allows only access to first 256 Unicode code points that can fit in 8-bit strings.

<note>Has nothing to do with non-Unicode Latin-1 encoding.</note>

Added in version 0.9.39.

Parameters:

  • buffer – An buffer_t

  • text – an array of UTF-8 characters to append

  • item_offset – the offset of the first character to add to the buffer

  • item_length – the number of characters to add to the buffer, or -1 for the end of text (assuming it is NULL terminated)

buffer_add_utf16(buffer: buffer_t, text: Sequence[int], item_offset: int, item_length: int) → None

See buffer_add_codepoints().

Replaces invalid UTF-16 characters with the buffer replacement code point, see buffer_set_replacement_codepoint().

Added in version 0.9.2.

Parameters:

  • buffer – An buffer_t

  • text – An array of UTF-16 characters to append

  • item_offset – The offset of the first character to add to the buffer

  • item_length – The number of characters to add to the buffer, or -1 for the end of text (assuming it is NULL terminated)

buffer_add_utf32(buffer: buffer_t, text: Sequence[int], item_offset: int, item_length: int) → None

See buffer_add_codepoints().

Replaces invalid UTF-32 characters with the buffer replacement code point, see buffer_set_replacement_codepoint().

Added in version 0.9.2.

Parameters:

  • buffer – An buffer_t

  • text – An array of UTF-32 characters to append

  • item_offset – The offset of the first character to add to the buffer

  • item_length – The number of characters to add to the buffer, or -1 for the end of text (assuming it is NULL terminated)

buffer_add_utf8(buffer: buffer_t, text: Sequence[int], item_offset: int, item_length: int) → None

See buffer_add_codepoints().

Replaces invalid UTF-8 characters with the buffer replacement code point, see buffer_set_replacement_codepoint().

Added in version 0.9.2.

Parameters:

  • buffer – An buffer_t

  • text – An array of UTF-8 characters to append.

  • item_offset – The offset of the first character to add to the buffer.

  • item_length – The number of characters to add to the buffer, or -1 for the end of text (assuming it is NULL terminated).

buffer_allocation_successful(buffer: buffer_t) → int

Check if allocating memory for the buffer succeeded.

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

Returns:

true if buffer memory allocation succeeded, false otherwise.

buffer_append(buffer: buffer_t, source: buffer_t, start: int, end: int) → None

Append (part of) contents of another buffer to this buffer.

Added in version 1.5.0.

Parameters:

  • buffer – An buffer_t

  • source – source buffer_t

  • start – start index into source buffer to copy. Use 0 to copy from start of buffer.

  • end – end index into source buffer to copy. Use HB_FEATURE_GLOBAL_END to copy to end of buffer.

buffer_clear_contents(buffer: buffer_t) → None

Similar to buffer_reset(), but does not clear the Unicode functions and the replacement code point.

Added in version 0.9.11.

Parameters:

buffer – An buffer_t

buffer_create() → buffer_t

Creates a new buffer_t with all properties to defaults.

Added in version 0.9.2.

Returns:

A newly allocated buffer_t with a reference count of 1. The initial reference count should be released with buffer_destroy() when you are done using the buffer_t. This function never returns NULL. If memory cannot be allocated, a special buffer_t object will be returned on which buffer_allocation_successful() returns false.

buffer_create_similar(src: buffer_t) → buffer_t

Creates a new buffer_t, similar to buffer_create(). The only difference is that the buffer is configured similarly to src.

Added in version 3.3.0.

Parameters:

src – An buffer_t

Returns:

A newly allocated buffer_t, similar to buffer_create().

buffer_deserialize_glyphs(buffer: buffer_t, buf: Sequence[str], font: font_t | None, format: buffer_serialize_format_t) → tuple[int, str]

Deserializes glyphs buffer from textual representation in the format produced by buffer_serialize_glyphs().

Added in version 0.9.7.

Parameters:
Returns:

true if parse was successful, false if an error occurred.

buffer_deserialize_unicode(buffer: buffer_t, buf: Sequence[str], format: buffer_serialize_format_t) → tuple[int, str]

Deserializes Unicode buffer from textual representation in the format produced by buffer_serialize_unicode().

Added in version 2.7.3.

Parameters:
Returns:

true if parse was successful, false if an error occurred.

buffer_diff(buffer: buffer_t, reference: buffer_t, dottedcircle_glyph: int, position_fuzz: int) → buffer_diff_flags_t

If dottedcircle_glyph is (hb_codepoint_t) -1 then HB_BUFFER_DIFF_FLAG_DOTTED_CIRCLE_PRESENT and HB_BUFFER_DIFF_FLAG_NOTDEF_PRESENT are never returned. This should be used by most callers if just comparing two buffers is needed.

Added in version 1.5.0.

Parameters:

  • buffer – a buffer.

  • reference – other buffer to compare to.

  • dottedcircle_glyph – glyph id of U+25CC DOTTED CIRCLE, or (hb_codepoint_t) -1.

  • position_fuzz – allowed absolute difference in position values.

buffer_get_cluster_level(buffer: buffer_t) → buffer_cluster_level_t

Fetches the cluster level of a buffer. The buffer_cluster_level_t dictates one aspect of how HarfBuzz will treat non-base characters during shaping.

Added in version 0.9.42.

Parameters:

buffer – An buffer_t

Returns:

The cluster level of buffer

buffer_get_content_type(buffer: buffer_t) → buffer_content_type_t

Fetches the type of buffer contents. Buffers are either empty, contain characters (before shaping), or contain glyphs (the result of shaping).

Added in version 0.9.5.

Parameters:

buffer – An buffer_t

Returns:

The type of buffer contents

buffer_get_direction(buffer: buffer_t) → direction_t

See buffer_set_direction()

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

Returns:

The direction of the buffer.

buffer_get_empty() → buffer_t

Fetches an empty buffer_t.

Added in version 0.9.2.

Returns:

The empty buffer

buffer_get_flags(buffer: buffer_t) → buffer_flags_t

Fetches the buffer_flags_t of buffer.

Added in version 0.9.7.

Parameters:

buffer – An buffer_t

Returns:

The buffer flags

buffer_get_glyph_infos(buffer: buffer_t) → list[glyph_info_t]

Returns buffer glyph information array. Returned pointer is valid as long as buffer contents are not modified.

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

Returns:

The buffer glyph information array. The value valid as long as buffer has not been modified.

buffer_get_glyph_positions(buffer: buffer_t) → list[glyph_position_t]

Returns buffer glyph position array. Returned pointer is valid as long as buffer contents are not modified.

If buffer did not have positions before, the positions will be initialized to zeros, unless this function is called from within a buffer message callback (see buffer_set_message_func()), in which case NULL is returned.

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

Returns:

The buffer glyph position array. The value valid as long as buffer has not been modified.

buffer_get_invisible_glyph(buffer: buffer_t) → int

See buffer_set_invisible_glyph().

Added in version 2.0.0.

Parameters:

buffer – An buffer_t

Returns:

The buffer invisible codepoint_t

buffer_get_language(buffer: buffer_t) → language_t

See buffer_set_language().

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

Returns:

The language_t of the buffer. Must not be freed by the caller.

buffer_get_length(buffer: buffer_t) → int

Returns the number of items in the buffer.

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

Returns:

The buffer length. The value valid as long as buffer has not been modified.

buffer_get_not_found_glyph(buffer: buffer_t) → int

See buffer_set_not_found_glyph().

Added in version 3.1.0.

Parameters:

buffer – An buffer_t

Returns:

The buffer not-found codepoint_t

buffer_get_replacement_codepoint(buffer: buffer_t) → int

Fetches the codepoint_t that replaces invalid entries for a given encoding when adding text to buffer.

Added in version 0.9.31.

Parameters:

buffer – An buffer_t

Returns:

The buffer replacement codepoint_t

buffer_get_script(buffer: buffer_t) → script_t

Fetches the script of buffer.

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

Returns:

The script_t of the buffer

buffer_get_segment_properties(buffer: buffer_t) → segment_properties_t

Sets props to the segment_properties_t of buffer.

Added in version 0.9.7.

Parameters:

buffer – An buffer_t

buffer_get_unicode_funcs(buffer: buffer_t) → unicode_funcs_t

Fetches the Unicode-functions structure of a buffer.

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

Returns:

The Unicode-functions structure

buffer_guess_segment_properties(buffer: buffer_t) → None

Sets unset buffer segment properties based on buffer Unicode contents. If buffer is not empty, it must have content type HB_BUFFER_CONTENT_TYPE_UNICODE.

If buffer script is not set (ie. is HB_SCRIPT_INVALID), it will be set to the Unicode script of the first character in the buffer that has a script other than HB_SCRIPT_COMMON, HB_SCRIPT_INHERITED, and HB_SCRIPT_UNKNOWN.

Next, if buffer direction is not set (ie. is HB_DIRECTION_INVALID), it will be set to the natural horizontal direction of the buffer script as returned by script_get_horizontal_direction(). If script_get_horizontal_direction() returns HB_DIRECTION_INVALID, then HB_DIRECTION_LTR is used.

Finally, if buffer language is not set (ie. is HB_LANGUAGE_INVALID), it will be set to the process’s default language as returned by language_get_default(). This may change in the future by taking buffer script into consideration when choosing a language. Note that language_get_default() is NOT threadsafe the first time it is called. See documentation for that function for details.

Added in version 0.9.7.

Parameters:

buffer – An buffer_t

buffer_has_positions(buffer: buffer_t) → int

Returns whether buffer has glyph position data. A buffer gains position data when buffer_get_glyph_positions() is called on it, and cleared of position data when buffer_clear_contents() is called.

Added in version 2.7.3.

Parameters:

buffer – an buffer_t.

Returns:

true if the buffer has position array, false otherwise.

buffer_normalize_glyphs(buffer: buffer_t) → None

Reorders a glyph buffer to have canonical in-cluster glyph order / position. The resulting clusters should behave identical to pre-reordering clusters.

<note>This has nothing to do with Unicode normalization.</note>

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

buffer_pre_allocate(buffer: buffer_t, size: int) → int

Pre allocates memory for buffer to fit at least size number of items.

Added in version 0.9.2.

Parameters:

  • buffer – An buffer_t

  • size – Number of items to pre allocate.

Returns:

true if buffer memory allocation succeeded, false otherwise

buffer_reset(buffer: buffer_t) → None

Resets the buffer to its initial status, as if it was just newly created with buffer_create().

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

buffer_reverse(buffer: buffer_t) → None

Reverses buffer contents.

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

buffer_reverse_clusters(buffer: buffer_t) → None

Reverses buffer clusters. That is, the buffer contents are reversed, then each cluster (consecutive items having the same cluster number) are reversed again.

Added in version 0.9.2.

Parameters:

buffer – An buffer_t

buffer_reverse_range(buffer: buffer_t, start: int, end: int) → None

Reverses buffer contents between start and end.

Added in version 0.9.41.

Parameters:

  • buffer – An buffer_t

  • start – start index

  • end – end index

buffer_serialize(buffer: buffer_t, start: int, end: int, font: font_t | None, format: buffer_serialize_format_t, flags: buffer_serialize_flags_t) → tuple[int, bytes, int]

Serializes buffer into a textual representation of its content, whether Unicode codepoints or glyph identifiers and positioning information. This is useful for showing the contents of the buffer, for example during debugging. See the documentation of buffer_serialize_unicode() and buffer_serialize_glyphs() for a description of the output format.

Added in version 2.7.3.

Parameters:

  • buffer – an buffer_t buffer.

  • start – the first item in buffer to serialize.

  • end – the last item in buffer to serialize.

  • font – the font_t used to shape this buffer, needed to read glyph names and extents. If NULL, an empty font will be used.

  • format – the buffer_serialize_format_t to use for formatting the output.

  • flags – the buffer_serialize_flags_t that control what glyph properties to serialize.

Returns:

The number of serialized items.

buffer_serialize_format_from_string(str: Sequence[int]) → buffer_serialize_format_t

Parses a string into an buffer_serialize_format_t. Does not check if str is a valid buffer serialization format, use buffer_serialize_list_formats() to get the list of supported formats.

Added in version 0.9.7.

Parameters:

str – a string to parse

Returns:

The parsed buffer_serialize_format_t.

buffer_serialize_format_to_string(format: buffer_serialize_format_t) → str

Converts format to the string corresponding it, or NULL if it is not a valid buffer_serialize_format_t.

Added in version 0.9.7.

Parameters:

format – an buffer_serialize_format_t to convert.

Returns:

A NULL terminated string corresponding to format. Should not be freed.

buffer_serialize_glyphs(buffer: buffer_t, start: int, end: int, font: font_t | None, format: buffer_serialize_format_t, flags: buffer_serialize_flags_t) → tuple[int, bytes, int]

Serializes buffer into a textual representation of its glyph content, useful for showing the contents of the buffer, for example during debugging. There are currently two supported serialization formats:

text

A human-readable, plain text format. The serialized glyphs will look something like:

[uni0651=0``518``,0+0|uni0628=0+1897]

  • The serialized glyphs are delimited with [ and ].

  • Glyphs are separated with |

  • Each glyph starts with glyph name, or glyph index if HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES flag is set. Then, - If HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set, = then glyph_info_t.cluster. - If HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set, the glyph_position_t in the format:

    • If HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set, the glyph_extents_t in the format <x_bearing,y_bearing,width,height>

json

A machine-readable, structured format. The serialized glyphs will look something like:

[{"g":"uni0651","cl":0,"dx":518,"dy":0,"ax":0,"ay":0},
{"g":"uni0628","cl":0,"dx":0,"dy":0,"ax":1897,"ay":0}]

Each glyph is a JSON object, with the following properties:

Added in version 0.9.7.

param buffer:

an buffer_t buffer.

param start:

the first item in buffer to serialize.

param end:

the last item in buffer to serialize.

param font:

the font_t used to shape this buffer, needed to read glyph names and extents. If NULL, an empty font will be used.

param format:

the buffer_serialize_format_t to use for formatting the output.

param flags:

the buffer_serialize_flags_t that control what glyph properties to serialize.

return:

The number of serialized items.

buffer_serialize_list_formats() → list[str]

Returns a list of supported buffer serialization formats.

Added in version 0.9.7.

Returns:

A string array of buffer serialization formats. Should not be freed.

buffer_serialize_unicode(buffer: buffer_t, start: int, end: int, format: buffer_serialize_format_t, flags: buffer_serialize_flags_t) → tuple[int, bytes, int]

Serializes buffer into a textual representation of its content, when the buffer contains Unicode codepoints (i.e., before shaping). This is useful for showing the contents of the buffer, for example during debugging. There are currently two supported serialization formats:

text

A human-readable, plain text format. The serialized codepoints will look something like:

 <U+0651=0|U+0628=1>

  • Glyphs are separated with |

  • Unicode codepoints are expressed as zero-padded four (or more) digit hexadecimal numbers preceded by U+

  • If HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set, the cluster will be indicated with a = then glyph_info_t.cluster.

json

A machine-readable, structured format. The serialized codepoints will be a list of objects with the following properties:

  • u: the Unicode codepoint as a decimal integer

  • cl: glyph_info_t.cluster if HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set.

For example:

[{u:1617,cl:0},{u:1576,cl:1}]

Added in version 2.7.3.

param buffer:

an buffer_t buffer.

param start:

the first item in buffer to serialize.

param end:

the last item in buffer to serialize.

param format:

the buffer_serialize_format_t to use for formatting the output.

param flags:

the buffer_serialize_flags_t that control what glyph properties to serialize.

return:

The number of serialized items.

buffer_set_cluster_level(buffer: buffer_t, cluster_level: buffer_cluster_level_t) → None

Sets the cluster level of a buffer. The buffer_cluster_level_t dictates one aspect of how HarfBuzz will treat non-base characters during shaping.

Added in version 0.9.42.

Parameters:

  • buffer – An buffer_t

  • cluster_level – The cluster level to set on the buffer

buffer_set_content_type(buffer: buffer_t, content_type: buffer_content_type_t) → None

Sets the type of buffer contents. Buffers are either empty, contain characters (before shaping), or contain glyphs (the result of shaping).

You rarely need to call this function, since a number of other functions transition the content type for you. Namely:

The above transitions are designed such that one can use a buffer in a loop of “reset : add-text : shape” without needing to ever modify the content type manually.

Added in version 0.9.5.

Parameters:

  • buffer – An buffer_t

  • content_type – The type of buffer contents to set

buffer_set_direction(buffer: buffer_t, direction: direction_t) → None

Set the text flow direction of the buffer. No shaping can happen without setting buffer direction, and it controls the visual direction for the output glyphs; for RTL direction the glyphs will be reversed. Many layout features depend on the proper setting of the direction, for example, reversing RTL text before shaping, then shaping with LTR direction is not the same as keeping the text in logical order and shaping with RTL direction.

Added in version 0.9.2.

Parameters:
buffer_set_flags(buffer: buffer_t, flags: buffer_flags_t) → None

Sets buffer flags to flags. See buffer_flags_t.

Added in version 0.9.7.

Parameters:

  • buffer – An buffer_t

  • flags – The buffer flags to set

buffer_set_invisible_glyph(buffer: buffer_t, invisible: int) → None

Sets the codepoint_t that replaces invisible characters in the shaping result. If set to zero (default), the glyph for the U+0020 SPACE character is used. Otherwise, this value is used verbatim.

Added in version 2.0.0.

Parameters:

  • buffer – An buffer_t

  • invisible – the invisible codepoint_t

buffer_set_language(buffer: buffer_t, language: language_t) → None

Sets the language of buffer to language.

Languages are crucial for selecting which OpenType feature to apply to the buffer which can result in applying language-specific behaviour. Languages are orthogonal to the scripts, and though they are related, they are different concepts and should not be confused with each other.

Use language_from_string() to convert from BCP 47 language tags to language_t.

Added in version 0.9.2.

Parameters:

  • buffer – An buffer_t

  • language – An hb_language_t to set

buffer_set_length(buffer: buffer_t, length: int) → int

Similar to buffer_pre_allocate(), but clears any new items added at the end.

Added in version 0.9.2.

Parameters:

  • buffer – An buffer_t

  • length – The new length of buffer

Returns:

true if buffer memory allocation succeeded, false otherwise.

buffer_set_message_func(buffer: buffer_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for buffer_message_func_t.

Added in version 1.1.3.

Parameters:

  • buffer – An buffer_t

  • func – Callback function

  • user_data – Data to pass to func

buffer_set_not_found_glyph(buffer: buffer_t, not_found: int) → None

Sets the codepoint_t that replaces characters not found in the font during shaping.

The not-found glyph defaults to zero, sometimes known as the “.notdef” glyph. This API allows for differentiating the two.

Added in version 3.1.0.

Parameters:

  • buffer – An buffer_t

  • not_found – the not-found codepoint_t

buffer_set_replacement_codepoint(buffer: buffer_t, replacement: int) → None

Sets the codepoint_t that replaces invalid entries for a given encoding when adding text to buffer.

Default is HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT.

Added in version 0.9.31.

Parameters:

  • buffer – An buffer_t

  • replacement – the replacement codepoint_t

buffer_set_script(buffer: buffer_t, script: script_t) → None

Sets the script of buffer to script.

Script is crucial for choosing the proper shaping behaviour for scripts that require it (e.g. Arabic) and the which OpenType features defined in the font to be applied.

You can pass one of the predefined script_t values, or use script_from_string() or script_from_iso15924_tag() to get the corresponding script from an ISO 15924 script tag.

Added in version 0.9.2.

Parameters:
buffer_set_segment_properties(buffer: buffer_t, props: segment_properties_t) → None

Sets the segment properties of the buffer, a shortcut for calling buffer_set_direction(), buffer_set_script() and buffer_set_language() individually.

Added in version 0.9.7.

Parameters:
buffer_set_unicode_funcs(buffer: buffer_t, unicode_funcs: unicode_funcs_t) → None

Sets the Unicode-functions structure of a buffer to unicode_funcs.

Added in version 0.9.2.

Parameters:

  • buffer – An buffer_t

  • unicode_funcs – The Unicode-functions structure

color_get_alpha(color: int) → int

Fetches the alpha channel of the given color.

Added in version 2.1.0.

Parameters:

color – an color_t we are interested in its channels.

Returns:

Alpha channel value

color_get_blue(color: int) → int

Fetches the blue channel of the given color.

Added in version 2.1.0.

Parameters:

color – an color_t we are interested in its channels.

Returns:

Blue channel value

color_get_green(color: int) → int

Fetches the green channel of the given color.

Added in version 2.1.0.

Parameters:

color – an color_t we are interested in its channels.

Returns:

Green channel value

color_get_red(color: int) → int

Fetches the red channel of the given color.

Added in version 2.1.0.

Parameters:

color – an color_t we are interested in its channels.

Returns:

Red channel value

color_line_get_color_stops(color_line: color_line_t, start: int) → tuple[int, list[color_stop_t]]

Fetches a list of color stops from the given color line object.

Note that due to variations being applied, the returned color stops may be out of order. It is the callers responsibility to ensure that color stops are sorted by their offset before they are used.

Added in version 7.0.0.

Parameters:

  • color_line – a color_line_t object

  • start – the index of the first color stop to return

Returns:

the total number of color stops in color_line

color_line_get_extend(color_line: color_line_t) → paint_extend_t

Fetches the extend mode of the color line object.

Added in version 7.0.0.

Parameters:

color_line – a color_line_t object

Returns:

the extend mode of color_line

direction_from_string(str: Sequence[int]) → direction_t

Converts a string to an direction_t.

Matching is loose and applies only to the first letter. For examples, “LTR” and “left-to-right” will both return HB_DIRECTION_LTR.

Unmatched strings will return HB_DIRECTION_INVALID.

Added in version 0.9.2.

Parameters:

str – String to convert

Returns:

The direction_t matching str

direction_to_string(direction: direction_t) → str

Converts an direction_t to a string.

Added in version 0.9.2.

Parameters:

direction – The direction_t to convert

Returns:

The string corresponding to direction

draw_close_path(dfuncs: draw_funcs_t, draw_data: None, st: draw_state_t) → None

Perform a “close-path” draw operation.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions

  • draw_data – associated draw data passed by the caller

  • st – current draw state

draw_cubic_to(dfuncs: draw_funcs_t, draw_data: None, st: draw_state_t, control1_x: float, control1_y: float, control2_x: float, control2_y: float, to_x: float, to_y: float) → None

Perform a “cubic-to” draw operation.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions

  • draw_data – associated draw data passed by the caller

  • st – current draw state

  • control1_x – X component of first control point

  • control1_y – Y component of first control point

  • control2_x – X component of second control point

  • control2_y – Y component of second control point

  • to_x – X component of target point

  • to_y – Y component of target point

draw_funcs_create() → draw_funcs_t

Creates a new draw callbacks object.

Added in version 4.0.0.

Returns:

A newly allocated draw_funcs_t with a reference count of 1. The initial reference count should be released with hb_draw_funcs_destroy when you are done using the draw_funcs_t. This function never returns NULL. If memory cannot be allocated, a special singleton draw_funcs_t object will be returned.

draw_funcs_get_empty() → draw_funcs_t

Fetches the singleton empty draw-functions structure.

Added in version 7.0.0.

Returns:

The empty draw-functions structure

draw_funcs_is_immutable(dfuncs: draw_funcs_t) → int

Checks whether dfuncs is immutable.

Added in version 4.0.0.

Parameters:

dfuncs – draw functions

Returns:

true if dfuncs is immutable, false otherwise

draw_funcs_make_immutable(dfuncs: draw_funcs_t) → None

Makes dfuncs object immutable.

Added in version 4.0.0.

Parameters:

dfuncs – draw functions

draw_funcs_set_close_path_func(dfuncs: draw_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets close-path callback to the draw functions object.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions object

  • func – close-path callback

  • user_data – Data to pass to func

draw_funcs_set_cubic_to_func(dfuncs: draw_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets cubic-to callback to the draw functions object.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions

  • func – cubic-to callback

  • user_data – Data to pass to func

draw_funcs_set_line_to_func(dfuncs: draw_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets line-to callback to the draw functions object.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions object

  • func – line-to callback

  • user_data – Data to pass to func

draw_funcs_set_move_to_func(dfuncs: draw_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets move-to callback to the draw functions object.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions object

  • func – move-to callback

  • user_data – Data to pass to func

draw_funcs_set_quadratic_to_func(dfuncs: draw_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets quadratic-to callback to the draw functions object.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions object

  • func – quadratic-to callback

  • user_data – Data to pass to func

draw_line_to(dfuncs: draw_funcs_t, draw_data: None, st: draw_state_t, to_x: float, to_y: float) → None

Perform a “line-to” draw operation.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions

  • draw_data – associated draw data passed by the caller

  • st – current draw state

  • to_x – X component of target point

  • to_y – Y component of target point

draw_move_to(dfuncs: draw_funcs_t, draw_data: None, st: draw_state_t, to_x: float, to_y: float) → None

Perform a “move-to” draw operation.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions

  • draw_data – associated draw data passed by the caller

  • st – current draw state

  • to_x – X component of target point

  • to_y – Y component of target point

draw_quadratic_to(dfuncs: draw_funcs_t, draw_data: None, st: draw_state_t, control_x: float, control_y: float, to_x: float, to_y: float) → None

Perform a “quadratic-to” draw operation.

Added in version 4.0.0.

Parameters:

  • dfuncs – draw functions

  • draw_data – associated draw data passed by the caller

  • st – current draw state

  • control_x – X component of control point

  • control_y – Y component of control point

  • to_x – X component of target point

  • to_y – Y component of target point

face_builder_add_table(face: face_t, tag: int, blob: blob_t) → int

Add table for tag with data provided by blob to the face. face must be created using face_builder_create().

Added in version 1.9.0.

Parameters:

  • face – A face object created with face_builder_create()

  • tag – The tag_t of the table to add

  • blob – The blob containing the table data to add

face_builder_create() → face_t

Creates a face_t that can be used with face_builder_add_table(). After tables are added to the face, it can be compiled to a binary font file by calling face_reference_blob().

Added in version 1.9.0.

Returns:

New face.

face_builder_sort_tables(face: face_t, tags: Sequence[int]) → None

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.

Added in version 5.3.0.

Parameters:

  • face – A face object created with face_builder_create()

  • tags – ordered list of table tags terminated by ``%HB_TAG_NONE``

face_collect_nominal_glyph_mapping(face: face_t) → tuple[map_t, set_t]

Collects the mapping from Unicode characters to nominal glyphs of the face, and optionally all of the Unicode characters covered by face.

Added in version 7.0.0.

Parameters:

face – A face object

face_collect_unicodes(face: face_t) → set_t

Collects all of the Unicode characters covered by face and adds them to the set_t set out.

Added in version 1.9.0.

Parameters:

face – A face object

face_collect_variation_selectors(face: face_t) → set_t

Collects all Unicode “Variation Selector” characters covered by face and adds them to the set_t set out.

Added in version 1.9.0.

Parameters:

face – A face object

face_collect_variation_unicodes(face: face_t, variation_selector: int) → set_t

Collects all Unicode characters for variation_selector covered by face and adds them to the set_t set out.

Added in version 1.9.0.

Parameters:

  • face – A face object

  • variation_selector – The Variation Selector to query

face_count(blob: blob_t) → int

Fetches the number of faces in a blob.

Added in version 1.7.7.

Parameters:

blob – a blob.

Returns:

Number of faces in blob

face_create(blob: blob_t, index: int) → face_t

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>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 face_get_index().</note>

<note>Note: The high 16-bits of index, if non-zero, are used by font_create() to load named-instances in variable fonts. See font_create() for details.</note>

Added in version 0.9.2.

Parameters:

  • blob – blob_t to work upon

  • index – The index of the face within blob

Returns:

The new face object

face_create_for_tables(reference_table_func: Callable[[...], blob_t], *user_data: Any) → face_t

Variant of 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 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.

Added in version 0.9.2.

Parameters:

  • reference_table_func – Table-referencing function

  • user_data – A pointer to the user data

Returns:

The new face object

face_get_empty() → face_t

Fetches the singleton empty face object.

Added in version 0.9.2.

Returns:

The empty face object

face_get_glyph_count(face: face_t) → int

Fetches the glyph-count value of the specified face object.

Added in version 0.9.7.

Parameters:

face – A face object

Returns:

The glyph-count value of face

face_get_index(face: face_t) → int

Fetches the face-index corresponding to the given face.

<note>Note: face indices within a collection are zero-based.</note>

Added in version 0.9.2.

Parameters:

face – A face object

Returns:

The index of face.

face_get_table_tags(face: face_t, start_offset: int) → tuple[int, list[int]]

Fetches a list of all table tags for a face, if possible. The list returned will begin at the offset provided

Added in version 1.6.0.

Parameters:

  • face – A face object

  • start_offset – The index of first table tag to retrieve

Returns:

Total number of tables, or zero if it is not possible to list

face_get_upem(face: face_t) → int

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.

Added in version 0.9.2.

Parameters:

face – A face object

Returns:

The upem value of face

face_is_immutable(face: face_t) → int

Tests whether the given face object is immutable.

Added in version 0.9.2.

Parameters:

face – A face object

Returns:

true is face is immutable, false otherwise

face_make_immutable(face: face_t) → None

Makes the given face object immutable.

Added in version 0.9.2.

Parameters:

face – A face object

face_reference_blob(face: face_t) → blob_t

Fetches a pointer to the binary blob that contains the specified face. Returns an empty blob if referencing face data is not possible.

Added in version 0.9.2.

Parameters:

face – A face object

Returns:

A pointer to the blob for face

face_reference_table(face: face_t, tag: int) → blob_t

Fetches a reference to the specified table within the specified face.

Added in version 0.9.2.

Parameters:

  • face – A face object

  • tag – The tag_t of the table to query

Returns:

A pointer to the tag table within face

face_set_glyph_count(face: face_t, glyph_count: int) → None

Sets the glyph count for a face object to the specified value.

This API is used in rare circumstances.

Added in version 0.9.7.

Parameters:

  • face – A face object

  • glyph_count – The glyph-count value to assign

face_set_index(face: face_t, index: int) → None

Assigns the specified face-index to face. Fails if the face is immutable.

<note>Note: changing the index has no effect on the face itself This only changes the value returned by face_get_index().</note>

Added in version 0.9.2.

Parameters:

  • face – A face object

  • index – The index to assign

face_set_upem(face: face_t, upem: int) → None

Sets the units-per-em (upem) for a face object to the specified value.

This API is used in rare circumstances.

Added in version 0.9.2.

Parameters:

  • face – A face object

  • upem – The units-per-em value to assign

feature_from_string(str: Sequence[int]) → tuple[int, feature_t]

Parses a string into a feature_t.

The format for specifying feature strings follows. All valid CSS font-feature-settings values other than ‘normal’ and the global values are also accepted, though not documented below. CSS string escapes are not supported.

The range indices refer to the positions between Unicode characters. The position before the first character is always 0.

The format is Python-esque. Here is how it all works:

<informaltable pgwide=’1’ align=’left’ frame=’none’> <tgroup cols=’5’> <thead> <row><entry>Syntax</entry> <entry>Value</entry> <entry>Start</entry> <entry>End</entry></row> </thead> <tbody> <row><entry>Setting value:</entry></row> <row><entry>kern</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>+kern</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>-kern</entry> <entry>0</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature off</entry></row> <row><entry>kern=0</entry> <entry>0</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature off</entry></row> <row><entry>kern=1</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>aalt=2</entry> <entry>2</entry> <entry>0</entry> <entry>∞</entry> <entry>Choose 2nd alternate</entry></row> <row><entry>Setting index:</entry></row> <row><entry>kern[]</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>kern[:]</entry> <entry>1</entry> <entry>0</entry> <entry>∞</entry> <entry>Turn feature on</entry></row> <row><entry>kern[5:]</entry> <entry>1</entry> <entry>5</entry> <entry>∞</entry> <entry>Turn feature on, partial</entry></row> <row><entry>kern[:5]</entry> <entry>1</entry> <entry>0</entry> <entry>5</entry> <entry>Turn feature on, partial</entry></row> <row><entry>kern[3:5]</entry> <entry>1</entry> <entry>3</entry> <entry>5</entry> <entry>Turn feature on, range</entry></row> <row><entry>kern[3]</entry> <entry>1</entry> <entry>3</entry> <entry>3+1</entry> <entry>Turn feature on, single char</entry></row> <row><entry>Mixing it all:</entry></row> <row><entry>aalt[3:5]=2</entry> <entry>2</entry> <entry>3</entry> <entry>5</entry> <entry>Turn 2nd alternate on for range</entry></row> </tbody> </tgroup> </informaltable>

Added in version 0.9.5.

Parameters:

str – a string to parse

Returns:

true if str is successfully parsed, false otherwise

feature_to_string(feature: feature_t) → list[str]

Converts a feature_t into a NULL-terminated string in the format understood by feature_from_string(). The client in responsible for allocating big enough size for buf, 128 bytes is more than enough.

Added in version 0.9.5.

Parameters:

feature – an feature_t to convert

font_add_glyph_origin_for_direction(font: font_t, glyph: int, direction: direction_t) → tuple[int, int]

Adds the origin coordinates to an (X,Y) point coordinate, in the specified glyph ID in the specified font.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

  • direction – The direction of the text segment

font_changed(font: font_t) → None

Notifies the font that underlying font data has changed. This has the effect of increasing the serial as returned by font_get_serial(), which invalidates internal caches.

Added in version 4.4.0.

Parameters:

font – font_t to work upon

font_create(face: face_t) → font_t

Constructs a new font object from the specified face.

<note>Note: If face’s index value (as passed to face_create() has non-zero top 16-bits, those bits minus one are passed to font_set_var_named_instance(), effectively loading a named-instance of a variable font, instead of the default-instance. This allows specifying which named-instance to load by default when creating the face.</note>

Added in version 0.9.2.

Parameters:

face – a face.

Returns:

The new font object

font_create_sub_font(parent: font_t) → font_t

Constructs a sub-font font object from the specified parent font, replicating the parent’s properties.

Added in version 0.9.2.

Parameters:

parent – The parent font object

Returns:

The new sub-font font object

font_draw_glyph(font: font_t, glyph: int, dfuncs: draw_funcs_t, draw_data: None) → None

Draws the outline that corresponds to a glyph in the specified font.

The outline is returned by way of calls to the callbacks of the dfuncs objects, with draw_data passed to them.

Added in version 7.0.0.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID

  • dfuncs – draw_funcs_t to draw to

  • draw_data – User data to pass to draw callbacks

font_funcs_create() → font_funcs_t

Creates a new font_funcs_t structure of font functions.

Added in version 0.9.2.

Returns:

The font-functions structure

font_funcs_get_empty() → font_funcs_t

Fetches an empty font-functions structure.

Added in version 0.9.2.

Returns:

The font-functions structure

font_funcs_is_immutable(ffuncs: font_funcs_t) → int

Tests whether a font-functions structure is immutable.

Added in version 0.9.2.

Parameters:

ffuncs – The font-functions structure

Returns:

true if ffuncs is immutable, false otherwise

font_funcs_make_immutable(ffuncs: font_funcs_t) → None

Makes a font-functions structure immutable.

Added in version 0.9.2.

Parameters:

ffuncs – The font-functions structure

font_funcs_set_draw_glyph_func(ffuncs: font_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the implementation function for font_draw_glyph_func_t.

Added in version 7.0.0.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_font_h_extents_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, font_extents_t]], *user_data: Any) → None

Sets the implementation function for font_get_font_h_extents_func_t.

Added in version 1.1.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_font_v_extents_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, font_extents_t]], *user_data: Any) → None

Sets the implementation function for font_get_font_v_extents_func_t.

Added in version 1.1.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_contour_point_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, int, int]], *user_data: Any) → None

Sets the implementation function for font_get_glyph_contour_point_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_extents_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, glyph_extents_t]], *user_data: Any) → None

Sets the implementation function for font_get_glyph_extents_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_from_name_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, int]], *user_data: Any) → None

Sets the implementation function for font_get_glyph_from_name_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, int]], *user_data: Any) → None

Deprecated. Use font_funcs_set_nominal_glyph_func() and font_funcs_set_variation_glyph_func() instead.

Added in version 0.9.2.

Deprecated since version 1.2.3: Please do not use it in newly written code

Parameters:

  • ffuncs – The font-functions structure

  • func – callback function

  • user_data – data to pass to func

font_funcs_set_glyph_h_advance_func(ffuncs: font_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for font_get_glyph_h_advance_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_h_advances_func(ffuncs: font_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for font_get_glyph_h_advances_func_t.

Added in version 1.8.6.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_h_kerning_func(ffuncs: font_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for font_get_glyph_h_kerning_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_h_origin_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, int, int]], *user_data: Any) → None

Sets the implementation function for font_get_glyph_h_origin_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_name_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, list[str]]], *user_data: Any) → None

Sets the implementation function for font_get_glyph_name_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_shape_func(ffuncs: font_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the implementation function for font_get_glyph_shape_func_t, which is the same as font_draw_glyph_func_t.

Added in version 4.0.0.

Deprecated since version 7.0.0: Use font_funcs_set_draw_glyph_func() instead

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_v_advance_func(ffuncs: font_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for font_get_glyph_v_advance_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_v_advances_func(ffuncs: font_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for font_get_glyph_v_advances_func_t.

Added in version 1.8.6.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_v_kerning_func(ffuncs: font_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for font_get_glyph_v_kerning_func_t.

Added in version 0.9.2.

Deprecated since version 2.0.0: Please do not use it in newly written code

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_glyph_v_origin_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, int, int]], *user_data: Any) → None

Sets the implementation function for font_get_glyph_v_origin_func_t.

Added in version 0.9.2.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_nominal_glyph_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, int]], *user_data: Any) → None

Sets the implementation function for font_get_nominal_glyph_func_t.

Added in version 1.2.3.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_nominal_glyphs_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, int]], *user_data: Any) → None

Sets the implementation function for font_get_nominal_glyphs_func_t.

Added in version 2.0.0.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_paint_glyph_func(ffuncs: font_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the implementation function for font_paint_glyph_func_t.

Added in version 7.0.0.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_funcs_set_variation_glyph_func(ffuncs: font_funcs_t, func: Callable[[...], tuple[int, int]], *user_data: Any) → None

Sets the implementation function for font_get_variation_glyph_func_t.

Added in version 1.2.3.

Parameters:

  • ffuncs – A font-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

font_get_empty() → font_t

Fetches the empty font object.

Added in version 0.9.2.

Returns:

The empty font object

font_get_extents_for_direction(font: font_t, direction: direction_t) → font_extents_t

Fetches the extents for a font in a text segment of the specified direction.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 1.1.3.

Parameters:

  • font – font_t to work upon

  • direction – The direction of the text segment

font_get_face(font: font_t) → face_t

Fetches the face associated with the specified font object.

Added in version 0.9.2.

Parameters:

font – font_t to work upon

Returns:

The face_t value

font_get_glyph(font: font_t, unicode: int, variation_selector: int) → tuple[int, int]

Fetches the glyph ID for a Unicode code point in the specified font, with an optional variation selector.

If variation_selector is 0, calls font_get_nominal_glyph(); otherwise calls font_get_variation_glyph().

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • unicode – The Unicode code point to query

  • variation_selector – A variation-selector code point

Returns:

true if data found, false otherwise

font_get_glyph_advance_for_direction(font: font_t, glyph: int, direction: direction_t) → tuple[int, int]

Fetches the advance for a glyph ID from the specified font, in a text segment of the specified direction.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

  • direction – The direction of the text segment

font_get_glyph_advances_for_direction(font: font_t, direction: direction_t, count: int, first_glyph: int, glyph_stride: int) → tuple[int, int]

Fetches the advances for a sequence of glyph IDs in the specified font, in a text segment of the specified direction.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 1.8.6.

Parameters:

  • font – font_t to work upon

  • direction – The direction of the text segment

  • count – The number of glyph IDs in the sequence queried

  • first_glyph – The first glyph ID to query

  • glyph_stride – The stride between successive glyph IDs

font_get_glyph_contour_point(font: font_t, glyph: int, point_index: int) → tuple[int, int, int]

Fetches the (x,y) coordinates of a specified contour-point index in the specified glyph, within the specified font.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

  • point_index – The contour-point index to query

Returns:

true if data found, false otherwise

font_get_glyph_contour_point_for_origin(font: font_t, glyph: int, point_index: int, direction: direction_t) → tuple[int, int, int]

Fetches the (X,Y) coordinates of a specified contour-point index in the specified glyph ID in the specified font, with respect to the origin in a text segment in the specified direction.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

  • point_index – The contour-point index to query

  • direction – The direction of the text segment

Returns:

true if data found, false otherwise

font_get_glyph_extents(font: font_t, glyph: int) → tuple[int, glyph_extents_t]

Fetches the glyph_extents_t data for a glyph ID in the specified font.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

Returns:

true if data found, false otherwise

font_get_glyph_extents_for_origin(font: font_t, glyph: int, direction: direction_t) → tuple[int, glyph_extents_t]

Fetches the glyph_extents_t data for a glyph ID in the specified font, with respect to the origin in a text segment in the specified direction.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

  • direction – The direction of the text segment

Returns:

true if data found, false otherwise

font_get_glyph_from_name(font: font_t, name: Sequence[str]) → tuple[int, int]

Fetches the glyph ID that corresponds to a name string in the specified font.

<note>Note: len == -1 means the name string is null-terminated.</note>

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • name – The name string to query

Returns:

true if data found, false otherwise

font_get_glyph_h_advance(font: font_t, glyph: int) → int

Fetches the advance for a glyph ID in the specified font, for horizontal text segments.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

Returns:

The advance of glyph within font

font_get_glyph_h_advances(font: font_t, count: int, first_glyph: int, glyph_stride: int, advance_stride: int) → int

Fetches the advances for a sequence of glyph IDs in the specified font, for horizontal text segments.

Added in version 1.8.6.

Parameters:

  • font – font_t to work upon

  • count – The number of glyph IDs in the sequence queried

  • first_glyph – The first glyph ID to query

  • glyph_stride – The stride between successive glyph IDs

  • advance_stride – The stride between successive advances

font_get_glyph_h_kerning(font: font_t, left_glyph: int, right_glyph: int) → int

Fetches the kerning-adjustment value for a glyph-pair in the specified font, for horizontal text segments.

<note>It handles legacy kerning only (as returned by the corresponding font_funcs_t function).</note>

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • left_glyph – The glyph ID of the left glyph in the glyph pair

  • right_glyph – The glyph ID of the right glyph in the glyph pair

Returns:

The kerning adjustment value

font_get_glyph_h_origin(font: font_t, glyph: int) → tuple[int, int, int]

Fetches the (X,Y) coordinates of the origin for a glyph ID in the specified font, for horizontal text segments.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

Returns:

true if data found, false otherwise

font_get_glyph_kerning_for_direction(font: font_t, first_glyph: int, second_glyph: int, direction: direction_t) → tuple[int, int]

Fetches the kerning-adjustment value for a glyph-pair in the specified font.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • first_glyph – The glyph ID of the first glyph in the glyph pair to query

  • second_glyph – The glyph ID of the second glyph in the glyph pair to query

  • direction – The direction of the text segment

font_get_glyph_name(font: font_t, glyph: int) → tuple[int, list[str]]

Fetches the glyph-name string for a glyph ID in the specified font.

According to the OpenType specification, glyph names are limited to 63 characters and can only contain (a subset of) ASCII.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

Returns:

true if data found, false otherwise

font_get_glyph_origin_for_direction(font: font_t, glyph: int, direction: direction_t) → tuple[int, int]

Fetches the (X,Y) coordinates of the origin for a glyph in the specified font.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

  • direction – The direction of the text segment

font_get_glyph_shape(font: font_t, glyph: int, dfuncs: draw_funcs_t, draw_data: None) → None

Fetches the glyph shape that corresponds to a glyph in the specified font. The shape is returned by way of calls to the callbacks of the dfuncs objects, with draw_data passed to them.

Added in version 4.0.0.

Deprecated since version 7.0.0: Use font_draw_glyph() instead

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID

  • dfuncs – draw_funcs_t to draw to

  • draw_data – User data to pass to draw callbacks

font_get_glyph_v_advance(font: font_t, glyph: int) → int

Fetches the advance for a glyph ID in the specified font, for vertical text segments.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

Returns:

The advance of glyph within font

font_get_glyph_v_advances(font: font_t, count: int, first_glyph: int, glyph_stride: int) → tuple[int, int]

Fetches the advances for a sequence of glyph IDs in the specified font, for vertical text segments.

Added in version 1.8.6.

Parameters:

  • font – font_t to work upon

  • count – The number of glyph IDs in the sequence queried

  • first_glyph – The first glyph ID to query

  • glyph_stride – The stride between successive glyph IDs

font_get_glyph_v_kerning(font: font_t, top_glyph: int, bottom_glyph: int) → int

Fetches the kerning-adjustment value for a glyph-pair in the specified font, for vertical text segments.

<note>It handles legacy kerning only (as returned by the corresponding font_funcs_t function).</note>

Added in version 0.9.2.

Deprecated since version 2.0.0: Please do not use it in newly written code

Parameters:

  • font – font_t to work upon

  • top_glyph – The glyph ID of the top glyph in the glyph pair

  • bottom_glyph – The glyph ID of the bottom glyph in the glyph pair

Returns:

The kerning adjustment value

font_get_glyph_v_origin(font: font_t, glyph: int) → tuple[int, int, int]

Fetches the (X,Y) coordinates of the origin for a glyph ID in the specified font, for vertical text segments.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

Returns:

true if data found, false otherwise

font_get_h_extents(font: font_t) → tuple[int, font_extents_t]

Fetches the extents for a specified font, for horizontal text segments.

Added in version 1.1.3.

Parameters:

font – font_t to work upon

Returns:

true if data found, false otherwise

font_get_nominal_glyph(font: font_t, unicode: int) → tuple[int, int]

Fetches the nominal glyph ID for a Unicode code point in the specified font.

This version of the function should not be used to fetch glyph IDs for code points modified by variation selectors. For variation-selector support, user font_get_variation_glyph() or use font_get_glyph().

Added in version 1.2.3.

Parameters:

  • font – font_t to work upon

  • unicode – The Unicode code point to query

Returns:

true if data found, false otherwise

font_get_nominal_glyphs(font: font_t, count: int, first_unicode: int, unicode_stride: int, glyph_stride: int) → tuple[int, int]

Fetches the nominal glyph IDs for a sequence of Unicode code points. Glyph IDs must be returned in a codepoint_t output parameter. Stops at the first unsupported glyph ID.

Added in version 2.6.3.

Parameters:

  • font – font_t to work upon

  • count – number of code points to query

  • first_unicode – The first Unicode code point to query

  • unicode_stride – The stride between successive code points

  • glyph_stride – The stride between successive glyph IDs

Returns:

the number of code points processed

font_get_parent(font: font_t) → font_t

Fetches the parent font of font.

Added in version 0.9.2.

Parameters:

font – font_t to work upon

Returns:

The parent font object

font_get_ppem(font: font_t) → tuple[int, int]

Fetches the horizontal and vertical points-per-em (ppem) of a font.

Added in version 0.9.2.

Parameters:

font – font_t to work upon

font_get_ptem(font: font_t) → float

Fetches the “point size” of a font. Used in CoreText to implement optical sizing.

Added in version 1.6.0.

Parameters:

font – font_t to work upon

Returns:

Point size. A value of zero means “not set.”

font_get_scale(font: font_t) → tuple[int, int]

Fetches the horizontal and vertical scale of a font.

Added in version 0.9.2.

Parameters:

font – font_t to work upon

font_get_serial(font: font_t) → int

Returns the internal serial number of the font. The serial number is increased every time a setting on the font is changed, using a setter function.

Added in version 4.4.0.

Parameters:

font – font_t to work upon

Returns:

serial number

font_get_synthetic_bold(font: font_t) → tuple[float, float, int]

Fetches the “synthetic boldness” parameters of a font.

Added in version 7.0.0.

Parameters:

font – font_t to work upon

font_get_synthetic_slant(font: font_t) → float

Fetches the “synthetic slant” of a font.

Added in version 3.3.0.

Parameters:

font – font_t to work upon

Returns:

Synthetic slant. By default is zero.

font_get_v_extents(font: font_t) → tuple[int, font_extents_t]

Fetches the extents for a specified font, for vertical text segments.

Added in version 1.1.3.

Parameters:

font – font_t to work upon

Returns:

true if data found, false otherwise

font_get_var_coords_design(font: font_t) → tuple[float, int]

Fetches the list of variation coordinates (in design-space units) currently set on a font.

Note that this returned array may only contain values for some (or none) of the axes; omitted axes effectively have their default values.

Return value is valid as long as variation coordinates of the font are not modified.

Added in version 3.3.0.

Parameters:

font – font_t to work upon

Returns:

coordinates array

font_get_var_coords_normalized(font: font_t) → tuple[int, int]

Fetches the list of normalized variation coordinates currently set on a font.

Note that this returned array may only contain values for some (or none) of the axes; omitted axes effectively have zero values.

Return value is valid as long as variation coordinates of the font are not modified.

Added in version 1.4.2.

Parameters:

font – font_t to work upon

Returns:

coordinates array

font_get_var_named_instance(font: font_t) → int

Returns the currently-set named-instance index of the font.

Added in version 7.0.0.

Parameters:

font – a font.

Returns:

Named-instance index or FONT_NO_VAR_NAMED_INSTANCE.

font_get_variation_glyph(font: font_t, unicode: int, variation_selector: int) → tuple[int, int]

Fetches the glyph ID for a Unicode code point when followed by by the specified variation-selector code point, in the specified font.

Added in version 1.2.3.

Parameters:

  • font – font_t to work upon

  • unicode – The Unicode code point to query

  • variation_selector – The variation-selector code point to query

Returns:

true if data found, false otherwise

font_glyph_from_string(font: font_t, s: Sequence[int]) → tuple[int, int]

Fetches the glyph ID from font that matches the specified string. Strings of the format gidDDD or uniUUUU are parsed automatically.

<note>Note: len == -1 means the string is null-terminated.</note>

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • s – string to query

Returns:

true if data found, false otherwise

font_glyph_to_string(font: font_t, glyph: int) → list[str]

Fetches the name of the specified glyph ID in font and returns it in string 's.

If the glyph ID has no name in font, a string of the form gidDDD is generated, with DDD being the glyph ID.

According to the OpenType specification, glyph names are limited to 63 characters and can only contain (a subset of) ASCII.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

font_is_immutable(font: font_t) → int

Tests whether a font object is immutable.

Added in version 0.9.2.

Parameters:

font – font_t to work upon

Returns:

true if font is immutable, false otherwise

font_make_immutable(font: font_t) → None

Makes font immutable.

Added in version 0.9.2.

Parameters:

font – font_t to work upon

font_paint_glyph(font: font_t, glyph: int, pfuncs: paint_funcs_t, paint_data: None, palette_index: int, foreground: int) → None

Paints the glyph.

The painting instructions are returned by way of calls to the callbacks of the funcs object, with paint_data passed to them.

If the font has color palettes (see ot_color_has_palettes()), then palette_index selects the palette to use. If the font only has one palette, this will be 0.

Added in version 7.0.0.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID

  • pfuncs – paint_funcs_t to paint with

  • paint_data – User data to pass to paint callbacks

  • palette_index – The index of the font’s color palette to use

  • foreground – The foreground color, unpremultipled

font_set_face(font: font_t, face: face_t) → None

Sets face as the font-face value of font.

Added in version 1.4.3.

Parameters:

  • font – font_t to work upon

  • face – The face_t to assign

font_set_funcs(font: font_t, klass: font_funcs_t, *font_data: Any) → None

Replaces the font-functions structure attached to a font, updating the font’s user-data with font-data and the destroy callback.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • klass – The font-functions structure.

  • font_data – Data to attach to font

font_set_funcs_data(font: font_t, font_data: None, destroy: Callable[[...], None] | None = None) → None

Replaces the user data attached to a font, updating the font’s destroy callback.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • font_data – Data to attach to font

  • destroy – The function to call when font_data is not needed anymore

font_set_parent(font: font_t, parent: font_t) → None

Sets the parent font of font.

Added in version 1.0.5.

Parameters:

  • font – font_t to work upon

  • parent – The parent font object to assign

font_set_ppem(font: font_t, x_ppem: int, y_ppem: int) → None

Sets the horizontal and vertical pixels-per-em (PPEM) of a font.

These values are used for pixel-size-specific adjustment to shaping and draw results, though for the most part they are unused and can be left unset.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • x_ppem – Horizontal ppem value to assign

  • y_ppem – Vertical ppem value to assign

font_set_ptem(font: font_t, ptem: float) → None

Sets the “point size” of a font. Set to zero to unset. Used in CoreText to implement optical sizing.

<note>Note: There are 72 points in an inch.</note>

Added in version 1.6.0.

Parameters:

  • font – font_t to work upon

  • ptem – font size in points.

font_set_scale(font: font_t, x_scale: int, y_scale: int) → None

Sets the horizontal and vertical scale of a font.

The font scale is a number related to, but not the same as, font size. Typically the client establishes a scale factor to be used between the two. For example, 64, or 256, which would be the fractional-precision part of the font scale. This is necessary because position_t values are integer types and you need to leave room for fractional values in there.

For example, to set the font size to 20, with 64 levels of fractional precision you would call hb_font_set_scale(font, 20 * 64, 20 * 64).

In the example above, even what font size 20 means is up to you. It might be 20 pixels, or 20 points, or 20 millimeters. HarfBuzz does not care about that. You can set the point size of the font using font_set_ptem(), and the pixel size using font_set_ppem().

The choice of scale is yours but needs to be consistent between what you set here, and what you expect out of position_t as well has draw / paint API output values.

Fonts default to a scale equal to the UPEM value of their face. A font with this setting is sometimes called an “unscaled” font.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • x_scale – Horizontal scale value to assign

  • y_scale – Vertical scale value to assign

font_set_synthetic_bold(font: font_t, x_embolden: float, y_embolden: float, in_place: int) → None

Sets the “synthetic boldness” of a font.

Positive values for x_embolden / y_embolden make a font bolder, negative values thinner. Typical values are in the 0.01 to 0.05 range. The default value is zero.

Synthetic boldness is applied by offsetting the contour points of the glyph shape.

Synthetic boldness is applied when rendering a glyph via font_draw_glyph().

If in_place is false, then glyph advance-widths are also adjusted, otherwise they are not. The in-place mode is useful for simulating font grading.

Added in version 7.0.0.

Parameters:

  • font – font_t to work upon

  • x_embolden – the amount to embolden horizontally

  • y_embolden – the amount to embolden vertically

  • in_place – whether to embolden glyphs in-place

font_set_synthetic_slant(font: font_t, slant: float) → None

Sets the “synthetic slant” of a font. By default is zero. Synthetic slant is the graphical skew applied to the font at rendering time.

HarfBuzz needs to know this value to adjust shaping results, metrics, and style values to match the slanted rendering.

<note>Note: The glyph shape fetched via the font_draw_glyph() function is slanted to reflect this value as well.</note>

<note>Note: The slant value is a ratio. For example, a 20% slant would be represented as a 0.2 value.</note>

Added in version 3.3.0.

Parameters:

  • font – font_t to work upon

  • slant – synthetic slant value.

font_set_var_coords_design(font: font_t, coords: Sequence[float]) → None

Applies a list of variation coordinates (in design-space units) to a font.

Note that this overrides all existing variations set on font. Axes not included in coords will be effectively set to their default values.

Added in version 1.4.2.

Parameters:

  • font – font_t to work upon

  • coords – Array of variation coordinates to apply

font_set_var_coords_normalized(font: font_t, coords: Sequence[int]) → None

Applies a list of variation coordinates (in normalized units) to a font.

Note that this overrides all existing variations set on font. Axes not included in coords will be effectively set to their default values.

<note>Note: Coordinates should be normalized to 2.14.</note>

Added in version 1.4.2.

Parameters:

  • font – font_t to work upon

  • coords – Array of variation coordinates to apply

font_set_var_named_instance(font: font_t, instance_index: int) → None

Sets design coords of a font from a named-instance index.

Added in version 2.6.0.

Parameters:

  • font – a font.

  • instance_index – named instance index.

font_set_variation(font: font_t, tag: int, value: float) → None

Change the value of one variation axis on the font.

Note: This function is expensive to be called repeatedly.

If you want to set multiple variation axes at the same time, use font_set_variations() instead.

Added in version 7.1.0.

Parameters:

  • font – font_t to work upon

  • tag – The tag_t tag of the variation-axis name

  • value – The value of the variation axis

font_set_variations(font: font_t, variations: Sequence[variation_t]) → None

Applies a list of font-variation settings to a font.

Note that this overrides all existing variations set on font. Axes not included in variations will be effectively set to their default values.

Added in version 1.4.2.

Parameters:

  • font – font_t to work upon

  • variations – Array of variation settings to apply

font_subtract_glyph_origin_for_direction(font: font_t, glyph: int, direction: direction_t) → tuple[int, int]

Subtracts the origin coordinates from an (X,Y) point coordinate, in the specified glyph ID in the specified font.

Calls the appropriate direction-specific variant (horizontal or vertical) depending on the value of direction.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph ID to query

  • direction – The direction of the text segment

ft_face_create(ft_face: Face, destroy: Callable[[...], None] | None = None) → face_t

Creates an 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 face_t will use the native HarfBuzz font implementation, unless you call ft_font_set_funcs() on them.

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

Most client programs should use ft_face_create_referenced() (or, perhaps, ft_face_create_cached()) instead.

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

Added in version 0.9.2.

Parameters:

  • ft_face – FT_Face to work upon

  • destroy – A callback to call when the face object is not needed anymore

Returns:

the new face_t face object

ft_face_create_cached(ft_face: Face) → face_t

Creates an 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 face_t will use the native HarfBuzz font implementation, unless you call ft_font_set_funcs() on them.

This variant of the function caches the newly created 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 face_t returned to them, and that face_t will be correctly reference counted.

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

Added in version 0.9.2.

Parameters:

ft_face – FT_Face to work upon

Returns:

the new face_t face object

ft_face_create_referenced(ft_face: Face) → face_t

Creates an 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 face_t will use the native HarfBuzz font implementation, unless you call 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 face_t face object remains alive. Also calls FT_Done_Face() when the face_t face object is destroyed.

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

Added in version 0.9.38.

Parameters:

ft_face – FT_Face to work upon

Returns:

the new face_t face object

ft_font_changed(font: font_t) → None

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.

Added in version 1.0.5.

Parameters:

font – font_t to work upon

ft_font_create(ft_face: Face, destroy: Callable[[...], None] | None = None) → font_t

Creates an font_t font object from the specified FT_Face.

<note>Note: You must set the face size on ft_face before calling ft_font_create() on it. HarfBuzz assumes size is always set and will access size member of FT_Face unconditionally.</note>

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

Most client programs should use ft_font_create_referenced() instead.

If you know you have valid reasons not to use ft_font_create_referenced(), then it is the client program’s responsibility to destroy ft_face after the font_t font object has been destroyed.

HarfBuzz will use the destroy callback on the 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 font_t font object has been destroyed.

Added in version 0.9.2.

Parameters:

  • ft_face – FT_Face to work upon

  • destroy – A callback to call when the font object is not needed anymore

Returns:

the new font_t font object

ft_font_create_referenced(ft_face: Face) → font_t

Creates an font_t font object from the specified FT_Face.

<note>Note: You must set the face size on ft_face before calling ft_font_create_referenced() on it. HarfBuzz assumes size is always set and will access size member of FT_Face unconditionally.</note>

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 font_t font object remains alive.

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

Added in version 0.9.38.

Parameters:

ft_face – FT_Face to work upon

Returns:

the new font_t font object

ft_font_get_load_flags(font: font_t) → int

Fetches the FT_Load_Glyph load flags of the specified font_t.

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

This function works with font_t objects created by ft_font_create() or ft_font_create_referenced().

Added in version 1.0.5.

Parameters:

font – font_t to work upon

Returns:

FT_Load_Glyph flags found, or 0

ft_font_set_funcs(font: font_t) → None

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

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

An font_t object created with 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 font_t after calling this function, you need to call ft_hb_font_changed() to update the underlying FT_Face.

<note>Note: Internally, this function creates an FT_Face. </note>

Added in version 1.0.5.

Parameters:

font – font_t to work upon

ft_font_set_load_flags(font: font_t, load_flags: int) → None

Sets the FT_Load_Glyph load flags for the specified font_t.

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

This function works with font_t objects created by ft_font_create() or ft_font_create_referenced().

Added in version 1.0.5.

Parameters:

  • font – font_t to work upon

  • load_flags – The FreeType load flags to set

ft_hb_font_changed(font: font_t) → int

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.

Added in version 4.4.0.

Parameters:

font – font_t to work upon

Returns:

true if changed, false otherwise

glib_blob_create(gbytes: Bytes) → blob_t

Creates an blob_t blob from the specified GBytes data structure.

Added in version 0.9.38.

Parameters:

gbytes – the GBytes structure to work upon

Returns:

the new blob_t blob object

glib_get_unicode_funcs() → unicode_funcs_t

Fetches a Unicode-functions structure that is populated with the appropriate GLib function for each method.

Added in version 0.9.38.

Returns:

a pointer to the unicode_funcs_t Unicode-functions structure

glib_script_from_script(script: script_t) → UnicodeScript

Fetches the GUnicodeScript identifier that corresponds to the specified script_t script.

Added in version 0.9.38.

Parameters:

script – The script_t to query

Returns:

the GUnicodeScript identifier found

glib_script_to_script(script: UnicodeScript) → script_t

Fetches the script_t script that corresponds to the specified GUnicodeScript identifier.

Added in version 0.9.38.

Parameters:

script – The GUnicodeScript identifier to query

Returns:

the script_t script found

glyph_info_get_glyph_flags(info: glyph_info_t) → glyph_flags_t

Returns glyph flags encoded within a glyph_info_t.

Added in version 1.5.0.

Parameters:

info – a glyph_info_t

Returns:

The glyph_flags_t encoded within info

language_from_string(str: Sequence[int]) → language_t

Converts str representing a BCP 47 language tag to the corresponding language_t.

Added in version 0.9.2.

Parameters:

str – a string representing a BCP 47 language tag

Returns:

The language_t corresponding to the BCP 47 language tag.

language_get_default() → language_t

Fetch the default language from current locale.

<note>Note that the first time this function is called, it calls “setlocale (LC_CTYPE, nullptr)” to fetch current locale. The underlying setlocale function is, in many implementations, NOT threadsafe. To avoid problems, call this function once before multiple threads can call it. This function is only used from buffer_guess_segment_properties() by HarfBuzz itself.</note>

Added in version 0.9.2.

Returns:

The default language of the locale as an language_t

language_matches(language: language_t, specific: language_t) → int

Check whether a second language tag is the same or a more specific version of the provided language tag. For example, “fa_IR.utf8” is a more specific tag for “fa” or for “fa_IR”.

Added in version 5.0.0.

Parameters:
Returns:

true if languages match, false otherwise.

language_to_string(language: language_t) → str

Converts an language_t to a string.

Added in version 0.9.2.

Parameters:

language – The language_t to convert

Returns:

A NULL-terminated string representing the language. Must not be freed by the caller.

map_allocation_successful(map: map_t) → int

Tests whether memory allocation for a set was successful.

Added in version 1.7.7.

Parameters:

map – A map

Returns:

true if allocation succeeded, false otherwise

map_clear(map: map_t) → None

Clears out the contents of map.

Added in version 1.7.7.

Parameters:

map – A map

map_create() → map_t

Creates a new, initially empty map.

Added in version 1.7.7.

Returns:

The new map_t

map_del(map: map_t, key: int) → None

Removes key and its stored value from map.

Added in version 1.7.7.

Parameters:

  • map – A map

  • key – The key to delete

map_get(map: map_t, key: int) → int

Fetches the value stored for key in map.

Added in version 1.7.7.

Parameters:

  • map – A map

  • key – The key to query

map_get_empty() → map_t

Fetches the singleton empty map_t.

Added in version 1.7.7.

Returns:

The empty map_t

map_get_population(map: map_t) → int

Returns the number of key-value pairs in the map.

Added in version 1.7.7.

Parameters:

map – A map

Returns:

The population of map

map_has(map: map_t, key: int) → int

Tests whether key is an element of map.

Added in version 1.7.7.

Parameters:

  • map – A map

  • key – The key to query

Returns:

true if key is found in map, false otherwise

map_hash(map: map_t) → int

Creates a hash representing map.

Added in version 4.4.0.

Parameters:

map – A map

Returns:

A hash of map.

map_is_empty(map: map_t) → int

Tests whether map is empty (contains no elements).

Added in version 1.7.7.

Parameters:

map – A map

Returns:

true if map is empty

map_is_equal(map: map_t, other: map_t) → int

Tests whether map and other are equal (contain the same elements).

Added in version 4.3.0.

Parameters:

  • map – A map

  • other – Another map

Returns:

true if the two maps are equal, false otherwise.

map_keys(map: map_t, keys: set_t) → None

Add the keys of map to keys.

Added in version 7.0.0.

Parameters:

  • map – A map

  • keys – A set

map_next(map: map_t) → tuple[int, int, int, int]

Fetches the next key/value pair in map.

Set idx to -1 to get started.

If the map is modified during iteration, the behavior is undefined.

The order in which the key/values are returned is undefined.

Added in version 7.0.0.

Parameters:

map – A map

Returns:

true if there was a next value, false otherwise

map_set(map: map_t, key: int, value: int) → None

Stores key:value in the map.

Added in version 1.7.7.

Parameters:

  • map – A map

  • key – The key to store in the map

  • value – The value to store for key

map_update(map: map_t, other: map_t) → None

Add the contents of other to map.

Added in version 7.0.0.

Parameters:

  • map – A map

  • other – Another map

map_values(map: map_t, values: set_t) → None

Add the values of map to values.

Added in version 7.0.0.

Parameters:

  • map – A map

  • values – A set

ot_color_glyph_get_layers(face: face_t, glyph: int, start_offset: int) → tuple[int, list[ot_color_layer_t]]

Fetches a list of all color layers for the specified glyph index in the specified face. The list returned will begin at the offset provided.

Added in version 2.1.0.

Parameters:

  • face – face_t to work upon

  • glyph – The glyph index to query

  • start_offset – offset of the first layer to retrieve

Returns:

Total number of layers available for the glyph index queried

ot_color_glyph_has_paint(face: face_t, glyph: int) → int

Tests where a face includes COLRv1 paint data for glyph.

Added in version 7.0.0.

Parameters:

  • face – face_t to work upon

  • glyph – The glyph index to query

Returns:

true if data found, false otherwise

ot_color_glyph_reference_png(font: font_t, glyph: int) → blob_t

Fetches the PNG image for a glyph. This function takes a font object, not a face object, as input. To get an optimally sized PNG blob, the PPEM values must be set on the font object. If PPEM is unset, the blob returned will be the largest PNG available.

If the glyph has no PNG image, the singleton empty blob is returned.

Added in version 2.1.0.

Parameters:

  • font – font_t to work upon

  • glyph – a glyph index

Returns:

An blob_t containing the PNG image for the glyph, if available

ot_color_glyph_reference_svg(face: face_t, glyph: int) → blob_t

Fetches the SVG document for a glyph. The blob may be either plain text or gzip-encoded.

If the glyph has no SVG document, the singleton empty blob is returned.

Added in version 2.1.0.

Parameters:

  • face – face_t to work upon

  • glyph – a svg glyph index

Returns:

An blob_t containing the SVG document of the glyph, if available

ot_color_has_layers(face: face_t) → int

Tests whether a face includes a COLR table with data according to COLRv0.

Added in version 2.1.0.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

ot_color_has_paint(face: face_t) → int

Tests where a face includes a COLR table with data according to COLRv1.

Added in version 7.0.0.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

ot_color_has_palettes(face: face_t) → int

Tests whether a face includes a CPAL color-palette table.

Added in version 2.1.0.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

ot_color_has_png(face: face_t) → int

Tests whether a face has PNG glyph images (either in CBDT or sbix tables).

Added in version 2.1.0.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

ot_color_has_svg(face: face_t) → int

Tests whether a face includes any SVG glyph images.

Added in version 2.1.0.

Parameters:

face – face_t to work upon.

Returns:

true if data found, false otherwise.

ot_color_palette_color_get_name_id(face: face_t, color_index: int) → int

Fetches the name table Name ID that provides display names for the specified color in a face’s CPAL color palette.

Display names can be generic (e.g., “Background”) or specific (e.g., “Eye color”).

Added in version 2.1.0.

Parameters:

  • face – face_t to work upon

  • color_index – The index of the color

Returns:

the Name ID found for the color.

ot_color_palette_get_colors(face: face_t, palette_index: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of the colors in a color palette.

After calling this function, colors will be filled with the palette colors. If colors is NULL, the function will just return the number of total colors without storing any actual colors; this can be used for allocating a buffer of suitable size before calling ot_color_palette_get_colors() a second time.

The RGBA values in the palette are unpremultiplied. See the OpenType spec CPAL section for details.

Added in version 2.1.0.

Parameters:

  • face – face_t to work upon

  • palette_index – the index of the color palette to query

  • start_offset – offset of the first color to retrieve

Returns:

the total number of colors in the palette

ot_color_palette_get_count(face: face_t) → int

Fetches the number of color palettes in a face.

Added in version 2.1.0.

Parameters:

face – face_t to work upon

Returns:

the number of palettes found

ot_color_palette_get_flags(face: face_t, palette_index: int) → ot_color_palette_flags_t

Fetches the flags defined for a color palette.

Added in version 2.1.0.

Parameters:

  • face – face_t to work upon

  • palette_index – The index of the color palette

Returns:

the ot_color_palette_flags_t of the requested color palette

ot_color_palette_get_name_id(face: face_t, palette_index: int) → int

Fetches the name table Name ID that provides display names for a CPAL color palette.

Palette display names can be generic (e.g., “Default”) or provide specific, themed names (e.g., “Spring”, “Summer”, “Fall”, and “Winter”).

Added in version 2.1.0.

Parameters:

  • face – face_t to work upon

  • palette_index – The index of the color palette

Returns:

the Named ID found for the palette. If the requested palette has no name the result is HB_OT_NAME_ID_INVALID.

ot_font_set_funcs(font: font_t) → None

Sets the font functions to use when working with font.

Added in version 0.9.28.

Parameters:

font – font_t to work upon

ot_layout_collect_features(face: face_t, table_tag: int, scripts: Sequence[int] | None = None, languages: Sequence[int] | None = None, features: Sequence[int] | None = None) → set_t

Fetches a list of all feature indexes in the specified face’s GSUB table or GPOS table, underneath the specified scripts, languages, and features. If no list of scripts is provided, all scripts will be queried. If no list of languages is provided, all languages will be queried. If no list of features is provided, all features will be queried.

Added in version 1.8.5.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • scripts – The array of scripts to collect features for, terminated by ``%HB_TAG_NONE``

  • languages – The array of languages to collect features for, terminated by ``%HB_TAG_NONE``

  • features – The array of features to collect, terminated by ``%HB_TAG_NONE``

ot_layout_collect_features_map(face: face_t, table_tag: int, script_index: int, language_index: int) → map_t

Fetches the mapping from feature tags to feature indexes for the specified script and language.

Added in version 8.1.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_index – The index of the requested language tag

ot_layout_collect_lookups(face: face_t, table_tag: int, scripts: Sequence[int] | None = None, languages: Sequence[int] | None = None, features: Sequence[int] | None = None) → set_t

Fetches a list of all feature-lookup indexes in the specified face’s GSUB table or GPOS table, underneath the specified scripts, languages, and features. If no list of scripts is provided, all scripts will be queried. If no list of languages is provided, all languages will be queried. If no list of features is provided, all features will be queried.

Added in version 0.9.8.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • scripts – The array of scripts to collect lookups for, terminated by ``%HB_TAG_NONE``

  • languages – The array of languages to collect lookups for, terminated by ``%HB_TAG_NONE``

  • features – The array of features to collect lookups for, terminated by ``%HB_TAG_NONE``

ot_layout_feature_get_characters(face: face_t, table_tag: int, feature_index: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of the characters defined as having a variant under the specified “Character Variant” (“cvXX”) feature tag.

Added in version 2.0.0.

Parameters:

  • face – face_t to work upon

  • table_tag – table tag to query, “GSUB” or “GPOS”.

  • feature_index – index of feature to query.

  • start_offset – offset of the first character to retrieve

Returns:

Number of total sample characters in the cvXX feature.

ot_layout_feature_get_lookups(face: face_t, table_tag: int, feature_index: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of all lookups enumerated for the specified feature, in the specified face’s GSUB table or GPOS table. The list returned will begin at the offset provided.

Added in version 0.9.7.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • feature_index – The index of the requested feature

  • start_offset – offset of the first lookup to retrieve

Returns:

Total number of lookups.

ot_layout_feature_get_name_ids(face: face_t, table_tag: int, feature_index: int) → tuple[int, int, int, int, int, int]

Fetches name indices from feature parameters for “Stylistic Set” (‘ssXX’) or “Character Variant” (‘cvXX’) features.

Added in version 2.0.0.

Parameters:

  • face – face_t to work upon

  • table_tag – table tag to query, “GSUB” or “GPOS”.

  • feature_index – index of feature to query.

Returns:

true if data found, false otherwise

ot_layout_feature_with_variations_get_lookups(face: face_t, table_tag: int, feature_index: int, variations_index: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of all lookups enumerated for the specified feature, in the specified face’s GSUB table or GPOS table, enabled at the specified variations index. The list returned will begin at the offset provided.

Added in version 1.4.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • feature_index – The index of the feature to query

  • variations_index – The index of the feature variation to query

  • start_offset – offset of the first lookup to retrieve

Returns:

Total number of lookups.

ot_layout_get_attach_points(face: face_t, glyph: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of all attachment points for the specified glyph in the GDEF table of the face. The list returned will begin at the offset provided.

Useful if the client program wishes to cache the list.

Parameters:

  • face – The face_t to work on

  • glyph – The codepoint_t code point to query

  • start_offset – offset of the first attachment point to retrieve

Returns:

Total number of attachment points for glyph.

ot_layout_get_baseline(font: font_t, baseline_tag: ot_layout_baseline_tag_t, direction: direction_t, script_tag: int, language_tag: int) → tuple[int, int]

Fetches a baseline value from the face.

Added in version 2.6.0.

Parameters:

  • font – a font

  • baseline_tag – a baseline tag

  • direction – text direction.

  • script_tag – script tag.

  • language_tag – language tag, currently unused.

Returns:

true if found baseline value in the font.

ot_layout_get_baseline2(font: font_t, baseline_tag: ot_layout_baseline_tag_t, direction: direction_t, script: script_t, language: language_t | None = None) → tuple[int, int]

Fetches a baseline value from the face.

This function is like ot_layout_get_baseline() but takes script_t and language_t instead of OpenType tag_t.

Added in version 8.0.0.

Parameters:

  • font – a font

  • baseline_tag – a baseline tag

  • direction – text direction.

  • script – script.

  • language – language, currently unused.

Returns:

true if found baseline value in the font.

ot_layout_get_baseline_with_fallback(font: font_t, baseline_tag: ot_layout_baseline_tag_t, direction: direction_t, script_tag: int, language_tag: int) → int

Fetches a baseline value from the face, and synthesizes it if the font does not have it.

Added in version 4.0.0.

Parameters:

  • font – a font

  • baseline_tag – a baseline tag

  • direction – text direction.

  • script_tag – script tag.

  • language_tag – language tag, currently unused.

ot_layout_get_baseline_with_fallback2(font: font_t, baseline_tag: ot_layout_baseline_tag_t, direction: direction_t, script: script_t, language: language_t | None = None) → int

Fetches a baseline value from the face, and synthesizes it if the font does not have it.

This function is like ot_layout_get_baseline_with_fallback() but takes script_t and language_t instead of OpenType tag_t.

Added in version 8.0.0.

Parameters:

  • font – a font

  • baseline_tag – a baseline tag

  • direction – text direction.

  • script – script.

  • language – language, currently unused.

ot_layout_get_font_extents(font: font_t, direction: direction_t, script_tag: int, language_tag: int) → tuple[int, font_extents_t]

Fetches script/language-specific font extents. These values are looked up in the BASE table’s MinMax records.

If no such extents are found, the default extents for the font are fetched. As such, the return value of this function can for the most part be ignored. Note that the per-script/language extents do not have a line-gap value, and the line-gap is set to zero in that case.

Added in version 8.0.0.

Parameters:

  • font – a font

  • direction – text direction.

  • script_tag – script tag.

  • language_tag – language tag.

Returns:

true if found script/language-specific font extents.

ot_layout_get_font_extents2(font: font_t, direction: direction_t, script: script_t, language: language_t | None = None) → tuple[int, font_extents_t]

Fetches script/language-specific font extents. These values are looked up in the BASE table’s MinMax records.

If no such extents are found, the default extents for the font are fetched. As such, the return value of this function can for the most part be ignored. Note that the per-script/language extents do not have a line-gap value, and the line-gap is set to zero in that case.

This function is like ot_layout_get_font_extents() but takes script_t and language_t instead of OpenType tag_t.

Added in version 8.0.0.

Parameters:

  • font – a font

  • direction – text direction.

  • script – script.

  • language – language.

Returns:

true if found script/language-specific font extents.

ot_layout_get_glyph_class(face: face_t, glyph: int) → ot_layout_glyph_class_t

Fetches the GDEF class of the requested glyph in the specified face.

Added in version 0.9.7.

Parameters:

  • face – The face_t to work on

  • glyph – The codepoint_t code point to query

Returns:

The ot_layout_glyph_class_t glyph class of the given code point in the GDEF table of the face.

ot_layout_get_glyphs_in_class(face: face_t, klass: ot_layout_glyph_class_t) → set_t

Retrieves the set of all glyphs from the face that belong to the requested glyph class in the face’s GDEF table.

Added in version 0.9.7.

Parameters:
ot_layout_get_horizontal_baseline_tag_for_script(script: script_t) → ot_layout_baseline_tag_t

Fetches the dominant horizontal baseline tag used by script.

Added in version 4.0.0.

Parameters:

script – a script tag.

Returns:

dominant baseline tag for the script.

ot_layout_get_ligature_carets(font: font_t, direction: direction_t, glyph: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of the caret positions defined for a ligature glyph in the GDEF table of the font. The list returned will begin at the offset provided.

Note that a ligature that is formed from n characters will have n-1 caret positions. The first character is not represented in the array, since its caret position is the glyph position.

The positions returned by this function are ‘unshaped’, and will have to be fixed up for kerning that may be applied to the ligature glyph.

Parameters:

  • font – The font_t to work on

  • direction – The direction_t text direction to use

  • glyph – The codepoint_t code point to query

  • start_offset – offset of the first caret position to retrieve

Returns:

Total number of ligature caret positions for glyph.

ot_layout_get_size_params(face: face_t) → tuple[int, int, int, int, int, int]

Fetches optical-size feature data (i.e., the size feature from GPOS). Note that the subfamily_id and the subfamily name string (accessible via the subfamily_name_id) as used here are defined as pertaining only to fonts within a font family that differ specifically in their respective size ranges; other ways to differentiate fonts within a subfamily are not covered by the size feature.

For more information on this distinction, see the [size feature documentation]( https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size).

Added in version 0.9.10.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

ot_layout_has_glyph_classes(face: face_t) → int

Tests whether a face has any glyph classes defined in its GDEF table.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

ot_layout_has_positioning(face: face_t) → int

Tests whether the specified face includes any GPOS positioning.

Parameters:

face – face_t to work upon

Returns:

true if the face has GPOS data, false otherwise

ot_layout_has_substitution(face: face_t) → int

Tests whether the specified face includes any GSUB substitutions.

Added in version 0.6.0.

Parameters:

face – face_t to work upon

Returns:

true if data found, false otherwise

ot_layout_language_find_feature(face: face_t, table_tag: int, script_index: int, language_index: int, feature_tag: int) → tuple[int, int]

Fetches the index of a given feature tag in the specified face’s GSUB table or GPOS table, underneath the specified script and language.

Added in version 0.6.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_index – The index of the requested language tag

  • feature_tag – tag_t of the feature tag requested

Returns:

true if the feature is found, false otherwise

ot_layout_language_get_feature_indexes(face: face_t, table_tag: int, script_index: int, language_index: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of all features in the specified face’s GSUB table or GPOS table, underneath the specified script and language. The list returned will begin at the offset provided.

Added in version 0.6.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_index – The index of the requested language tag

  • start_offset – offset of the first feature tag to retrieve

Returns:

Total number of features.

ot_layout_language_get_feature_tags(face: face_t, table_tag: int, script_index: int, language_index: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of all features in the specified face’s GSUB table or GPOS table, underneath the specified script and language. The list returned will begin at the offset provided.

Added in version 0.6.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_index – The index of the requested language tag

  • start_offset – offset of the first feature tag to retrieve

Returns:

Total number of feature tags.

ot_layout_language_get_required_feature(face: face_t, table_tag: int, script_index: int, language_index: int) → tuple[int, int, int]

Fetches the tag of a requested feature index in the given face’s GSUB or GPOS table, underneath the specified script and language.

Added in version 0.9.30.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_index – The index of the requested language tag

Returns:

true if the feature is found, false otherwise

ot_layout_language_get_required_feature_index(face: face_t, table_tag: int, script_index: int, language_index: int) → tuple[int, int]

Fetches the index of a requested feature in the given face’s GSUB or GPOS table, underneath the specified script and language.

Added in version 0.6.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_index – The index of the requested language tag

Returns:

true if the feature is found, false otherwise

ot_layout_lookup_collect_glyphs(face: face_t, table_tag: int, lookup_index: int) → tuple[set_t, set_t, set_t, set_t]

Fetches a list of all glyphs affected by the specified lookup in the specified face’s GSUB table or GPOS table.

Added in version 0.9.7.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • lookup_index – The index of the feature lookup to query

ot_layout_lookup_get_glyph_alternates(face: face_t, lookup_index: int, glyph: int, start_offset: int) → tuple[int, list[int]]

Fetches alternates of a glyph from a given GSUB lookup index.

Added in version 2.6.8.

Parameters:

  • face – a face.

  • lookup_index – index of the feature lookup to query.

  • glyph – a glyph id.

  • start_offset – starting offset.

Returns:

Total number of alternates found in the specific lookup index for the given glyph id.

ot_layout_lookup_get_optical_bound(font: font_t, lookup_index: int, direction: direction_t, glyph: int) → int

Fetches the optical bound of a glyph positioned at the margin of text. The direction identifies which edge of the glyph to query.

Added in version 5.3.0.

Parameters:

  • font – a font.

  • lookup_index – index of the feature lookup to query.

  • direction – edge of the glyph to query.

  • glyph – a glyph id.

Returns:

Adjustment value. Negative values mean the glyph will stick out of the margin.

ot_layout_lookup_substitute_closure(face: face_t, lookup_index: int) → set_t

Compute the transitive closure of glyphs needed for a specified lookup.

Added in version 0.9.7.

Parameters:

  • face – face_t to work upon

  • lookup_index – index of the feature lookup to query

ot_layout_lookup_would_substitute(face: face_t, lookup_index: int, glyphs: int, glyphs_length: int, zero_context: int) → int

Tests whether a specified lookup in the specified face would trigger a substitution on the given glyph sequence.

Added in version 0.9.7.

Parameters:

  • face – face_t to work upon

  • lookup_index – The index of the lookup to query

  • glyphs – The sequence of glyphs to query for substitution

  • glyphs_length – The length of the glyph sequence

  • zero_context – bool_t indicating whether pre-/post-context are disallowed in substitutions

Returns:

true if a substitution would be triggered, false otherwise

ot_layout_lookups_substitute_closure(face: face_t, lookups: set_t) → set_t

Compute the transitive closure of glyphs needed for all of the provided lookups.

Added in version 1.8.1.

Parameters:

  • face – face_t to work upon

  • lookups – The set of lookups to query

ot_layout_script_find_language(face: face_t, table_tag: int, script_index: int, language_tag: int, language_index: int) → int

Fetches the index of a given language tag in the specified face’s GSUB table or GPOS table, underneath the specified script tag.

Added in version 0.6.0.

Deprecated since version 2.0.0: Please do not use it in newly written code

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_tag – The tag_t of the requested language

  • language_index – The index of the requested language

Returns:

true if the language tag is found, false otherwise

ot_layout_script_get_language_tags(face: face_t, table_tag: int, script_index: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of language tags in the given face’s GSUB or GPOS table, underneath the specified script index. The list returned will begin at the offset provided.

Added in version 0.6.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • start_offset – offset of the first language tag to retrieve

Returns:

Total number of language tags.

ot_layout_script_select_language(face: face_t, table_tag: int, script_index: int, language_count: int, language_tags: int) → tuple[int, int]

Fetches the index of the first language tag fom language_tags that is present in the specified face’s GSUB or GPOS table, underneath the specified script index.

If none of the given language tags is found, false is returned and language_index is set to the default language index.

Added in version 2.0.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_count – The number of languages in the specified script

  • language_tags – The array of language tags

Returns:

true if one of the given language tags is found, false otherwise

ot_layout_script_select_language2(face: face_t, table_tag: int, script_index: int, language_count: int, language_tags: int) → tuple[int, int, int]

Fetches the index of the first language tag fom language_tags that is present in the specified face’s GSUB or GPOS table, underneath the specified script index.

If none of the given language tags is found, false is returned and language_index is set to HB_OT_LAYOUT_DEFAULT_LANGUAGE_INDEX and chosen_language is set to HB_TAG_NONE.

Added in version 7.0.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_index – The index of the requested script tag

  • language_count – The number of languages in the specified script

  • language_tags – The array of language tags

Returns:

true if one of the given language tags is found, false otherwise

ot_layout_table_choose_script(face: face_t, table_tag: int, script_tags: int) → tuple[int, int, int]

Deprecated since 2.0.0

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_tags – Array of tag_t script tags

ot_layout_table_find_feature_variations(face: face_t, table_tag: int, coords: int, num_coords: int) → tuple[int, int]

Fetches a list of feature variations in the specified face’s GSUB table or GPOS table, at the specified variation coordinates.

Added in version 1.4.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • coords – The variation coordinates to query

  • num_coords – The number of variation coordinates

Returns:

true if feature variations were found, false otherwise.

ot_layout_table_find_script(face: face_t, table_tag: int, script_tag: int) → tuple[int, int]

Fetches the index if a given script tag in the specified face’s GSUB table or GPOS table.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_tag – tag_t of the script tag requested

Returns:

true if the script is found, false otherwise

ot_layout_table_get_feature_tags(face: face_t, table_tag: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of all feature tags in the given face’s GSUB or GPOS table. Note that there might be duplicate feature tags, belonging to different script/language-system pairs of the table.

Added in version 0.6.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • start_offset – offset of the first feature tag to retrieve

Returns:

Total number of feature tags.

ot_layout_table_get_lookup_count(face: face_t, table_tag: int) → int

Fetches the total number of lookups enumerated in the specified face’s GSUB table or GPOS table.

Added in version 0.9.22.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

Returns:

Total number of lookups.

ot_layout_table_get_script_tags(face: face_t, table_tag: int, start_offset: int) → tuple[int, list[int]]

Fetches a list of all scripts enumerated in the specified face’s GSUB table or GPOS table. The list returned will begin at the offset provided.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • start_offset – offset of the first script tag to retrieve

Returns:

Total number of script tags.

ot_layout_table_select_script(face: face_t, table_tag: int, script_count: int, script_tags: int) → tuple[int, int, int]

Selects an OpenType script for table_tag from the script_tags array.

If the table does not have any of the requested scripts, then DFLT, dflt, and latn tags are tried in that order. If the table still does not have any of these scripts, script_index is set to HB_OT_LAYOUT_NO_SCRIPT_INDEX and chosen_script is set to HB_TAG_NONE.

Added in version 2.0.0.

Parameters:

  • face – face_t to work upon

  • table_tag – HB_OT_TAG_GSUB or HB_OT_TAG_GPOS

  • script_count – Number of script tags in the array

  • script_tags – Array of tag_t script tags

Returns:

true if one of the requested scripts is selected, false if a fallback script is selected or if no scripts are selected.

ot_math_get_constant(font: font_t, constant: ot_math_constant_t) → int

Fetches the specified math constant. For most constants, the value returned is an position_t.

However, if the requested constant is HB_OT_MATH_CONSTANT_SCRIPT_PERCENT_SCALE_DOWN, HB_OT_MATH_CONSTANT_SCRIPT_SCRIPT_PERCENT_SCALE_DOWN or HB_OT_MATH_CONSTANT_RADICAL_DEGREE_BOTTOM_RAISE_PERCENT, then the return value is an integer between 0 and 100 representing that percentage.

Added in version 1.3.3.

Parameters:
Returns:

the requested constant or zero

ot_math_get_glyph_assembly(font: font_t, glyph: int, direction: direction_t, start_offset: int) → tuple[int, list[ot_math_glyph_part_t], int]

Fetches the GlyphAssembly for the specified font, glyph index, and direction. Returned are a list of ot_math_glyph_part_t glyph parts that can be used to draw the glyph and an italics-correction value (if one is defined in the font).

<note>The direction parameter is only used to select between horizontal or vertical directions for the construction. Even though all direction_t values are accepted, only the result of HB_DIRECTION_IS_HORIZONTAL is considered.</note>

Added in version 1.3.3.

Parameters:

  • font – font_t to work upon

  • glyph – The index of the glyph to stretch

  • direction – direction of the stretching (horizontal or vertical)

  • start_offset – offset of the first glyph part to retrieve

Returns:

the total number of parts in the glyph assembly

ot_math_get_glyph_italics_correction(font: font_t, glyph: int) → int

Fetches an italics-correction value (if one exists) for the specified glyph index.

Added in version 1.3.3.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph index from which to retrieve the value

Returns:

the italics correction of the glyph or zero

ot_math_get_glyph_kerning(font: font_t, glyph: int, kern: ot_math_kern_t, correction_height: int) → int

Fetches the math kerning (cut-ins) value for the specified font, glyph index, and kern.

If the MathKern table is found, the function examines it to find a height value that is greater or equal to correction_height. If such a height value is found, corresponding kerning value from the table is returned. If no such height value is found, the last kerning value is returned.

Added in version 1.3.3.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph index from which to retrieve the value

  • kern – The ot_math_kern_t from which to retrieve the value

  • correction_height – the correction height to use to determine the kerning.

Returns:

requested kerning value or zero

ot_math_get_glyph_kernings(font: font_t, glyph: int, kern: ot_math_kern_t, start_offset: int) → tuple[int, list[ot_math_kern_entry_t]]

Fetches the raw MathKern (cut-in) data for the specified font, glyph index, and kern. The corresponding list of kern values and correction heights is returned as a list of ot_math_kern_entry_t structs.

See also hb_ot_math_get_glyph_kerning, which handles selecting the appropriate kern value for a given correction height.

<note>For a glyph with n defined kern values (where n > 0), there are only ``n``−1 defined correction heights, as each correction height defines a boundary past which the next kern value should be selected. Therefore, only the ot_math_kern_entry_t.kern_value of the uppermost ot_math_kern_entry_t actually comes from the font; its corresponding ot_math_kern_entry_t.max_correction_height is always set to <code>INT32_MAX</code>.</note>

Added in version 3.4.0.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph index from which to retrieve the kernings

  • kern – The ot_math_kern_t from which to retrieve the kernings

  • start_offset – offset of the first kern entry to retrieve

Returns:

the total number of kern values available or zero

ot_math_get_glyph_top_accent_attachment(font: font_t, glyph: int) → int

Fetches a top-accent-attachment value (if one exists) for the specified glyph index.

For any glyph that does not have a top-accent-attachment value - that is, a glyph not covered by the MathTopAccentAttachment table (or, when font has no MathTopAccentAttachment table or no MATH table, any glyph) - the function synthesizes a value, returning the position at one-half the glyph’s advance width.

Added in version 1.3.3.

Parameters:

  • font – font_t to work upon

  • glyph – The glyph index from which to retrieve the value

Returns:

the top accent attachment of the glyph or 0.5 * the advance width of glyph

ot_math_get_glyph_variants(font: font_t, glyph: int, direction: direction_t, start_offset: int) → tuple[int, list[ot_math_glyph_variant_t]]

Fetches the MathGlyphConstruction for the specified font, glyph index, and direction. The corresponding list of size variants is returned as a list of ot_math_glyph_variant_t structs.

<note>The direction parameter is only used to select between horizontal or vertical directions for the construction. Even though all direction_t values are accepted, only the result of HB_DIRECTION_IS_HORIZONTAL is considered.</note>

Added in version 1.3.3.

Parameters:

  • font – font_t to work upon

  • glyph – The index of the glyph to stretch

  • direction – The direction of the stretching (horizontal or vertical)

  • start_offset – offset of the first variant to retrieve

Returns:

the total number of size variants available or zero

ot_math_get_min_connector_overlap(font: font_t, direction: direction_t) → int

Fetches the MathVariants table for the specified font and returns the minimum overlap of connecting glyphs that are required to draw a glyph assembly in the specified direction.

<note>The direction parameter is only used to select between horizontal or vertical directions for the construction. Even though all direction_t values are accepted, only the result of HB_DIRECTION_IS_HORIZONTAL is considered.</note>

Added in version 1.3.3.

Parameters:

  • font – font_t to work upon

  • direction – direction of the stretching (horizontal or vertical)

Returns:

requested minimum connector overlap or zero

ot_math_has_data(face: face_t) → int

Tests whether a face has a MATH table.

Added in version 1.3.3.

Parameters:

face – face_t to test

Returns:

true if the table is found, false otherwise

ot_math_is_glyph_extended_shape(face: face_t, glyph: int) → int

Tests whether the given glyph index is an extended shape in the face.

Added in version 1.3.3.

Parameters:

  • face – face_t to work upon

  • glyph – The glyph index to test

Returns:

true if the glyph is an extended shape, false otherwise

ot_meta_get_entry_tags(face: face_t, start_offset: int) → tuple[int, list[ot_meta_tag_t]]

Fetches all available feature types.

Added in version 2.6.0.

Parameters:

  • face – a face object

  • start_offset – iteration’s start offset

Returns:

Number of all available feature types.

ot_meta_reference_entry(face: face_t, meta_tag: ot_meta_tag_t) → blob_t

It fetches metadata entry of a given tag from a font.

Added in version 2.6.0.

Parameters:

  • face – a face_t object.

  • meta_tag – tag of metadata you like to have.

Returns:

A blob containing the blob.

ot_metrics_get_position(font: font_t, metrics_tag: ot_metrics_tag_t) → tuple[int, int]

Fetches metrics value corresponding to metrics_tag from font.

Added in version 2.6.0.

Parameters:

  • font – an font_t object.

  • metrics_tag – tag of metrics value you like to fetch.

Returns:

Whether found the requested metrics in the font.

ot_metrics_get_position_with_fallback(font: font_t, metrics_tag: ot_metrics_tag_t) → int

Fetches metrics value corresponding to metrics_tag from font, and synthesizes a value if it the value is missing in the font.

Added in version 4.0.0.

Parameters:

  • font – an font_t object.

  • metrics_tag – tag of metrics value you like to fetch.

ot_metrics_get_variation(font: font_t, metrics_tag: ot_metrics_tag_t) → float

Fetches metrics value corresponding to metrics_tag from font with the current font variation settings applied.

Added in version 2.6.0.

Parameters:

  • font – an font_t object.

  • metrics_tag – tag of metrics value you like to fetch.

Returns:

The requested metric value.

ot_metrics_get_x_variation(font: font_t, metrics_tag: ot_metrics_tag_t) → int

Fetches horizontal metrics value corresponding to metrics_tag from font with the current font variation settings applied.

Added in version 2.6.0.

Parameters:

  • font – an font_t object.

  • metrics_tag – tag of metrics value you like to fetch.

Returns:

The requested metric value.

ot_metrics_get_y_variation(font: font_t, metrics_tag: ot_metrics_tag_t) → int

Fetches vertical metrics value corresponding to metrics_tag from font with the current font variation settings applied.

Added in version 2.6.0.

Parameters:

  • font – an font_t object.

  • metrics_tag – tag of metrics value you like to fetch.

Returns:

The requested metric value.

ot_name_get_utf16(face: face_t, name_id: int, language: language_t) → tuple[int, list[int]]

Fetches a font name from the OpenType ‘name’ table. If language is HB_LANGUAGE_INVALID, English (“en”) is assumed. Returns string in UTF-16 encoding. A NUL terminator is always written for convenience, and isn’t included in the output text_size.

Added in version 2.1.0.

Parameters:

  • face – font face.

  • name_id – OpenType name identifier to fetch.

  • language – language to fetch the name for.

Returns:

full length of the requested string, or 0 if not found.

ot_name_get_utf32(face: face_t, name_id: int, language: language_t) → tuple[int, list[int]]

Fetches a font name from the OpenType ‘name’ table. If language is HB_LANGUAGE_INVALID, English (“en”) is assumed. Returns string in UTF-32 encoding. A NUL terminator is always written for convenience, and isn’t included in the output text_size.

Added in version 2.1.0.

Parameters:

  • face – font face.

  • name_id – OpenType name identifier to fetch.

  • language – language to fetch the name for.

Returns:

full length of the requested string, or 0 if not found.

ot_name_get_utf8(face: face_t, name_id: int, language: language_t) → tuple[int, list[str]]

Fetches a font name from the OpenType ‘name’ table. If language is HB_LANGUAGE_INVALID, English (“en”) is assumed. Returns string in UTF-8 encoding. A NUL terminator is always written for convenience, and isn’t included in the output text_size.

Added in version 2.1.0.

Parameters:

  • face – font face.

  • name_id – OpenType name identifier to fetch.

  • language – language to fetch the name for.

Returns:

full length of the requested string, or 0 if not found.

ot_name_list_names(face: face_t) → list[ot_name_entry_t]

Enumerates all available name IDs and language combinations. Returned array is owned by the face and should not be modified. It can be used as long as face is alive.

Added in version 2.1.0.

Parameters:

face – font face.

Returns:

Array of available name entries.

ot_shape_glyphs_closure(font: font_t, buffer: buffer_t, features: Sequence[feature_t]) → set_t

Computes the transitive closure of glyphs needed for a specified input buffer under the given font and feature list. The closure is computed as a set, not as a list.

Added in version 0.9.2.

Parameters:

  • font – font_t to work upon

  • buffer – The input buffer to compute from

  • features – The features enabled on the buffer

ot_shape_plan_collect_lookups(shape_plan: shape_plan_t, table_tag: int) → set_t

Computes the complete set of GSUB or GPOS lookups that are applicable under a given shape_plan.

Added in version 0.9.7.

Parameters:

  • shape_plan – shape_plan_t to query

  • table_tag – GSUB or GPOS

ot_tag_from_language(language: language_t) → int

Converts an language_t to an tag_t.

Added in version 0.6.0.

Deprecated since version 2.0.0: use ot_tags_from_script_and_language() instead

Parameters:

language – an language_t to convert.

ot_tag_to_language(tag: int) → language_t | None

Converts a language tag to an language_t.

Added in version 0.9.2.

Parameters:

tag – an language tag

Returns:

The language_t corresponding to tag.

ot_tag_to_script(tag: int) → script_t

Converts a script tag to an script_t.

Parameters:

tag – a script tag

Returns:

The script_t corresponding to tag.

ot_tags_from_script(script: script_t) → tuple[int, int]

Converts an script_t to script tags.

Added in version 0.6.0.

Deprecated since version 2.0.0: use ot_tags_from_script_and_language() instead

Parameters:

script – an script_t to convert.

ot_tags_from_script_and_language(script: script_t, language: language_t | None = None) → tuple[int, int, int, int]

Converts an script_t and an language_t to script and language tags.

Added in version 2.0.0.

Parameters:
ot_tags_to_script_and_language(script_tag: int, language_tag: int) → tuple[script_t, language_t]

Converts a script tag and a language tag to an script_t and an language_t.

Added in version 2.0.0.

Parameters:

  • script_tag – a script tag

  • language_tag – a language tag

ot_var_find_axis(face: face_t, axis_tag: int, axis_index: int) → tuple[int, ot_var_axis_t]

Fetches the variation-axis information corresponding to the specified axis tag in the specified face.

Added in version 1.4.2.

Deprecated since version 2.2.0:

Parameters:

  • face – face_t to work upon

  • axis_tag – The tag_t of the variation axis to query

  • axis_index – The index of the variation axis

ot_var_find_axis_info(face: face_t, axis_tag: int) → tuple[int, ot_var_axis_info_t]

Fetches the variation-axis information corresponding to the specified axis tag in the specified face.

Added in version 2.2.0.

Parameters:

  • face – face_t to work upon

  • axis_tag – The tag_t of the variation axis to query

Returns:

true if data found, false otherwise

ot_var_get_axes(face: face_t, start_offset: int) → tuple[int, list[ot_var_axis_t]]

Fetches a list of all variation axes in the specified face. The list returned will begin at the offset provided.

Added in version 1.4.2.

Deprecated since version 2.2.0: use ot_var_get_axis_infos() instead

Parameters:

  • face – face_t to work upon

  • start_offset – offset of the first lookup to retrieve

ot_var_get_axis_count(face: face_t) → int

Fetches the number of OpenType variation axes included in the face.

Added in version 1.4.2.

Parameters:

face – The face_t to work on

Returns:

the number of variation axes defined

ot_var_get_axis_infos(face: face_t, start_offset: int) → tuple[int, list[ot_var_axis_info_t]]

Fetches a list of all variation axes in the specified face. The list returned will begin at the offset provided.

Added in version 2.2.0.

Parameters:

  • face – face_t to work upon

  • start_offset – offset of the first lookup to retrieve

Returns:

the number of variation axes in the face

ot_var_get_named_instance_count(face: face_t) → int

Fetches the number of named instances included in the face.

Added in version 2.2.0.

Parameters:

face – The face_t to work on

Returns:

the number of named instances defined

ot_var_has_data(face: face_t) → int

Tests whether a face includes any OpenType variation data in the fvar table.

Added in version 1.4.2.

Parameters:

face – The face_t to work on

Returns:

true if data found, false otherwise

ot_var_named_instance_get_design_coords(face: face_t, instance_index: int) → tuple[int, list[float]]

Fetches the design-space coordinates corresponding to the given named instance in the face.

Added in version 2.2.0.

Parameters:

  • face – The face_t to work on

  • instance_index – The index of the named instance to query

Returns:

the number of variation axes in the face

ot_var_named_instance_get_postscript_name_id(face: face_t, instance_index: int) → int

Fetches the name table Name ID that provides display names for the “PostScript name” defined for the given named instance in the face.

Added in version 2.2.0.

Parameters:

  • face – The face_t to work on

  • instance_index – The index of the named instance to query

Returns:

the Name ID found for the PostScript name

ot_var_named_instance_get_subfamily_name_id(face: face_t, instance_index: int) → int

Fetches the name table Name ID that provides display names for the “Subfamily name” defined for the given named instance in the face.

Added in version 2.2.0.

Parameters:

  • face – The face_t to work on

  • instance_index – The index of the named instance to query

Returns:

the Name ID found for the Subfamily name

ot_var_normalize_coords(face: face_t, coords_length: int, design_coords: float) → int

Normalizes the given design-space coordinates. The minimum and maximum values for the axis are mapped to the interval [-1,1], with the default axis value mapped to 0.

The normalized values have 14 bits of fixed-point sub-integer precision as per OpenType specification.

Any additional scaling defined in the face’s avar table is also applied, as described at https://docs.microsoft.com/en-us/typography/opentype/spec/avar

Added in version 1.4.2.

Parameters:

  • face – The face_t to work on

  • coords_length – The length of the coordinate array

  • design_coords – The design-space coordinates to normalize

ot_var_normalize_variations(face: face_t, variations: variation_t, variations_length: int) → list[int]

Normalizes all of the coordinates in the given list of variation axes.

Added in version 1.4.2.

Parameters:

  • face – The face_t to work on

  • variations – The array of variations to normalize

  • variations_length – The number of variations to normalize

paint_color(funcs: paint_funcs_t, paint_data: None, is_foreground: int, color: int) → None

Perform a “color” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • is_foreground – whether the color is the foreground

  • color – The color to use

paint_color_glyph(funcs: paint_funcs_t, paint_data: None, glyph: int, font: font_t) → int

Perform a “color-glyph” paint operation.

Added in version 8.2.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • glyph – the glyph ID

  • font – the font

paint_custom_palette_color(funcs: paint_funcs_t, paint_data: None, color_index: int) → tuple[int, int]

Gets the custom palette color for color_index.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • color_index – color index

Returns:

true if found, false otherwise

paint_funcs_create() → paint_funcs_t

Creates a new paint_funcs_t structure of paint functions.

The initial reference count of 1 should be released with paint_funcs_destroy() when you are done using the paint_funcs_t. This function never returns NULL. If memory cannot be allocated, a special singleton paint_funcs_t object will be returned.

Added in version 7.0.0.

Returns:

the paint-functions structure

paint_funcs_get_empty() → paint_funcs_t

Fetches the singleton empty paint-functions structure.

Added in version 7.0.0.

Returns:

The empty paint-functions structure

paint_funcs_is_immutable(funcs: paint_funcs_t) → int

Tests whether a paint-functions structure is immutable.

Added in version 7.0.0.

Parameters:

funcs – The paint-functions structure

Returns:

true if funcs is immutable, false otherwise

paint_funcs_make_immutable(funcs: paint_funcs_t) → None

Makes a paint-functions structure immutable.

After this call, all attempts to set one of the callbacks on funcs will fail.

Added in version 7.0.0.

Parameters:

funcs – The paint-functions structure

paint_funcs_set_color_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the paint-color callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The paint-color callback

  • user_data – Data to pass to func

paint_funcs_set_color_glyph_func(funcs: paint_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the color-glyph callback on the paint functions struct.

Added in version 8.2.0.

Parameters:

  • funcs – A paint functions struct

  • func – The color-glyph callback

  • user_data – Data to pass to func

paint_funcs_set_custom_palette_color_func(funcs: paint_funcs_t, func: Callable[[...], tuple[int, int]], *user_data: Any) → None

Sets the custom-palette-color callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The custom-palette-color callback

  • user_data – Data to pass to func

paint_funcs_set_image_func(funcs: paint_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the paint-image callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The paint-image callback

  • user_data – Data to pass to func

paint_funcs_set_linear_gradient_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the linear-gradient callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The linear-gradient callback

  • user_data – Data to pass to func

paint_funcs_set_pop_clip_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the pop-clip callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The pop-clip callback

  • user_data – Data to pass to func

paint_funcs_set_pop_group_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the pop-group callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The pop-group callback

  • user_data – Data to pass to func

paint_funcs_set_pop_transform_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the pop-transform callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The pop-transform callback

  • user_data – Data to pass to func

paint_funcs_set_push_clip_glyph_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the push-clip-glyph callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The push-clip-glyph callback

  • user_data – Data to pass to func

paint_funcs_set_push_clip_rectangle_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the push-clip-rect callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The push-clip-rectangle callback

  • user_data – Data to pass to func

paint_funcs_set_push_group_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the push-group callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The push-group callback

  • user_data – Data to pass to func

paint_funcs_set_push_transform_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the push-transform callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The push-transform callback

  • user_data – Data to pass to func

paint_funcs_set_radial_gradient_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the radial-gradient callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The radial-gradient callback

  • user_data – Data to pass to func

paint_funcs_set_sweep_gradient_func(funcs: paint_funcs_t, func: Callable[[...], None], *user_data: Any) → None

Sets the sweep-gradient callback on the paint functions struct.

Added in version 7.0.0.

Parameters:

  • funcs – A paint functions struct

  • func – The sweep-gradient callback

  • user_data – Data to pass to func

paint_image(funcs: paint_funcs_t, paint_data: None, image: blob_t, width: int, height: int, format: int, slant: float, extents: glyph_extents_t | None = None) → None

Perform a “image” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • image – image data

  • width – width of the raster image in pixels, or 0

  • height – height of the raster image in pixels, or 0

  • format – the image format as a tag

  • slant – the synthetic slant ratio to be applied to the image during rendering

  • extents – the extents of the glyph

paint_linear_gradient(funcs: paint_funcs_t, paint_data: None, color_line: color_line_t, x0: float, y0: float, x1: float, y1: float, x2: float, y2: float) → None

Perform a “linear-gradient” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • color_line – Color information for the gradient

  • x0 – X coordinate of the first point

  • y0 – Y coordinate of the first point

  • x1 – X coordinate of the second point

  • y1 – Y coordinate of the second point

  • x2 – X coordinate of the third point

  • y2 – Y coordinate of the third point

paint_pop_clip(funcs: paint_funcs_t, paint_data: None) → None

Perform a “pop-clip” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

paint_pop_group(funcs: paint_funcs_t, paint_data: None, mode: paint_composite_mode_t) → None

Perform a “pop-group” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • mode – the compositing mode to use

paint_pop_transform(funcs: paint_funcs_t, paint_data: None) → None

Perform a “pop-transform” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

paint_push_clip_glyph(funcs: paint_funcs_t, paint_data: None, glyph: int, font: font_t) → None

Perform a “push-clip-glyph” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • glyph – the glyph ID

  • font – the font

paint_push_clip_rectangle(funcs: paint_funcs_t, paint_data: None, xmin: float, ymin: float, xmax: float, ymax: float) → None

Perform a “push-clip-rect” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • xmin – min X for the rectangle

  • ymin – min Y for the rectangle

  • xmax – max X for the rectangle

  • ymax – max Y for the rectangle

paint_push_group(funcs: paint_funcs_t, paint_data: None) → None

Perform a “push-group” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

paint_push_transform(funcs: paint_funcs_t, paint_data: None, xx: float, yx: float, xy: float, yy: float, dx: float, dy: float) → None

Perform a “push-transform” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • xx – xx component of the transform matrix

  • yx – yx component of the transform matrix

  • xy – xy component of the transform matrix

  • yy – yy component of the transform matrix

  • dx – dx component of the transform matrix

  • dy – dy component of the transform matrix

paint_radial_gradient(funcs: paint_funcs_t, paint_data: None, color_line: color_line_t, x0: float, y0: float, r0: float, x1: float, y1: float, r1: float) → None

Perform a “radial-gradient” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • color_line – Color information for the gradient

  • x0 – X coordinate of the first circle’s center

  • y0 – Y coordinate of the first circle’s center

  • r0 – radius of the first circle

  • x1 – X coordinate of the second circle’s center

  • y1 – Y coordinate of the second circle’s center

  • r1 – radius of the second circle

paint_sweep_gradient(funcs: paint_funcs_t, paint_data: None, color_line: color_line_t, x0: float, y0: float, start_angle: float, end_angle: float) → None

Perform a “sweep-gradient” paint operation.

Added in version 7.0.0.

Parameters:

  • funcs – paint functions

  • paint_data – associated data passed by the caller

  • color_line – Color information for the gradient

  • x0 – X coordinate of the circle’s center

  • y0 – Y coordinate of the circle’s center

  • start_angle – the start angle

  • end_angle – the end angle

script_from_iso15924_tag(tag: int) → script_t

Converts an ISO 15924 script tag to a corresponding script_t.

Added in version 0.9.2.

Parameters:

tag – an tag_t representing an ISO 15924 tag.

Returns:

An script_t corresponding to the ISO 15924 tag.

script_from_string(str: Sequence[int]) → script_t

Converts a string str representing an ISO 15924 script tag to a corresponding script_t. Shorthand for tag_from_string() then script_from_iso15924_tag().

Added in version 0.9.2.

Parameters:

str – a string representing an ISO 15924 tag.

Returns:

An script_t corresponding to the ISO 15924 tag.

script_get_horizontal_direction(script: script_t) → direction_t

Fetches the direction_t of a script when it is set horizontally. All right-to-left scripts will return HB_DIRECTION_RTL. All left-to-right scripts will return HB_DIRECTION_LTR. Scripts that can be written either horizontally or vertically will return HB_DIRECTION_INVALID. Unknown scripts will return HB_DIRECTION_LTR.

Added in version 0.9.2.

Parameters:

script – The script_t to query

Returns:

The horizontal direction_t of script

script_to_iso15924_tag(script: script_t) → int

Converts an script_t to a corresponding ISO 15924 script tag.

Added in version 0.9.2.

Parameters:

script – an script_t to convert.

Returns:

An tag_t representing an ISO 15924 script tag.

segment_properties_equal(a: segment_properties_t, b: segment_properties_t) → int

Checks the equality of two segment_properties_t’s.

Added in version 0.9.7.

Parameters:
Returns:

true if all properties of a equal those of b, false otherwise.

segment_properties_hash(p: segment_properties_t) → int

Creates a hash representing p.

Added in version 0.9.7.

Parameters:

p – segment_properties_t to hash.

Returns:

A hash of p.

segment_properties_overlay(p: segment_properties_t, src: segment_properties_t) → None

Fills in missing fields of p from src in a considered manner.

First, if p does not have direction set, direction is copied from src.

Next, if p and src have the same direction (which can be unset), if p does not have script set, script is copied from src.

Finally, if p and src have the same direction and script (which either can be unset), if p does not have language set, language is copied from src.

Added in version 3.3.0.

Parameters:
set_add(set: set_t, codepoint: int) → None

Adds codepoint to set.

Added in version 0.9.2.

Parameters:

  • set – A set

  • codepoint – The element to add to set

set_add_range(set: set_t, first: int, last: int) → None

Adds all of the elements from first to last (inclusive) to set.

Added in version 0.9.7.

Parameters:

  • set – A set

  • first – The first element to add to set

  • last – The final element to add to set

set_add_sorted_array(set: set_t, sorted_codepoints: Sequence[int]) → None

Adds num_codepoints codepoints to a set at once. The codepoints array must be in increasing order, with size at least num_codepoints.

Added in version 4.1.0.

Parameters:

  • set – A set

  • sorted_codepoints – Array of codepoints to add

set_allocation_successful(set: set_t) → int

Tests whether memory allocation for a set was successful.

Added in version 0.9.2.

Parameters:

set – A set

Returns:

true if allocation succeeded, false otherwise

set_clear(set: set_t) → None

Clears out the contents of a set.

Added in version 0.9.2.

Parameters:

set – A set

set_create() → set_t

Creates a new, initially empty set.

Added in version 0.9.2.

Returns:

The new set_t

set_del(set: set_t, codepoint: int) → None

Removes codepoint from set.

Added in version 0.9.2.

Parameters:

  • set – A set

  • codepoint – Removes codepoint from set

set_del_range(set: set_t, first: int, last: int) → None

Removes all of the elements from first to last (inclusive) from set.

If last is HB_SET_VALUE_INVALID, then all values greater than or equal to first are removed.

Added in version 0.9.7.

Parameters:

  • set – A set

  • first – The first element to remove from set

  • last – The final element to remove from set

set_get_empty() → set_t

Fetches the singleton empty set_t.

Added in version 0.9.2.

Returns:

The empty set_t

set_get_max(set: set_t) → int

Finds the largest element in the set.

Added in version 0.9.7.

Parameters:

set – A set

Returns:

maximum of set, or HB_SET_VALUE_INVALID if set is empty.

set_get_min(set: set_t) → int

Finds the smallest element in the set.

Added in version 0.9.7.

Parameters:

set – A set

Returns:

minimum of set, or HB_SET_VALUE_INVALID if set is empty.

set_get_population(set: set_t) → int

Returns the number of elements in the set.

Added in version 0.9.7.

Parameters:

set – A set

Returns:

The population of set

set_has(set: set_t, codepoint: int) → int

Tests whether codepoint belongs to set.

Added in version 0.9.2.

Parameters:

  • set – A set

  • codepoint – The element to query

Returns:

true if codepoint is in set, false otherwise

set_hash(set: set_t) → int

Creates a hash representing set.

Added in version 4.4.0.

Parameters:

set – A set

Returns:

A hash of set.

set_intersect(set: set_t, other: set_t) → None

Makes set the intersection of set and other.

Added in version 0.9.2.

Parameters:

  • set – A set

  • other – Another set

set_invert(set: set_t) → None

Inverts the contents of set.

Added in version 3.0.0.

Parameters:

set – A set

set_is_empty(set: set_t) → int

Tests whether a set is empty (contains no elements).

Added in version 0.9.7.

Parameters:

set – a set.

Returns:

true if set is empty

set_is_equal(set: set_t, other: set_t) → int

Tests whether set and other are equal (contain the same elements).

Added in version 0.9.7.

Parameters:

  • set – A set

  • other – Another set

Returns:

true if the two sets are equal, false otherwise.

set_is_inverted(set: set_t) → int

Returns whether the set is inverted.

Added in version 7.0.0.

Parameters:

set – A set

Returns:

true if the set is inverted, false otherwise

set_is_subset(set: set_t, larger_set: set_t) → int

Tests whether set is a subset of larger_set.

Added in version 1.8.1.

Parameters:

  • set – A set

  • larger_set – Another set

Returns:

true if the set is a subset of (or equal to) larger_set, false otherwise.

set_next(set: set_t) → tuple[int, int]

Fetches the next element in set that is greater than current value of codepoint.

Set codepoint to HB_SET_VALUE_INVALID to get started.

Added in version 0.9.2.

Parameters:

set – A set

Returns:

true if there was a next value, false otherwise

set_next_many(set: set_t, codepoint: int, out: Sequence[int]) → int

Finds the next element in set that is greater than codepoint. Writes out codepoints to out, until either the set runs out of elements, or size codepoints are written, whichever comes first.

Added in version 4.2.0.

Parameters:

  • set – A set

  • codepoint – Outputting codepoints starting after this one. Use HB_SET_VALUE_INVALID to get started.

  • out – An array of codepoints to write to.

Returns:

the number of values written.

set_next_range(set: set_t) → tuple[int, int, int]

Fetches the next consecutive range of elements in set that are greater than current value of last.

Set last to HB_SET_VALUE_INVALID to get started.

Added in version 0.9.7.

Parameters:

set – A set

Returns:

true if there was a next range, false otherwise

set_previous(set: set_t) → tuple[int, int]

Fetches the previous element in set that is lower than current value of codepoint.

Set codepoint to HB_SET_VALUE_INVALID to get started.

Added in version 1.8.0.

Parameters:

set – A set

Returns:

true if there was a previous value, false otherwise

set_previous_range(set: set_t) → tuple[int, int, int]

Fetches the previous consecutive range of elements in set that are greater than current value of last.

Set first to HB_SET_VALUE_INVALID to get started.

Added in version 1.8.0.

Parameters:

set – A set

Returns:

true if there was a previous range, false otherwise

set_set(set: set_t, other: set_t) → None

Makes the contents of set equal to the contents of other.

Added in version 0.9.2.

Parameters:

  • set – A set

  • other – Another set

set_subtract(set: set_t, other: set_t) → None

Subtracts the contents of other from set.

Added in version 0.9.2.

Parameters:

  • set – A set

  • other – Another set

set_symmetric_difference(set: set_t, other: set_t) → None

Makes set the symmetric difference of set and other.

Added in version 0.9.2.

Parameters:

  • set – A set

  • other – Another set

set_union(set: set_t, other: set_t) → None

Makes set the union of set and other.

Added in version 0.9.2.

Parameters:

  • set – A set

  • other – Another set

shape(font: font_t, buffer: buffer_t, features: Sequence[feature_t] | None = None) → None

Shapes buffer using font turning its Unicode characters content to positioned glyphs. If features is not NULL, it will be used to control the features applied during shaping. If two features have the same tag but overlapping ranges the value of the feature with the higher index takes precedence.

Added in version 0.9.2.

Parameters:

  • font – an font_t to use for shaping

  • buffer – an buffer_t to shape

  • features – an array of user specified feature_t or NULL

shape_full(font: font_t, buffer: buffer_t, features: Sequence[feature_t] | None = None, shaper_list: Sequence[str] | None = None) → int

See shape() for details. If shaper_list is not NULL, the specified shapers will be used in the given order, otherwise the default shapers list will be used.

Added in version 0.9.2.

Parameters:

  • font – an font_t to use for shaping

  • buffer – an buffer_t to shape

  • features – an array of user specified feature_t or NULL

  • shaper_list – a NULL-terminated array of shapers to use or NULL

Returns:

false if all shapers failed, true otherwise

shape_justify(font: font_t, buffer: buffer_t, features: Sequence[feature_t] | None, shaper_list: Sequence[str] | None, min_target_advance: float, max_target_advance: float) → tuple[int, float, int, float]

See shape_full() for basic details. If shaper_list is not NULL, the specified shapers will be used in the given order, otherwise the default shapers list will be used.

In addition, justify the shaping results such that the shaping results reach the target advance width/height, depending on the buffer direction.

If the advance of the buffer shaped with shape_full() is already known, put that in *advance. Otherwise set *advance to zero.

This API is currently experimental and will probably change in the future.

Parameters:

  • font – a mutable font_t to use for shaping

  • buffer – an buffer_t to shape

  • features – an array of user specified feature_t or NULL

  • shaper_list – a NULL-terminated array of shapers to use or NULL

  • min_target_advance – Minimum advance width/height to aim for.

  • max_target_advance – Maximum advance width/height to aim for.

Returns:

false if all shapers failed, true otherwise

XSince: EXPERIMENTAL

shape_list_shapers() → list[str]

Retrieves the list of shapers supported by HarfBuzz.

Added in version 0.9.2.

Returns:

an array of constant strings

shape_plan_create(face: face_t, props: segment_properties_t, user_features: Sequence[feature_t], shaper_list: Sequence[str]) → shape_plan_t

Constructs a shaping plan for a combination of face, user_features, props, and shaper_list.

Added in version 0.9.7.

Parameters:

  • face – face_t to use

  • props – The segment_properties_t of the segment

  • user_features – The list of user-selected features

  • shaper_list – List of shapers to try

Returns:

The shaping plan

shape_plan_create2(face: face_t, props: segment_properties_t, user_features: Sequence[feature_t], coords: Sequence[int], shaper_list: Sequence[str]) → shape_plan_t

The variable-font version of hb_shape_plan_create. Constructs a shaping plan for a combination of face, user_features, props, and shaper_list, plus the variation-space coordinates coords.

Added in version 1.4.0.

Parameters:

  • face – face_t to use

  • props – The segment_properties_t of the segment

  • user_features – The list of user-selected features

  • coords – The list of variation-space coordinates

  • shaper_list – List of shapers to try

Returns:

The shaping plan

shape_plan_create_cached(face: face_t, props: segment_properties_t, user_features: Sequence[feature_t], shaper_list: Sequence[str]) → shape_plan_t

Creates a cached shaping plan suitable for reuse, for a combination of face, user_features, props, and shaper_list.

Added in version 0.9.7.

Parameters:

  • face – face_t to use

  • props – The segment_properties_t of the segment

  • user_features – The list of user-selected features

  • shaper_list – List of shapers to try

Returns:

The shaping plan

shape_plan_create_cached2(face: face_t, props: segment_properties_t, user_features: Sequence[feature_t], coords: Sequence[int], shaper_list: Sequence[str]) → shape_plan_t

The variable-font version of hb_shape_plan_create_cached. Creates a cached shaping plan suitable for reuse, for a combination of face, user_features, props, and shaper_list, plus the variation-space coordinates coords.

Added in version 1.4.0.

Parameters:

  • face – face_t to use

  • props – The segment_properties_t of the segment

  • user_features – The list of user-selected features

  • coords – The list of variation-space coordinates

  • shaper_list – List of shapers to try

Returns:

The shaping plan

shape_plan_execute(shape_plan: shape_plan_t, font: font_t, buffer: buffer_t, features: Sequence[feature_t]) → int

Executes the given shaping plan on the specified buffer, using the given font and features.

Added in version 0.9.7.

Parameters:

  • shape_plan – A shaping plan

  • font – The font_t to use

  • buffer – The buffer_t to work upon

  • features – Features to enable

Returns:

true if success, false otherwise.

shape_plan_get_empty() → shape_plan_t

Fetches the singleton empty shaping plan.

Added in version 0.9.7.

Returns:

The empty shaping plan

shape_plan_get_shaper(shape_plan: shape_plan_t) → str

Fetches the shaper from a given shaping plan.

Added in version 0.9.7.

Parameters:

shape_plan – A shaping plan

Returns:

The shaper

style_get_value(font: font_t, style_tag: style_tag_t) → float

Searches variation axes of a font_t object for a specific axis first, if not set, then tries to get default style values from different tables of the font.

Added in version 3.0.0.

Parameters:

  • font – a font_t object.

  • style_tag – a style tag.

Returns:

Corresponding axis or default value to a style tag.

tag_from_string(str: Sequence[int]) → int

Converts a string into an tag_t. Valid tags are four characters. Shorter input strings will be padded with spaces. Longer input strings will be truncated.

Added in version 0.9.2.

Parameters:

str – String to convert

Returns:

The tag_t corresponding to str

tag_to_string(tag: int) → bytes

Converts an tag_t to a string and returns it in buf. Strings will be four characters long.

Added in version 0.9.5.

Parameters:

tag – tag_t to convert

unicode_combining_class(ufuncs: unicode_funcs_t, unicode: int) → unicode_combining_class_t

Retrieves the Canonical Combining Class (ccc) property of code point unicode.

Added in version 0.9.2.

Parameters:

  • ufuncs – The Unicode-functions structure

  • unicode – The code point to query

Returns:

The unicode_combining_class_t of unicode

unicode_compose(ufuncs: unicode_funcs_t, a: int, b: int) → tuple[int, int]

Fetches the composition of a sequence of two Unicode code points.

Calls the composition function of the specified Unicode-functions structure ufuncs.

Added in version 0.9.2.

Parameters:

  • ufuncs – The Unicode-functions structure

  • a – The first Unicode code point to compose

  • b – The second Unicode code point to compose

Returns:

true if a and b composed, false otherwise

unicode_decompose(ufuncs: unicode_funcs_t, ab: int) → tuple[int, int, int]

Fetches the decomposition of a Unicode code point.

Calls the decomposition function of the specified Unicode-functions structure ufuncs.

Added in version 0.9.2.

Parameters:

  • ufuncs – The Unicode-functions structure

  • ab – Unicode code point to decompose

Returns:

true if ab was decomposed, false otherwise

unicode_decompose_compatibility(ufuncs: unicode_funcs_t, u: int) → tuple[int, int]

Fetches the compatibility decomposition of a Unicode code point. Deprecated.

Added in version 0.9.2.

Deprecated since version 2.0.0: Please do not use it in newly written code

Parameters:

  • ufuncs – The Unicode-functions structure

  • u – Code point to decompose

Returns:

length of decomposed.

unicode_eastasian_width(ufuncs: unicode_funcs_t, unicode: int) → int

Don’t use. Not used by HarfBuzz.

Added in version 0.9.2.

Deprecated since version 2.0.0: Please do not use it in newly written code

Parameters:

  • ufuncs – a Unicode-function structure

  • unicode – The code point to query

unicode_funcs_create(parent: unicode_funcs_t | None = None) → unicode_funcs_t

Creates a new unicode_funcs_t structure of Unicode functions.

Added in version 0.9.2.

Parameters:

parent – Parent Unicode-functions structure

Returns:

The Unicode-functions structure

unicode_funcs_get_default() → unicode_funcs_t

Fetches a pointer to the default Unicode-functions structure that is used when no functions are explicitly set on buffer_t.

Added in version 0.9.2.

Returns:

a pointer to the unicode_funcs_t Unicode-functions structure

unicode_funcs_get_empty() → unicode_funcs_t

Fetches the singleton empty Unicode-functions structure.

Added in version 0.9.2.

Returns:

The empty Unicode-functions structure

unicode_funcs_get_parent(ufuncs: unicode_funcs_t) → unicode_funcs_t

Fetches the parent of the Unicode-functions structure ufuncs.

Added in version 0.9.2.

Parameters:

ufuncs – The Unicode-functions structure

Returns:

The parent Unicode-functions structure

unicode_funcs_is_immutable(ufuncs: unicode_funcs_t) → int

Tests whether the specified Unicode-functions structure is immutable.

Added in version 0.9.2.

Parameters:

ufuncs – The Unicode-functions structure

Returns:

true if ufuncs is immutable, false otherwise

unicode_funcs_make_immutable(ufuncs: unicode_funcs_t) → None

Makes the specified Unicode-functions structure immutable.

Added in version 0.9.2.

Parameters:

ufuncs – The Unicode-functions structure

unicode_funcs_set_combining_class_func(ufuncs: unicode_funcs_t, func: Callable[[...], unicode_combining_class_t], *user_data: Any) → None

Sets the implementation function for unicode_combining_class_func_t.

Added in version 0.9.2.

Parameters:

  • ufuncs – A Unicode-functions structure

  • func – The callback function to assign

  • user_data – Data to pass to func

unicode_funcs_set_compose_func(ufuncs: unicode_funcs_t, func: Callable[[...], tuple[int, int]], *user_data: Any) → None

Sets the implementation function for unicode_compose_func_t.

Added in version 0.9.2.

Parameters:

  • ufuncs – A Unicode-functions structure

  • func – The callback function to assign

  • user_data – Data to pass to func

unicode_funcs_set_decompose_compatibility_func(ufuncs: unicode_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for unicode_decompose_compatibility_func_t.

Added in version 0.9.2.

Deprecated since version 2.0.0: Please do not use it in newly written code

Parameters:

  • ufuncs – A Unicode-functions structure

  • func – The callback function to assign

  • user_data – Data to pass to func

unicode_funcs_set_decompose_func(ufuncs: unicode_funcs_t, func: Callable[[...], tuple[int, int, int]], *user_data: Any) → None

Sets the implementation function for unicode_decompose_func_t.

Added in version 0.9.2.

Parameters:

  • ufuncs – A Unicode-functions structure

  • func – The callback function to assign

  • user_data – Data to pass to func

unicode_funcs_set_eastasian_width_func(ufuncs: unicode_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for unicode_eastasian_width_func_t.

Added in version 0.9.2.

Deprecated since version 2.0.0: Please do not use it in newly written code

Parameters:

  • ufuncs – a Unicode-function structure

  • func – The callback function to assign

  • user_data – Data to pass to func

unicode_funcs_set_general_category_func(ufuncs: unicode_funcs_t, func: Callable[[...], unicode_general_category_t], *user_data: Any) → None

Sets the implementation function for unicode_general_category_func_t.

Added in version 0.9.2.

Parameters:

  • ufuncs – A Unicode-functions structure

  • func – The callback function to assign

  • user_data – Data to pass to func

unicode_funcs_set_mirroring_func(ufuncs: unicode_funcs_t, func: Callable[[...], int], *user_data: Any) → None

Sets the implementation function for unicode_mirroring_func_t.

Added in version 0.9.2.

Parameters:

  • ufuncs – A Unicode-functions structure

  • func – The callback function to assign

  • user_data – Data to pass to func

unicode_funcs_set_script_func(ufuncs: unicode_funcs_t, func: Callable[[...], script_t], *user_data: Any) → None

Sets the implementation function for unicode_script_func_t.

Added in version 0.9.2.

Parameters:

  • ufuncs – A Unicode-functions structure

  • func – The callback function to assign

  • user_data – Data to pass to func

unicode_general_category(ufuncs: unicode_funcs_t, unicode: int) → unicode_general_category_t

Retrieves the General Category (gc) property of code point unicode.

Added in version 0.9.2.

Parameters:

  • ufuncs – The Unicode-functions structure

  • unicode – The code point to query

Returns:

The unicode_general_category_t of unicode

unicode_mirroring(ufuncs: unicode_funcs_t, unicode: int) → int

Retrieves the Bi-directional Mirroring Glyph code point defined for code point unicode.

Added in version 0.9.2.

Parameters:

  • ufuncs – The Unicode-functions structure

  • unicode – The code point to query

Returns:

The codepoint_t of the Mirroring Glyph for unicode

unicode_script(ufuncs: unicode_funcs_t, unicode: int) → script_t

Retrieves the script_t script to which code point unicode belongs.

Added in version 0.9.2.

Parameters:

  • ufuncs – The Unicode-functions structure

  • unicode – The code point to query

Returns:

The script_t of unicode

variation_from_string(str: Sequence[int]) → tuple[int, variation_t]

Parses a string into a variation_t.

The format for specifying variation settings follows. All valid CSS font-variation-settings values other than ‘normal’ and ‘inherited’ are also accepted, though, not documented below.

The format is a tag, optionally followed by an equals sign, followed by a number. For example wght=500, or slnt=-7.5.

Added in version 1.4.2.

Parameters:

str – a string to parse

Returns:

true if str is successfully parsed, false otherwise

variation_to_string(variation: variation_t) → list[str]

Converts an variation_t into a NULL-terminated string in the format understood by variation_from_string(). The client in responsible for allocating big enough size for buf, 128 bytes is more than enough.

Added in version 1.4.2.

Parameters:

variation – an variation_t to convert

version() → tuple[int, int, int]

Returns library version as three integer components.

Added in version 0.9.2.

version_atleast(major: int, minor: int, micro: int) → int

Tests the library version against a minimum value, as three integer components.

Added in version 0.9.30.

Parameters:

  • major – Library major version component

  • minor – Library minor version component

  • micro – Library micro version component

Returns:

true if the library is equal to or greater than the test value, false otherwise

version_string() → str

Returns library version as a string with three components.

Added in version 0.9.2.

Returns:

Library version string