Top |
Functions
Types and Values
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.
The input buffer is a sequence of Unicode codepoints, with associated attributes such as direction and script. The output buffer is a sequence of glyphs, with associated attributes such as position and cluster.
Functions
hb_buffer_create ()
hb_buffer_t *
hb_buffer_create (void
);
Creates a new hb_buffer_t with all properties to defaults.
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_allocation_successful ()
hb_bool_t
hb_buffer_allocation_successful (hb_buffer_t *buffer
);
Check if allocating memory for the buffer succeeded.
Since: 0.9.2
hb_buffer_create_similar ()
hb_buffer_t *
hb_buffer_create_similar (const hb_buffer_t *src
);
Creates a new hb_buffer_t, similar to hb_buffer_create()
. The only
difference is that the buffer is configured similarly to src
.
Since: 3.3.0
hb_buffer_get_empty ()
hb_buffer_t *
hb_buffer_get_empty (void
);
Fetches an empty hb_buffer_t.
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]
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]
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 |
[nullable] |
replace |
Whether to replace an existing data with the same key |
Since: 0.9.2
hb_buffer_get_user_data ()
void * hb_buffer_get_user_data (const 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]
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()
.
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.
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.
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 |
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 scalar values. In contrast,
hb_buffer_add_utf32()
can be used that takes similar input but performs
sanity-check on the input.
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 |
|
item_offset |
the offset of the first code point to add to the |
|
item_length |
the number of code points to add to the |
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 |
|
item_offset |
The offset of the first character to add to the |
|
item_length |
The number of characters to add to the |
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 |
|
item_offset |
The offset of the first character to add to the |
|
item_length |
The number of characters to add to the |
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 |
|
item_offset |
The offset of the first character to add to the |
|
item_length |
The number of characters to add to the |
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.
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 |
|
item_offset |
the offset of the first character to add to the |
|
item_length |
the number of characters to add to the |
Since: 0.9.39
hb_buffer_append ()
void hb_buffer_append (hb_buffer_t *buffer
,const 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 |
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).
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
HB_BUFFER_CONTENT_TYPE_INVALID
. Callinghb_buffer_reset()
,hb_buffer_clear_contents()
, as well as callinghb_buffer_set_length()
with an argument of zero all set the buffer content type to invalid as well.Calling
hb_buffer_add_utf8()
,hb_buffer_add_utf16()
,hb_buffer_add_utf32()
,hb_buffer_add_codepoints()
andhb_buffer_add_latin1()
expect that buffer is either empty and have a content type of invalid, or that buffer content type isHB_BUFFER_CONTENT_TYPE_UNICODE
, and they also set the content type to Unicode if they added anything to an empty buffer.Finally
hb_shape()
andhb_shape_full()
expect that the buffer is either empty and have content type of invalid, or that buffer content type isHB_BUFFER_CONTENT_TYPE_UNICODE
, and upon success they set the buffer content type toHB_BUFFER_CONTENT_TYPE_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.
Since: 0.9.5
hb_buffer_get_content_type ()
hb_buffer_content_type_t
hb_buffer_get_content_type (const 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).
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.
Since: 0.9.2
hb_buffer_get_direction ()
hb_direction_t
hb_buffer_get_direction (const hb_buffer_t *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.
Since: 0.9.2
hb_buffer_get_script ()
hb_script_t
hb_buffer_get_script (const hb_buffer_t *buffer
);
Fetches the script of 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.
Since: 0.9.2
hb_buffer_get_language ()
hb_language_t
hb_buffer_get_language (const hb_buffer_t *buffer
);
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.
Since: 0.9.7
hb_buffer_get_flags ()
hb_buffer_flags_t
hb_buffer_get_flags (const hb_buffer_t *buffer
);
Fetches the hb_buffer_flags_t of buffer
.
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.
Since: 0.9.42
hb_buffer_get_cluster_level ()
hb_buffer_cluster_level_t
hb_buffer_get_cluster_level (const 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.
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.
Since: 0.9.2
hb_buffer_get_length ()
unsigned int
hb_buffer_get_length (const hb_buffer_t *buffer
);
Returns the number of items in the buffer.
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.
Since: 0.9.7
hb_buffer_get_segment_properties ()
void hb_buffer_get_segment_properties (const hb_buffer_t *buffer
,hb_segment_properties_t *props
);
Sets props
to the hb_segment_properties_t of buffer
.
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.
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
.
Since: 0.9.2
hb_buffer_get_unicode_funcs ()
hb_unicode_funcs_t *
hb_buffer_get_unicode_funcs (const hb_buffer_t *buffer
);
Fetches the Unicode-functions structure of a buffer.
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.
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_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.
Since: 1.5.0
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.
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 hb_buffer_set_message_func()
),
in which case NULL
is returned.
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.
Since: 2.7.3
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.
Since: 2.0.0
hb_buffer_get_invisible_glyph ()
hb_codepoint_t
hb_buffer_get_invisible_glyph (const hb_buffer_t *buffer
);
See hb_buffer_set_invisible_glyph()
.
Since: 2.0.0
hb_buffer_set_not_found_glyph ()
void hb_buffer_set_not_found_glyph (hb_buffer_t *buffer
,hb_codepoint_t not_found
);
Sets the hb_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.
Since: 3.1.0
hb_buffer_get_not_found_glyph ()
hb_codepoint_t
hb_buffer_get_not_found_glyph (const hb_buffer_t *buffer
);
See hb_buffer_set_not_found_glyph()
.
Since: 3.1.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.
Since: 0.9.31
hb_buffer_get_replacement_codepoint ()
hb_codepoint_t
hb_buffer_get_replacement_codepoint (const hb_buffer_t *buffer
);
Fetches the hb_codepoint_t that replaces invalid entries for a given encoding
when adding text to buffer
.
Since: 0.9.31
hb_buffer_set_random_state ()
void hb_buffer_set_random_state (hb_buffer_t *buffer
,unsigned state
);
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
hb_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.
Since: 8.4.0
hb_buffer_get_random_state ()
unsigned
hb_buffer_get_random_state (const hb_buffer_t *buffer
);
See hb_buffer_set_random_state()
.
Since: 8.4.0
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.
Since: 0.9.2
hb_buffer_reverse ()
void
hb_buffer_reverse (hb_buffer_t *buffer
);
Reverses buffer contents.
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
.
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.
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 |
|
end |
the last item in |
|
buf |
output string to write serialized buffer into. |
[out][array length=buf_size][element-type uint8_t] |
buf_size |
the size of |
|
buf_consumed |
if not |
[out][optional] |
font |
the hb_font_t used to shape this buffer, needed to
read glyph names and extents. If |
[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. |
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 |
|
end |
the last item in |
|
buf |
output string to write serialized buffer into. |
[out][array length=buf_size][element-type uint8_t] |
buf_size |
the size of |
|
buf_consumed |
if not |
[out][optional] |
font |
the hb_font_t used to shape this buffer, needed to
read glyph names and extents. If |
[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. |
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 |
|
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 |
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 integercl
: 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 |
|
end |
the last item in |
|
buf |
output string to write serialized buffer into. |
[out][array length=buf_size][element-type uint8_t] |
buf_size |
the size of |
|
buf_consumed |
if not |
[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. |
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 |
|
end_ptr |
output pointer to the character after last consumed one. |
[out][optional] |
format |
the hb_buffer_serialize_format_t of the input |
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 |
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.
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.
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.
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
.
Since: 0.9.7
hb_segment_properties_overlay ()
void hb_segment_properties_overlay (hb_segment_properties_t *p
,const hb_segment_properties_t *src
);
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
.
Since: 3.3.0
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_codepoint_t) -1. |
|
position_fuzz |
allowed absolute difference in position values. |
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 |
|
message |
|
|
user_data |
User data pointer passed by the caller |
Since: 1.1.3
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 |
[nullable] |
destroy |
The function to call when |
[nullable] |
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 |
either a Unicode code point (before shaping) or a glyph index (after shaping). |
|
the index of the character in the original text that corresponds
to this hb_glyph_info_t, or whatever the client passes to
|
enum hb_glyph_flags_t
Flags for hb_glyph_info_t.
Members
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 is safe to break the glyph-run at the beginning of this cluster, and the two sides will 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. |
||
Indicates that if input text is changed on one
side of the beginning of the cluster this glyph
is part of, then the shaping results for the
other side might change.
Note that the absence of this flag will NOT by
itself mean that it IS safe to concat text.
Only two pieces of text both of which clear of
this flag can be concatenated safely.
This can be used to optimize paragraph
layout, by avoiding re-shaping of each line
after line-breaking, by limiting the
reshaping to a small piece around the
breaking position only, even if the breaking
position carries the
HB_GLYPH_FLAG_UNSAFE_TO_BREAK or when
hyphenation or other text transformation
happens at line-break position, in the following
way:
1. Iterate back from the line-break position
until the first cluster start position that is
NOT unsafe-to-concat, 2. shape the segment from
there till the end of line, 3. check whether the
resulting glyph-run also is clear of the
unsafe-to-concat at its start-of-text position;
if it is, just splice it into place and the line
is shaped; If not, move on to a position further
back that is clear of unsafe-to-concat and retry
from there, and repeat.
At the start of next line a similar algorithm can
be implemented. That is: 1. Iterate forward from
the line-break position until the first cluster
start position that is NOT unsafe-to-concat, 2.
shape the segment from beginning of the line to
that position, 3. check whether the resulting
glyph-run also is clear of the unsafe-to-concat
at its end-of-text position; if it is, just splice
it into place and the beginning is shaped; If not,
move on to a position further forward that is clear
of unsafe-to-concat and retry up to there, and repeat.
A slight complication will arise in the
implementation of the algorithm above,
because while our buffer API has a way to
return flags for position corresponding to
start-of-text, there is currently no position
corresponding to end-of-text. This limitation
can be alleviated by shaping more text than needed
and looking for unsafe-to-concat flag within text
clusters.
The HB_GLYPH_FLAG_UNSAFE_TO_BREAK flag will
always imply this flag.
To use this flag, you must enable the buffer flag
|
||
In scripts that use elongation (Arabic, Mongolian, Syriac, etc.), this flag signifies that it is safe to insert a U+0640 TATWEEL character before this cluster for elongation. This flag does not determine the script-specific elongation places, but only when it is safe to do the elongation without interrupting text shaping. Since: 5.1.0 |
||
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 |
how much the line advances after drawing this glyph when setting text in horizontal direction. |
|
hb_position_t |
how much the line advances after drawing this glyph when setting text in vertical direction. |
|
hb_position_t |
how much the glyph moves on the X-axis before drawing it, this should not affect how much the line advances. |
|
hb_position_t |
how much the glyph moves on the Y-axis before drawing it, this should not affect how much the line advances. |
enum hb_buffer_flags_t
Flags for hb_buffer_t.
Members
the default buffer flag. |
||
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. |
||
flag indicating that special handling of the end of text
paragraph can be applied to this buffer, similar to
|
||
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
|
||
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.)
|
||
flag indicating that a dotted circle should not be inserted in the rendering of incorrect character sequences (such at <0905 093E>). Since: 2.4.0 |
||
flag indicating that the |
||
flag indicating that the |
||
flag indicating that the |
||
All currently defined flags: Since: 4.4.0 |
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
Return cluster values grouped by graphemes into monotone order. |
||
Return cluster values grouped into monotone order. |
||
Don't group cluster values. |
||
Default cluster level,
equal to |
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 |
the hb_direction_t of the buffer, see |
|
hb_script_t |
the hb_script_t of the buffer, see |
|
hb_language_t |
the hb_language_t of the buffer, see |
enum hb_buffer_serialize_format_t
The buffer serialization and de-serialization format used in
hb_buffer_serialize_glyphs()
and hb_buffer_deserialize_glyphs()
.
Since: 0.9.2
enum hb_buffer_serialize_flags_t
Flags that control what glyph information are serialized in hb_buffer_serialize_glyphs()
.
Members
serialize glyph names, clusters and positions. |
||
do not serialize glyph cluster. |
||
do not serialize glyph position information. |
||
do no serialize glyph name. |
||
serialize glyph extents. |
||
serialize glyph flags. Since: 1.5.0 |
||
do not serialize glyph advances, glyph offsets will reflect absolute glyph positions. Since: 1.8.0 |
||
All currently defined flags. Since: 4.4.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
equal buffers. |
||
buffers with different hb_buffer_content_type_t. |
||
buffers with differing length. |
||
|
||
dotted circle glyph is present in the reference buffer. |
||
difference in hb_glyph_info_t.codepoint |
||
difference in hb_glyph_info_t.cluster |
||
difference in hb_glyph_flags_t. |
||
difference in hb_glyph_position_t. |
Since: 1.5.0