## hb-buffer

hb-buffer — Input and output buffers

## Functions

hb_buffer_t * | hb_buffer_create ()
hb_buffer_t * | hb_buffer_reference ()
hb_buffer_t * | hb_buffer_get_empty ()
void | hb_buffer_destroy ()
void | hb_buffer_reset ()
void | hb_buffer_clear_contents ()
hb_bool_t | hb_buffer_pre_allocate ()
hb_bool_t | hb_buffer_allocation_successful ()
void | hb_buffer_add ()
void | hb_buffer_add_codepoints ()
void | hb_buffer_add_utf32 ()
void | hb_buffer_add_utf16 ()
void | hb_buffer_add_utf8 ()
void | hb_buffer_add_latin1 ()
void | hb_buffer_append ()
void | hb_buffer_set_content_type ()
hb_buffer_content_type_t | hb_buffer_get_content_type ()
void | hb_buffer_set_direction ()
hb_direction_t | hb_buffer_get_direction ()
void | hb_buffer_set_script ()
hb_script_t | hb_buffer_get_script ()
void | hb_buffer_set_language ()
hb_language_t | hb_buffer_get_language ()
void | hb_buffer_set_flags ()
hb_buffer_flags_t | hb_buffer_get_flags ()
void | hb_buffer_set_cluster_level ()
hb_buffer_cluster_level_t | hb_buffer_get_cluster_level ()
hb_bool_t | hb_buffer_set_length ()
unsigned int | hb_buffer_get_length ()
void | hb_buffer_set_segment_properties ()
void | hb_buffer_get_segment_properties ()
void | hb_buffer_guess_segment_properties ()
void | hb_buffer_set_unicode_funcs ()
hb_unicode_funcs_t * | hb_buffer_get_unicode_funcs ()
hb_bool_t | hb_buffer_set_user_data ()
void * | hb_buffer_get_user_data ()
hb_glyph_info_t * | hb_buffer_get_glyph_infos ()
hb_glyph_position_t * | hb_buffer_get_glyph_positions ()
hb_bool_t | hb_buffer_has_positions ()
hb_codepoint_t | hb_buffer_get_invisible_glyph ()
void | hb_buffer_set_invisible_glyph ()
void | hb_buffer_set_replacement_codepoint ()
hb_codepoint_t | hb_buffer_get_replacement_codepoint ()
void | hb_buffer_normalize_glyphs ()
void | hb_buffer_reverse ()
void | hb_buffer_reverse_range ()
void | hb_buffer_reverse_clusters ()
unsigned int | hb_buffer_serialize ()
unsigned int | hb_buffer_serialize_glyphs ()
hb_bool_t | hb_buffer_deserialize_glyphs ()
unsigned int | hb_buffer_serialize_unicode ()
hb_bool_t | hb_buffer_deserialize_unicode ()
hb_buffer_serialize_format_t | hb_buffer_serialize_format_from_string ()
const char * | hb_buffer_serialize_format_to_string ()
const char ** | hb_buffer_serialize_list_formats ()
hb_bool_t | hb_segment_properties_equal ()
unsigned int | hb_segment_properties_hash ()
hb_buffer_diff_flags_t | hb_buffer_diff ()
void | hb_buffer_set_message_func ()
hb_glyph_flags_t | hb_glyph_info_get_glyph_flags ()
hb_bool_t | (*hb_buffer_message_func_t) ()

## Types and Values

#define | HB_SEGMENT_PROPERTIES_DEFAULT
#define | HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT
typedef | hb_buffer_t
| hb_glyph_info_t
enum | hb_glyph_flags_t
| hb_glyph_position_t
enum | hb_buffer_content_type_t
enum | hb_buffer_flags_t
enum | hb_buffer_cluster_level_t
| hb_segment_properties_t
enum | hb_buffer_serialize_format_t
enum | hb_buffer_serialize_flags_t
enum | hb_buffer_diff_flags_t

## Includes

    #include <hb.h>

## Description

Buffers serve a dual role in HarfBuzz; before shaping, they hold the input characters that are passed to `hb_shape()`, and after shaping they hold the output glyphs.

## Functions

### hb_buffer_create ()

    hb_buffer_t *
    hb_buffer_create (void);

Creates a new hb_buffer_t with all properties to defaults.

[Xconstructor]

#### Returns

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

[transfer full]

Since: 0.9.2

### hb_buffer_reference ()

    hb_buffer_t *
    hb_buffer_reference (hb_buffer_t *buffer);

Increases the reference count on `buffer` by one. This prevents `buffer` from being destroyed until a matching call to `hb_buffer_destroy()` is made.

[skip]

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The referenced hb_buffer_t.

[transfer full]

Since: 0.9.2

### hb_buffer_get_empty ()

    hb_buffer_t *
    hb_buffer_get_empty (void);

Fetches an empty hb_buffer_t.

#### Returns

The empty buffer.

