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:

face – face_t to work upon
feature_type – The aat_layout_feature_type_t of the requested feature type

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.

The filename is passed directly to the system on all platforms, except on Windows, where the filename is interpreted as UTF-8. Only if the filename is not valid UTF-8, it will be interpreted according to the system codepage.

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:

buffer – an buffer_t buffer.
buf – string to deserialize
font – font for getting glyph IDs
format – the buffer_serialize_format_t of the input buf

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:

buffer – an buffer_t buffer.
buf – string to deserialize
format – the buffer_serialize_format_t of the input buf

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_random_state(buffer: buffer_t) → int

See buffer_set_random_state().

Added in version 8.4.0.

Parameters:: buffer – An buffer_t
Returns:: The buffer random state

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 both glyph_position_t.x_offset and glyph_position_t.y_offset are not 0, `x_offset,y_offset`. Then,
- +x_advance, then ,y_advance if glyph_position_t.y_advance is not 0. Then,
- 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:

g: the glyph name or glyph index if HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES flag is set.
cl: glyph_info_t.cluster if HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set.
dx,``dy``,``ax``,``ay``: glyph_position_t.x_offset, glyph_position_t.y_offset,
glyph_position_t.x_advance and glyph_position_t.y_advance respectively, if HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set.
xb,``yb``,``w``,``h``: glyph_extents_t.x_bearing, glyph_extents_t.y_bearing,
glyph_extents_t.width and glyph_extents_t.height respectively if HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set.

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:

A newly created buffer starts with content type INVALID. Calling buffer_reset(), buffer_clear_contents(), as well as calling buffer_set_length() with an argument of zero all set the buffer content type to invalid as well.
Calling buffer_add_utf8(), buffer_add_utf16(), buffer_add_utf32(), buffer_add_codepoints() and buffer_add_latin1() expect that buffer is either empty and have a content type of invalid, or that buffer content type is UNICODE, and they also set the content type to Unicode if they added anything to an empty buffer.
Finally shape() and shape_full() expect that the buffer is either empty and have content type of invalid, or that buffer content type is UNICODE, and upon success they set the buffer content type to GLYPHS.

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 – An buffer_t
direction – the direction_t of the buffer

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_random_state(buffer: buffer_t, state: int) → None

Sets the random state of the buffer. The state changes every time a glyph uses randomness (eg. the rand OpenType feature). This function together with buffer_get_random_state() allow for transferring the current random state to a subsequent buffer, to get better randomness distribution.

Defaults to 1 and when buffer contents are cleared. A value of 0 disables randomness during shaping.

Added in version 8.4.0.

Parameters:

buffer – An buffer_t
state – the new random state

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 – An buffer_t
script – An script_t to set.

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 – An buffer_t
props – An segment_properties_t to use

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.

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.

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:

language – The language_t to work on
specific – Another language_t

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.

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:

face – The face_t to work on
klass – The ot_layout_glyph_class_t GDEF class to retrieve

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:

font – font_t to work upon
constant – ot_math_constant_t the constant to retrieve

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.

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.

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:

script – an script_t to convert.
language – an language_t to convert.

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:

use ot_var_find_axis_info() instead

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:

a – first segment_properties_t to compare.
b – second segment_properties_t to compare.

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:

p – segment_properties_t to fill in.
src – segment_properties_t to fill in from.

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