[transfer full]

Since: 0.9.2

### hb_buffer_destroy ()

    void
    hb_buffer_destroy (hb_buffer_t *buffer);

Deallocate the `buffer` . Decreases the reference count on `buffer` by one. If the result is zero, then `buffer` and all associated resources are freed. See `hb_buffer_reference()`.

[skip]

#### Parameters

buffer | An hb_buffer_t |

Since: 0.9.2

### hb_buffer_reset ()

    void
    hb_buffer_reset (hb_buffer_t *buffer);

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

#### Parameters

buffer | An hb_buffer_t |

Since: 0.9.2

### hb_buffer_clear_contents ()

    void
    hb_buffer_clear_contents (hb_buffer_t *buffer);

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

#### Parameters

buffer | An hb_buffer_t |

Since: 0.9.11

### hb_buffer_pre_allocate ()

    hb_bool_t
    hb_buffer_pre_allocate (hb_buffer_t *buffer,
                            unsigned int size);

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

#### Parameters

buffer | An hb_buffer_t |
size | Number of items to pre allocate. |

#### Returns

`true` if `buffer` memory allocation succeeded, `false` otherwise

Since: 0.9.2

### hb_buffer_allocation_successful ()

    hb_bool_t
    hb_buffer_allocation_successful (hb_buffer_t *buffer);

Check if allocating memory for the buffer succeeded.

#### Parameters

buffer | An hb_buffer_t |

#### Returns

`true` if `buffer` memory allocation succeeded, `false` otherwise.

Since: 0.9.2

### hb_buffer_add ()

    void
    hb_buffer_add (hb_buffer_t *buffer,
                   hb_codepoint_t codepoint,
                   unsigned int cluster);

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

#### Parameters

buffer | An hb_buffer_t |
codepoint | A Unicode code point. |
cluster | The cluster value of `codepoint` . |

Since: 0.9.7

### hb_buffer_add_codepoints ()

    void
    hb_buffer_add_codepoints (hb_buffer_t *buffer,
                              const hb_codepoint_t *text,
                              int text_length,
                              unsigned int item_offset,
                              int item_length);

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 code points.

#### Parameters

buffer | a hb_buffer_t to append characters to. |
text | an array of Unicode code points to append. | [array length=text_length]
text_length | the length of the `text` , or -1 if it is `NULL` terminated. |
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). |

Since: 0.9.31

### hb_buffer_add_utf32 ()

    void
    hb_buffer_add_utf32 (hb_buffer_t *buffer,
                         const uint32_t *text,
                         int text_length,
                         unsigned int item_offset,
                         int item_length);

See `hb_buffer_add_codepoints()`.

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

#### Parameters

buffer | An hb_buffer_t |
text | An array of UTF-32 characters to append. | [array length=text_length]
text_length | The length of the `text` , or -1 if it is `NULL` terminated |
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) |

Since: 0.9.2

### hb_buffer_add_utf16 ()

    void
    hb_buffer_add_utf16 (hb_buffer_t *buffer,
                         const uint16_t *text,
                         int text_length,
                         unsigned int item_offset,
                         int item_length);

See `hb_buffer_add_codepoints()`.

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

#### Parameters

buffer | An hb_buffer_t |
text | An array of UTF-16 characters to append. | [array length=text_length]
text_length | The length of the `text` , or -1 if it is `NULL` terminated |
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) |

Since: 0.9.2

### hb_buffer_add_utf8 ()

    void
    hb_buffer_add_utf8 (hb_buffer_t *buffer,
                        const char *text,
                        int text_length,
                        unsigned int item_offset,
                        int item_length);

See `hb_buffer_add_codepoints()`.

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

#### Parameters

buffer | An hb_buffer_t |
text | An array of UTF-8 characters to append. | [array length=text_length][element-type uint8_t]
text_length | The length of the `text` , or -1 if it is `NULL` terminated. |
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). |

Since: 0.9.2

### hb_buffer_add_latin1 ()

    void
    hb_buffer_add_latin1 (hb_buffer_t *buffer,
                          const uint8_t *text,
                          int text_length,
                          unsigned int item_offset,
                          int item_length);

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

Has nothing to do with non-Unicode Latin-1 encoding.

#### Parameters

buffer | An hb_buffer_t |
text | an array of UTF-8 characters to append. | [array length=text_length][element-type uint8_t]
text_length | the length of the `text` , or -1 if it is `NULL` terminated |
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) |

Since: 0.9.39

### hb_buffer_append ()

    void
    hb_buffer_append (hb_buffer_t *buffer,
                      hb_buffer_t *source,
                      unsigned int start,
                      unsigned int end);

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

#### Parameters

buffer | An hb_buffer_t |
source | source hb_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. |

Since: 1.5.0

### hb_buffer_set_content_type ()

    void
    hb_buffer_set_content_type (hb_buffer_t *buffer,
                                hb_buffer_content_type_t content_type);

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

#### Parameters

buffer | An hb_buffer_t |
content_type | The type of buffer contents to set |

Since: 0.9.5

### hb_buffer_get_content_type ()

    hb_buffer_content_type_t
    hb_buffer_get_content_type (hb_buffer_t *buffer);

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

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The type of `buffer` contents

Since: 0.9.5

### hb_buffer_set_direction ()

    void
    hb_buffer_set_direction (hb_buffer_t *buffer,
                             hb_direction_t direction);

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.

#### Parameters

buffer | An hb_buffer_t |
direction | the hb_direction_t of the `buffer` |

Since: 0.9.2

### hb_buffer_get_direction ()

    hb_direction_t
    hb_buffer_get_direction (hb_buffer_t *buffer);

See `hb_buffer_set_direction()`

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The direction of the `buffer` .

Since: 0.9.2

### hb_buffer_set_script ()

    void
    hb_buffer_set_script (hb_buffer_t *buffer,
                          hb_script_t script);

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 hb_script_t values, or use `hb_script_from_string()` or `hb_script_from_iso15924_tag()` to get the corresponding script from an ISO 15924 script tag.

#### Parameters

buffer | An hb_buffer_t |
script | An hb_script_t to set. |

Since: 0.9.2

### hb_buffer_get_script ()

    hb_script_t
    hb_buffer_get_script (hb_buffer_t *buffer);

Fetches the script of `buffer` .

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The hb_script_t of the `buffer`

Since: 0.9.2

### hb_buffer_set_language ()

    void
    hb_buffer_set_language (hb_buffer_t *buffer,
                            hb_language_t language);

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 `hb_language_from_string()` to convert from BCP 47 language tags to hb_language_t.

#### Parameters

buffer | An hb_buffer_t |
language | An hb_language_t to set |

Since: 0.9.2

### hb_buffer_get_language ()

    hb_language_t
    hb_buffer_get_language (hb_buffer_t *buffer);

See `hb_buffer_set_language()`.

#### Parameters

buffer | An hb_buffer_t |

#### Returns

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

[transfer none]

Since: 0.9.2

### hb_buffer_set_flags ()

    void
    hb_buffer_set_flags (hb_buffer_t *buffer,
                         hb_buffer_flags_t flags);

Sets `buffer` flags to `flags` . See hb_buffer_flags_t.

#### Parameters

buffer | An hb_buffer_t |
flags | The buffer flags to set |

Since: 0.9.7

### hb_buffer_get_flags ()

    hb_buffer_flags_t
    hb_buffer_get_flags (hb_buffer_t *buffer);

Fetches the hb_buffer_flags_t of `buffer` .

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The `buffer` flags

Since: 0.9.7

### hb_buffer_set_cluster_level ()

    void
    hb_buffer_set_cluster_level (hb_buffer_t *buffer,
                                 hb_buffer_cluster_level_t cluster_level);

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

#### Parameters

buffer | An hb_buffer_t |
cluster_level | The cluster level to set on the buffer |

Since: 0.9.42

### hb_buffer_get_cluster_level ()

    hb_buffer_cluster_level_t
    hb_buffer_get_cluster_level (hb_buffer_t *buffer);

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

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The cluster level of `buffer`

Since: 0.9.42

### hb_buffer_set_length ()

    hb_bool_t
    hb_buffer_set_length (hb_buffer_t *buffer,
                          unsigned int length);

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

#### Parameters

buffer | An hb_buffer_t |
length | The new length of `buffer` |

#### Returns

`true` if `buffer` memory allocation succeeded, `false` otherwise.

Since: 0.9.2

### hb_buffer_get_length ()

    unsigned int
    hb_buffer_get_length (hb_buffer_t *buffer);

Returns the number of items in the buffer.

#### Parameters

buffer | An hb_buffer_t |

#### Returns

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

Since: 0.9.2

### hb_buffer_set_segment_properties ()

    void
    hb_buffer_set_segment_properties (hb_buffer_t *buffer,
                                      const hb_segment_properties_t *props);

Sets the segment properties of the buffer, a shortcut for calling `hb_buffer_set_direction()`, `hb_buffer_set_script()` and `hb_buffer_set_language()` individually.

#### Parameters

buffer | An hb_buffer_t |
props | An hb_segment_properties_t to use |

Since: 0.9.7

### hb_buffer_get_segment_properties ()

    void
    hb_buffer_get_segment_properties (hb_buffer_t *buffer,
                                      hb_segment_properties_t *props);

Sets `props` to the hb_segment_properties_t of `buffer` .

#### Parameters

buffer | An hb_buffer_t |
props | The output hb_segment_properties_t. | [out]

Since: 0.9.7

### hb_buffer_guess_segment_properties ()

    void
    hb_buffer_guess_segment_properties (hb_buffer_t *buffer);

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 `hb_script_get_horizontal_direction()`. If `hb_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 `hb_language_get_default()`. This may change in the future by taking buffer script into consideration when choosing a language. Note that `hb_language_get_default()` is NOT threadsafe the first time it is called. See documentation for that function for details.

#### Parameters

buffer | An hb_buffer_t |

Since: 0.9.7

### hb_buffer_set_unicode_funcs ()

    void
    hb_buffer_set_unicode_funcs (hb_buffer_t *buffer,
                                 hb_unicode_funcs_t *unicode_funcs);

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

#### Parameters

buffer | An hb_buffer_t |
unicode_funcs | The Unicode-functions structure |

Since: 0.9.2

### hb_buffer_get_unicode_funcs ()

    hb_unicode_funcs_t *
    hb_buffer_get_unicode_funcs (hb_buffer_t *buffer);

Fetches the Unicode-functions structure of a buffer.

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The Unicode-functions structure

Since: 0.9.2

### hb_buffer_set_user_data ()

    hb_bool_t
    hb_buffer_set_user_data (hb_buffer_t *buffer,
                             hb_user_data_key_t *key,
                             void *data,
                             hb_destroy_func_t destroy,
                             hb_bool_t replace);

Attaches a user-data key/data pair to the specified buffer.

[skip]

#### Parameters

buffer | An hb_buffer_t |
key | The user-data key |
data | A pointer to the user data |
destroy | A callback to call when `data` is not needed anymore. | [nullable]
replace | Whether to replace an existing data with the same key |

#### Returns

`true` if success, `false` otherwise

Since: 0.9.2

### hb_buffer_get_user_data ()

    void *
    hb_buffer_get_user_data (hb_buffer_t *buffer,
                             hb_user_data_key_t *key);

Fetches the user data associated with the specified key, attached to the specified buffer.

[skip]

#### Parameters

buffer | An hb_buffer_t |
key | The user-data key to query |

#### Returns

A pointer to the user data.

[transfer none]

Since: 0.9.2

### hb_buffer_get_glyph_infos ()

    hb_glyph_info_t *
    hb_buffer_get_glyph_infos (hb_buffer_t *buffer,
                               unsigned int *length);

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

#### Parameters

buffer | An hb_buffer_t |
length | The output-array length. | [out]

#### Returns

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

[transfer none][array length=length]

Since: 0.9.2

### hb_buffer_get_glyph_positions ()

    hb_glyph_position_t *
    hb_buffer_get_glyph_positions (hb_buffer_t *buffer,
                                   unsigned int *length);

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

#### Parameters

buffer | An hb_buffer_t |
length | The output length. | [out]

#### Returns

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

[transfer none][array length=length]

Since: 0.9.2

### hb_buffer_has_positions ()

    hb_bool_t
    hb_buffer_has_positions (hb_buffer_t *buffer);

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

#### Parameters

buffer | an hb_buffer_t. |

#### Returns

`true` if the `buffer` has position array, `false` otherwise.

Since: 2.7.3

### hb_buffer_get_invisible_glyph ()

    hb_codepoint_t
    hb_buffer_get_invisible_glyph (hb_buffer_t *buffer);

See `hb_buffer_set_invisible_glyph()`.

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The `buffer` invisible hb_codepoint_t

Since: 2.0.0

### hb_buffer_set_invisible_glyph ()

    void
    hb_buffer_set_invisible_glyph (hb_buffer_t *buffer,
                                   hb_codepoint_t invisible);

Sets the hb_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.

#### Parameters

buffer | An hb_buffer_t |
invisible | the invisible hb_codepoint_t |

Since: 2.0.0

### hb_buffer_set_replacement_codepoint ()

    void
    hb_buffer_set_replacement_codepoint (hb_buffer_t *buffer,
                                         hb_codepoint_t replacement);

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

Default is HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT.

#### Parameters

buffer | An hb_buffer_t |
replacement | the replacement hb_codepoint_t |

Since: 0.9.31

### hb_buffer_get_replacement_codepoint ()

    hb_codepoint_t
    hb_buffer_get_replacement_codepoint (hb_buffer_t *buffer);

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

#### Parameters

buffer | An hb_buffer_t |

#### Returns

The `buffer` replacement hb_codepoint_t

Since: 0.9.31

### hb_buffer_normalize_glyphs ()

    void
    hb_buffer_normalize_glyphs (hb_buffer_t *buffer);

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

This has nothing to do with Unicode normalization.

#### Parameters

buffer | An hb_buffer_t |

Since: 0.9.2

### hb_buffer_reverse ()

    void
    hb_buffer_reverse (hb_buffer_t *buffer);

Reverses buffer contents.

#### Parameters

buffer | An hb_buffer_t |

Since: 0.9.2

### hb_buffer_reverse_range ()

    void
    hb_buffer_reverse_range (hb_buffer_t *buffer,
                             unsigned int start,
                             unsigned int end);

Reverses buffer contents between `start` and `end` .

#### Parameters

buffer | An hb_buffer_t |
start | start index |
end | end index |

Since: 0.9.41

### hb_buffer_reverse_clusters ()

    void
    hb_buffer_reverse_clusters (hb_buffer_t *buffer);

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

#### Parameters

buffer | An hb_buffer_t |

Since: 0.9.2

### hb_buffer_serialize ()

    unsigned int
    hb_buffer_serialize (hb_buffer_t *buffer,
                         unsigned int start,
                         unsigned int end,
                         char *buf,
                         unsigned int buf_size,
                         unsigned int *buf_consumed,
                         hb_font_t *font,
                         hb_buffer_serialize_format_t format,
                         hb_buffer_serialize_flags_t flags);

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 `hb_buffer_serialize_unicode()` and `hb_buffer_serialize_glyphs()` for a description of the output format.

#### Parameters

buffer | an hb_buffer_t buffer. |
start | the first item in `buffer` to serialize. |
end | the last item in `buffer` to serialize. |
buf | output string to write serialized buffer into. | [out][array length=buf_size][element-type uint8_t]
buf_size | the size of `buf` . |
buf_consumed | if not `NULL`, will be set to the number of byes written into `buf` . | [out][optional]
font | the hb_font_t used to shape this buffer, needed to read glyph names and extents. If `NULL`, and empty font will be used. | [nullable]
format | the hb_buffer_serialize_format_t to use for formatting the output. |
flags | the hb_buffer_serialize_flags_t that control what glyph properties to serialize. |

#### Returns

The number of serialized items.

Since: 2.7.3

### hb_buffer_serialize_glyphs ()

    unsigned int
    hb_buffer_serialize_glyphs (hb_buffer_t *buffer,
                                unsigned int start,
                                unsigned int end,
                                char *buf,
                                unsigned int buf_size,
                                unsigned int *buf_consumed,
                                hb_font_t *font,
                                hb_buffer_serialize_format_t format,
                                hb_buffer_serialize_flags_t flags);

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 hb_glyph_info_t.cluster.

  - If HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set, the hb_glyph_position_t in the format:

    - If both hb_glyph_position_t.x_offset and hb_glyph_position_t.y_offset are not 0, `@x_offset,y_offset`. Then,

    - `+x_advance`, then `,y_advance` if hb_glyph_position_t.y_advance is not 0. Then,

  - If HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set, the hb_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`: hb_glyph_info_t.cluster if HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set.

- `dx`,`dy`,`ax`,`ay`: hb_glyph_position_t.x_offset, hb_glyph_position_t.y_offset, hb_glyph_position_t.x_advance and hb_glyph_position_t.y_advance respectively, if HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set.

- `xb`,`yb`,`w`,`h`: hb_glyph_extents_t.x_bearing, hb_glyph_extents_t.y_bearing, hb_glyph_extents_t.width and hb_glyph_extents_t.height respectively if HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set.

#### Parameters

buffer | an hb_buffer_t buffer. |
start | the first item in `buffer` to serialize. |
end | the last item in `buffer` to serialize. |
buf | output string to write serialized buffer into. | [out][array length=buf_size][element-type uint8_t]
buf_size | the size of `buf` . |
buf_consumed | if not `NULL`, will be set to the number of byes written into `buf` . | [out][optional]
font | the hb_font_t used to shape this buffer, needed to read glyph names and extents. If `NULL`, and empty font will be used. | [nullable]
format | the hb_buffer_serialize_format_t to use for formatting the output. |
flags | the hb_buffer_serialize_flags_t that control what glyph properties to serialize. |

#### Returns

The number of serialized items.

Since: 0.9.7

### hb_buffer_deserialize_glyphs ()

    hb_bool_t
    hb_buffer_deserialize_glyphs (hb_buffer_t *buffer,
                                  const char *buf,
                                  int buf_len,
                                  const char **end_ptr,
                                  hb_font_t *font,
                                  hb_buffer_serialize_format_t format);

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

#### Parameters

buffer | an hb_buffer_t buffer. |
buf | string to deserialize. | [array length=buf_len]
buf_len | the size of `buf` , or -1 if it is `NULL`-terminated |
end_ptr | output pointer to the character after last consumed one. | [out][optional]
font | font for getting glyph IDs. | [nullable]
format | the hb_buffer_serialize_format_t of the input `buf` |

#### Returns

`true` if `buf` is not fully consumed, `false` otherwise.

Since: 0.9.7

### hb_buffer_serialize_unicode ()

    unsigned int
    hb_buffer_serialize_unicode (hb_buffer_t *buffer,
                                 unsigned int start,
                                 unsigned int end,
                                 char *buf,
                                 unsigned int buf_size,
                                 unsigned int *buf_consumed,
                                 hb_buffer_serialize_format_t format,
                                 hb_buffer_serialize_flags_t flags);

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 hb_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`: hb_glyph_info_t.cluster if HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set.

For example:

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

#### Parameters

buffer | an hb_buffer_t buffer. |
start | the first item in `buffer` to serialize. |
end | the last item in `buffer` to serialize. |
buf | output string to write serialized buffer into. | [out][array length=buf_size][element-type uint8_t]
buf_size | the size of `buf` . |
buf_consumed | if not `NULL`, will be set to the number of byes written into `buf` . | [out][optional]
format | the hb_buffer_serialize_format_t to use for formatting the output. |
flags | the hb_buffer_serialize_flags_t that control what glyph properties to serialize. |

#### Returns

The number of serialized items.

Since: 2.7.3

### hb_buffer_deserialize_unicode ()

    hb_bool_t
    hb_buffer_deserialize_unicode (hb_buffer_t *buffer,
                                   const char *buf,
                                   int buf_len,
                                   const char **end_ptr,
                                   hb_buffer_serialize_format_t format);

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

#### Parameters

buffer | an hb_buffer_t buffer. |
buf | string to deserialize. | [array length=buf_len]
buf_len | the size of `buf` , or -1 if it is `NULL`-terminated |
end_ptr | output pointer to the character after last consumed one. | [out][optional]
format | the hb_buffer_serialize_format_t of the input `buf` |

#### Returns

`true` if `buf` is not fully consumed, `false` otherwise.

Since: 2.7.3

### hb_buffer_serialize_format_from_string ()

    hb_buffer_serialize_format_t
    hb_buffer_serialize_format_from_string
                                   (const char *str,
                                    int len);

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

#### Parameters

str | a string to parse. | [array length=len][element-type uint8_t]
len | length of `str` , or -1 if string is `NULL` terminated |

#### Returns

The parsed hb_buffer_serialize_format_t.

Since: 0.9.7

### hb_buffer_serialize_format_to_string ()

    const char *
    hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format);

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

#### Parameters

format | an hb_buffer_serialize_format_t to convert. |

#### Returns

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

[transfer none]

Since: 0.9.7

### hb_buffer_serialize_list_formats ()

    const char **
    hb_buffer_serialize_list_formats (void);

Returns a list of supported buffer serialization formats.

#### Returns

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

[transfer none]

Since: 0.9.7

### hb_segment_properties_equal ()

    hb_bool_t
    hb_segment_properties_equal (const hb_segment_properties_t *a,
                                 const hb_segment_properties_t *b);

Checks the equality of two hb_segment_properties_t's.

#### Parameters

a | first hb_segment_properties_t to compare. |
b | second hb_segment_properties_t to compare. |

#### Returns

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

Since: 0.9.7

### hb_segment_properties_hash ()

    unsigned int
    hb_segment_properties_hash (const hb_segment_properties_t *p);

Creates a hash representing `p` .

#### Parameters

p | hb_segment_properties_t to hash. |

#### Returns

A hash of `p` .

Since: 0.9.7

### hb_buffer_diff ()

    hb_buffer_diff_flags_t
    hb_buffer_diff (hb_buffer_t *buffer,
                    hb_buffer_t *reference,
                    hb_codepoint_t dottedcircle_glyph,
                    unsigned int position_fuzz);

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.

#### Parameters

buffer | a buffer. |
reference | other buffer to compare to. |
dottedcircle_glyph | glyph id of U+25CC DOTTED CIRCLE, or (hb_codepont_t) -1. |
position_fuzz | allowed absolute difference in position values. |

Since: 1.5.0

### hb_buffer_set_message_func ()

    void
    hb_buffer_set_message_func (hb_buffer_t *buffer,
                                hb_buffer_message_func_t func,
                                void *user_data,
                                hb_destroy_func_t destroy);

Sets the implementation function for hb_buffer_message_func_t.

#### Parameters

buffer | An hb_buffer_t |
func | Callback function. | [closure user_data][destroy destroy][scope notified]
user_data | Data to pass to `func` . | [nullable]
destroy | The function to call when `user_data` is not needed anymore. | [nullable]

Since: 1.1.3

### hb_glyph_info_get_glyph_flags ()

    hb_glyph_flags_t
    hb_glyph_info_get_glyph_flags (const hb_glyph_info_t *info);

Returns glyph flags encoded within a hb_glyph_info_t.

#### Parameters

info | a hb_glyph_info_t |

#### Returns

The hb_glyph_flags_t encoded within `info`

Since: 1.5.0

### hb_buffer_message_func_t ()

    hb_bool_t
    (*hb_buffer_message_func_t) (hb_buffer_t *buffer,
                                 hb_font_t *font,
                                 const char *message,
                                 void *user_data);

A callback method for hb_buffer_t. The method gets called with the hb_buffer_t it was set on, the hb_font_t the buffer is shaped with and a message describing what step of the shaping process will be performed. Returning `false` from this method will skip this shaping step and move to the next one.

#### Parameters

buffer | An hb_buffer_t to work upon |
font | The hb_font_t the `buffer` is shaped with |
message | `NULL`-terminated message passed to the function |
user_data | User data pointer passed by the caller |

#### Returns

`true` to perform the shaping step, `false` to skip it.

Since: 1.1.3

## Types and Values

### HB_SEGMENT_PROPERTIES_DEFAULT

    #define             HB_SEGMENT_PROPERTIES_DEFAULT

The default hb_segment_properties_t of of freshly created hb_buffer_t.

### HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT

    #define HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT 0xFFFDu

The default code point for replacing invalid characters in a given encoding. Set to U+FFFD REPLACEMENT CHARACTER.

Since: 0.9.31

### hb_buffer_t

    typedef struct hb_buffer_t hb_buffer_t;

The main structure holding the input text and its properties before shaping, and output glyphs and their information after shaping.

### hb_glyph_info_t

    typedef struct {
      hb_codepoint_t codepoint;
      uint32_t       cluster;
    } hb_glyph_info_t;

The hb_glyph_info_t is the structure that holds information about the glyphs and their relation to input text.

#### Members

hb_codepoint_t `codepoint`; | either a Unicode code point (before shaping) or a glyph index (after shaping). |
uint32_t `cluster`; | the index of the character in the original text that corresponds to this hb_glyph_info_t, or whatever the client passes to `hb_buffer_add()`. More than one hb_glyph_info_t can have the same `cluster` value, if they resulted from the same character (e.g. one to many glyph substitution), and when more than one character gets merged in the same glyph (e.g. many to one glyph substitution) the hb_glyph_info_t will have the smallest cluster value of them. By default some characters are merged into the same cluster (e.g. combining marks have the same cluster as their bases) even if they are separate glyphs, `hb_buffer_set_cluster_level()` allow selecting more fine-grained cluster handling. |

### enum hb_glyph_flags_t

Flags for hb_glyph_info_t.

#### Members

HB_GLYPH_FLAG_UNSAFE_TO_BREAK | Indicates that if input text is broken at the beginning of the cluster this glyph is part of, then both sides need to be re-shaped, as the result might be different. On the flip side, it means that when this flag is not present, then it's safe to break the glyph-run at the beginning of this cluster, and the two sides represent the exact same result one would get if breaking input text at the beginning of this cluster and shaping the two sides separately. This can be used to optimize paragraph layout, by avoiding re-shaping of each line after line-breaking, or limiting the reshaping to a small piece around the breaking point only. |
HB_GLYPH_FLAG_DEFINED | All the currently defined flags. |

Since: 1.5.0

### hb_glyph_position_t

    typedef struct {
      hb_position_t  x_advance;
      hb_position_t  y_advance;
      hb_position_t  x_offset;
      hb_position_t  y_offset;
    } hb_glyph_position_t;

The hb_glyph_position_t is the structure that holds the positions of the glyph in both horizontal and vertical directions. All positions in hb_glyph_position_t are relative to the current point.

#### Members

hb_position_t `x_advance`; | how much the line advances after drawing this glyph when setting text in horizontal direction. |
hb_position_t `y_advance`; | how much the line advances after drawing this glyph when setting text in vertical direction. |
hb_position_t `x_offset`; | how much the glyph moves on the X-axis before drawing it, this should not affect how much the line advances. |
hb_position_t `y_offset`; | how much the glyph moves on the Y-axis before drawing it, this should not affect how much the line advances. |

### enum hb_buffer_content_type_t

The type of hb_buffer_t contents.

#### Members

HB_BUFFER_CONTENT_TYPE_INVALID | Initial value for new buffer. |
HB_BUFFER_CONTENT_TYPE_UNICODE | The buffer contains input characters (before shaping). |
HB_BUFFER_CONTENT_TYPE_GLYPHS | The buffer contains output glyphs (after shaping). |

### enum hb_buffer_flags_t

Flags for hb_buffer_t.

#### Members

HB_BUFFER_FLAG_DEFAULT | the default buffer flag. |
HB_BUFFER_FLAG_BOT | flag indicating that special handling of the beginning of text paragraph can be applied to this buffer. Should usually be set, unless you are passing to the buffer only part of the text without the full context. |
HB_BUFFER_FLAG_EOT | flag indicating that special handling of the end of text paragraph can be applied to this buffer, similar to `HB_BUFFER_FLAG_BOT` . |
HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES | flag indication that character with Default_Ignorable Unicode property should use the corresponding glyph from the font, instead of hiding them (done by replacing them with the space glyph and zeroing the advance width.) This flag takes precedence over `HB_BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES` . |
HB_BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES | flag indication that character with Default_Ignorable Unicode property should be removed from glyph string instead of hiding them (done by replacing them with the space glyph and zeroing the advance width.) `HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES` takes precedence over this flag. Since: 1.8.0 |
HB_BUFFER_FLAG_DO_NOT_INSERT_DOTTED_CIRCLE | flag indicating that a dotted circle should not be inserted in the rendering of incorrect character sequences (such at <0905 093E>). Since: 2.4 |

Since: 0.9.20

### enum hb_buffer_cluster_level_t

Data type for holding HarfBuzz's clustering behavior options. The cluster level dictates one aspect of how HarfBuzz will treat non-base characters during shaping.

In `HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES` , non-base characters are merged into the cluster of the base character that precedes them.

In `HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS` , non-base characters are initially assigned their own cluster values, which are not merged into preceding base clusters. This allows HarfBuzz to perform additional operations like reorder sequences of adjacent marks.

`HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES` is the default, because it maintains backward compatibility with older versions of HarfBuzz. New client programs that do not need to maintain such backward compatibility are recommended to use `HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS` instead of the default.

#### Members

HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES | Return cluster values grouped by graphemes into monotone order. |
HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS | Return cluster values grouped into monotone order. |
HB_BUFFER_CLUSTER_LEVEL_CHARACTERS | Don't group cluster values. |
HB_BUFFER_CLUSTER_LEVEL_DEFAULT | Default cluster level, equal to `HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES` . |

Since: 0.9.42

### hb_segment_properties_t

    typedef struct {
      hb_direction_t  direction;
      hb_script_t     script;
      hb_language_t   language;
    } hb_segment_properties_t;

The structure that holds various text properties of an hb_buffer_t. Can be set and retrieved using `hb_buffer_set_segment_properties()` and `hb_buffer_get_segment_properties()`, respectively.

#### Members

hb_direction_t `direction`; | the hb_direction_t of the buffer, see `hb_buffer_set_direction()`. |
hb_script_t `script`; | the hb_script_t of the buffer, see `hb_buffer_set_script()`. |
hb_language_t `language`; | the hb_language_t of the buffer, see `hb_buffer_set_language()`. |

### enum hb_buffer_serialize_format_t

The buffer serialization and de-serialization format used in `hb_buffer_serialize_glyphs()` and `hb_buffer_deserialize_glyphs()`.

#### Members

HB_BUFFER_SERIALIZE_FORMAT_TEXT | a human-readable, plain text format. |
HB_BUFFER_SERIALIZE_FORMAT_JSON | a machine-readable JSON format. |
HB_BUFFER_SERIALIZE_FORMAT_INVALID | invalid format. |

Since: 0.9.2

### enum hb_buffer_serialize_flags_t

Flags that control what glyph information are serialized in `hb_buffer_serialize_glyphs()`.

#### Members

HB_BUFFER_SERIALIZE_FLAG_DEFAULT | serialize glyph names, clusters and positions. |
HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS | do not serialize glyph cluster. |
HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS | do not serialize glyph position information. |
HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES | do no serialize glyph name. |
HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS | serialize glyph extents. |
HB_BUFFER_SERIALIZE_FLAG_GLYPH_FLAGS | serialize glyph flags. Since: 1.5.0 |
HB_BUFFER_SERIALIZE_FLAG_NO_ADVANCES | do not serialize glyph advances, glyph offsets will reflect absolute glyph positions. Since: 1.8.0 |

Since: 0.9.20

### enum hb_buffer_diff_flags_t

Flags from comparing two hb_buffer_t's.

Buffer with different hb_buffer_content_type_t cannot be meaningfully compared in any further detail.

For buffers with differing length, the per-glyph comparison is not attempted, though we do still scan reference buffer for dotted circle and `.notdef` glyphs.

If the buffers have the same length, we compare them glyph-by-glyph and report which aspect(s) of the glyph info/position are different.

#### Members

HB_BUFFER_DIFF_FLAG_EQUAL | equal buffers. |
HB_BUFFER_DIFF_FLAG_CONTENT_TYPE_MISMATCH | buffers with different hb_buffer_content_type_t. |
HB_BUFFER_DIFF_FLAG_LENGTH_MISMATCH | buffers with differing length. |
HB_BUFFER_DIFF_FLAG_NOTDEF_PRESENT | `.notdef` glyph is present in the reference buffer. |
HB_BUFFER_DIFF_FLAG_DOTTED_CIRCLE_PRESENT | dotted circle glyph is present in the reference buffer. |
HB_BUFFER_DIFF_FLAG_CODEPOINT_MISMATCH | difference in hb_glyph_info_t.codepoint |
HB_BUFFER_DIFF_FLAG_CLUSTER_MISMATCH | difference in hb_glyph_info_t.cluster |
HB_BUFFER_DIFF_FLAG_GLYPH_FLAGS_MISMATCH | difference in hb_glyph_flags_t. |
HB_BUFFER_DIFF_FLAG_POSITION_MISMATCH | difference in hb_glyph_position_t. |

Since: 1.5.0