From 9ab9f974d42e0001966e243a23a64e6aefbd4764 Mon Sep 17 00:00:00 2001 From: Khaled Hosny Date: Fri, 1 Jan 2016 20:38:21 +0400 Subject: [PATCH] [docs] More buffers documentation --- docs/harfbuzz-sections.txt | 4 +- src/hb-buffer-serialize.cc | 85 ++++++++++++++++++++++++----------- src/hb-buffer.cc | 91 +++++++++++++++++++++++++++++--------- src/hb-buffer.h | 78 ++++++++++++++++++++------------ src/hb-shape.cc | 10 +++-- 5 files changed, 187 insertions(+), 81 deletions(-) diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt index 153f19e22..e0dc23d9c 100644 --- a/docs/harfbuzz-sections.txt +++ b/docs/harfbuzz-sections.txt @@ -56,8 +56,8 @@ hb_buffer_get_cluster_level hb_buffer_set_length hb_buffer_get_length hb_buffer_set_segment_properties -hb_buffer_guess_segment_properties hb_buffer_get_segment_properties +hb_buffer_guess_segment_properties hb_buffer_set_unicode_funcs hb_buffer_get_unicode_funcs hb_buffer_set_user_data @@ -84,9 +84,9 @@ hb_glyph_position_t hb_buffer_content_type_t hb_buffer_flags_t hb_buffer_cluster_level_t -hb_buffer_serialize_flags_t hb_segment_properties_t hb_buffer_serialize_format_t +hb_buffer_serialize_flags_t hb_buffer_message_func_t diff --git a/src/hb-buffer-serialize.cc b/src/hb-buffer-serialize.cc index 2dc146ab1..63a0f3466 100644 --- a/src/hb-buffer-serialize.cc +++ b/src/hb-buffer-serialize.cc @@ -36,11 +36,12 @@ static const char *serialize_formats[] = { /** * hb_buffer_serialize_list_formats: * - * + * Returns a list of supported buffer serialization formats. * * Return value: (transfer none): + * A string array of buffer serialization formats. Should not be freed. * - * Since: 0.9.2 + * Since: 0.9.7 **/ const char ** hb_buffer_serialize_list_formats (void) @@ -50,14 +51,17 @@ hb_buffer_serialize_list_formats (void) /** * hb_buffer_serialize_format_from_string: - * @str: - * @len: + * @str: (array length=len) (element-type uint8_t): a string to parse + * @len: length of @str, or -1 if string is %NULL terminated * - * + * 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. * * Return value: + * The parsed #hb_buffer_serialize_format_t. * - * Since: 0.9.2 + * Since: 0.9.7 **/ hb_buffer_serialize_format_t hb_buffer_serialize_format_from_string (const char *str, int len) @@ -68,13 +72,15 @@ hb_buffer_serialize_format_from_string (const char *str, int len) /** * hb_buffer_serialize_format_to_string: - * @format: + * @format: an #hb_buffer_serialize_format_t to convert. * - * + * Converts @format to the string corresponding it, or %NULL if it is not a valid + * #hb_buffer_serialize_format_t. * - * Return value: + * Return value: (transfer none): + * A %NULL terminated string corresponding to @format. Should not be freed. * - * Since: 0.9.2 + * Since: 0.9.7 **/ const char * hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format) @@ -242,24 +248,51 @@ _hb_buffer_serialize_glyphs_text (hb_buffer_t *buffer, return end - start; } -/* Returns number of items, starting at start, that were serialized. */ /** * hb_buffer_serialize_glyphs: - * @buffer: a buffer. - * @start: - * @end: - * @buf: (array length=buf_size): - * @buf_size: - * @buf_consumed: (out): - * @font: - * @format: - * @flags: + * @buffer: an #hb_buffer_t buffer. + * @start: the first item in @buffer to serialize. + * @end: the last item in @buffer to serialize. + * @buf: (out) (array length=buf_size) (element-type uint8_t): output string to + * write serialized buffer into. + * @buf_size: the size of @buf. + * @buf_consumed: (out) (allow-none): if not %NULL, will be set to the number of byes written into @buf. + * @font: (allow-none): the #hb_font_t used to shape this buffer, needed to + * read glyph names and extents. If %NULL, and empty font will be used. + * @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. * - * + * 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 + * TODO. * * Return value: + * The number of serialized items. * - * Since: 0.9.2 + * Since: 0.9.7 **/ unsigned int hb_buffer_serialize_glyphs (hb_buffer_t *buffer, @@ -267,8 +300,8 @@ hb_buffer_serialize_glyphs (hb_buffer_t *buffer, unsigned int end, char *buf, unsigned int buf_size, - unsigned int *buf_consumed, /* May be NULL */ - hb_font_t *font, /* May be NULL */ + unsigned int *buf_consumed, + hb_font_t *font, hb_buffer_serialize_format_t format, hb_buffer_serialize_flags_t flags) { @@ -358,7 +391,7 @@ parse_int (const char *pp, const char *end, int32_t *pv) /** * hb_buffer_deserialize_glyphs: - * @buffer: a buffer. + * @buffer: an #hb_buffer_t buffer. * @buf: (array length=buf_len): * @buf_len: * @end_ptr: (out): @@ -369,7 +402,7 @@ parse_int (const char *pp, const char *end, int32_t *pv) * * Return value: * - * Since: 0.9.2 + * Since: 0.9.7 **/ hb_bool_t hb_buffer_deserialize_glyphs (hb_buffer_t *buffer, diff --git a/src/hb-buffer.cc b/src/hb-buffer.cc index 468aa79db..c731ed189 100644 --- a/src/hb-buffer.cc +++ b/src/hb-buffer.cc @@ -47,6 +47,13 @@ /** * hb_segment_properties_equal: + * @a: first #hb_segment_properties_t to compare. + * @b: second #hb_segment_properties_t to compare. + * + * Checks the equality of two #hb_segment_properties_t's. + * + * Return value: (transfer full): + * %true if all properties of @a equal those of @b, false otherwise. * * Since: 0.9.7 **/ @@ -64,6 +71,12 @@ hb_segment_properties_equal (const hb_segment_properties_t *a, /** * hb_segment_properties_hash: + * @p: #hb_segment_properties_t to hash. + * + * Creates a hash representing @p. + * + * Return value: + * A hash of @p. * * Since: 0.9.7 **/ @@ -1075,9 +1088,11 @@ hb_buffer_get_language (hb_buffer_t *buffer) /** * hb_buffer_set_segment_properties: * @buffer: an #hb_buffer_t. - * @props: + * @props: an #hb_segment_properties_t to use. * - * + * 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 **/ @@ -1094,9 +1109,9 @@ hb_buffer_set_segment_properties (hb_buffer_t *buffer, /** * hb_buffer_get_segment_properties: * @buffer: an #hb_buffer_t. - * @props: (out): + * @props: (out): the output #hb_segment_properties_t. * - * + * Sets @props to the #hb_segment_properties_t of @buffer. * * Since: 0.9.7 **/ @@ -1183,9 +1198,12 @@ hb_buffer_get_cluster_level (hb_buffer_t *buffer) /** * hb_buffer_set_replacement_codepoint: * @buffer: an #hb_buffer_t. - * @replacement: + * @replacement: the replacement #hb_codepoint_t * - * + * 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 **/ @@ -1203,9 +1221,10 @@ hb_buffer_set_replacement_codepoint (hb_buffer_t *buffer, * hb_buffer_get_replacement_codepoint: * @buffer: an #hb_buffer_t. * - * + * See hb_buffer_set_replacement_codepoint(). * * Return value: + * The @buffer replacement #hb_codepoint_t. * * Since: 0.9.31 **/ @@ -1220,8 +1239,8 @@ hb_buffer_get_replacement_codepoint (hb_buffer_t *buffer) * hb_buffer_reset: * @buffer: an #hb_buffer_t. * - * Resets the buffer to its initial status, just like new buffers returned from - * hb_buffer_create(). + * Resets the buffer to its initial status, as if it was just newly created + * with hb_buffer_create(). * * Since: 0.9.2 **/ @@ -1235,7 +1254,8 @@ hb_buffer_reset (hb_buffer_t *buffer) * hb_buffer_clear_contents: * @buffer: an #hb_buffer_t. * - * Clears the contents of the buffer without resetting other properties. + * Similar to hb_buffer_reset(), but does not clear the Unicode functions and + * the replacement code point. * * Since: 0.9.11 **/ @@ -1253,7 +1273,7 @@ hb_buffer_clear_contents (hb_buffer_t *buffer) * Pre allocates memory for @buffer to fit at least @size number of items. * * Return value: - * %true if the memory pre allocation succeeded, %false otherwise. + * %true if @buffer memory allocation succeeded, %false otherwise. * * Since: 0.9.2 **/ @@ -1270,7 +1290,7 @@ hb_buffer_pre_allocate (hb_buffer_t *buffer, unsigned int size) * Check if allocating memory for the buffer succeeded. * * Return value: - * %true if memory allocation succeeded, %false otherwise. + * %true if @buffer memory allocation succeeded, %false otherwise. * * Since: 0.9.2 **/ @@ -1292,6 +1312,9 @@ hb_buffer_allocation_successful (hb_buffer_t *buffer) * 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. + * * Since: 0.9.7 **/ void @@ -1306,11 +1329,13 @@ hb_buffer_add (hb_buffer_t *buffer, /** * hb_buffer_set_length: * @buffer: an #hb_buffer_t. - * @length: + * @length: the new length of @buffer. * - * + * Similar to hb_buffer_pre_allocate(), but clears any new items added at the + * end. * * Return value: + * %true if @buffer memory allocation succeeded, %false otherwise. * * Since: 0.9.2 **/ @@ -1351,6 +1376,7 @@ hb_buffer_set_length (hb_buffer_t *buffer, * * Return value: * The @buffer length. + * The value valid as long as buffer has not been modified. * * Since: 0.9.2 **/ @@ -1370,6 +1396,7 @@ hb_buffer_get_length (hb_buffer_t *buffer) * * Return value: (transfer none) (array length=length): * The @buffer glyph information array. + * The value valid as long as buffer has not been modified. * * Since: 0.9.2 **/ @@ -1393,6 +1420,7 @@ hb_buffer_get_glyph_infos (hb_buffer_t *buffer, * * Return value: (transfer none) (array length=length): * The @buffer glyph position array. + * The value valid as long as buffer has not been modified. * * Since: 0.9.2 **/ @@ -1558,7 +1586,8 @@ hb_buffer_add_utf (hb_buffer_t *buffer, /** * hb_buffer_add_utf8: * @buffer: an #hb_buffer_t. - * @text: (array length=text_length): an array of UTF-8 characters to append. + * @text: (array length=text_length) (element-type uint8_t): an array of UTF-8 + * characters to append. * @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 @@ -1566,6 +1595,9 @@ hb_buffer_add_utf (hb_buffer_t *buffer, * * See hb_buffer_add_codepoints(). * + * Replaces invalid UTF-8 characters with the @buffer replacement code point, + * see hb_buffer_set_replacement_codepoint(). + * * Since: 0.9.2 **/ void @@ -1589,6 +1621,9 @@ hb_buffer_add_utf8 (hb_buffer_t *buffer, * * See hb_buffer_add_codepoints(). * + * Replaces invalid UTF-16 characters with the @buffer replacement code point, + * see hb_buffer_set_replacement_codepoint(). + * * Since: 0.9.2 **/ void @@ -1612,6 +1647,9 @@ hb_buffer_add_utf16 (hb_buffer_t *buffer, * * See hb_buffer_add_codepoints(). * + * Replaces invalid UTF-32 characters with the @buffer replacement code point, + * see hb_buffer_set_replacement_codepoint(). + * * Since: 0.9.2 **/ void @@ -1627,12 +1665,17 @@ hb_buffer_add_utf32 (hb_buffer_t *buffer, /** * hb_buffer_add_latin1: * @buffer: an #hb_buffer_t. - * @text: (array length=text_length) (element-type uint8_t): - * @text_length: - * @item_offset: - * @item_length: + * @text: (array length=text_length) (element-type uint8_t): an array of UTF-8 + * characters to append. + * @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). * - * + * 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. * * Since: 0.9.39 **/ @@ -1665,6 +1708,9 @@ hb_buffer_add_latin1 (hb_buffer_t *buffer, * 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. + * * Since: 0.9.31 **/ void @@ -1737,7 +1783,10 @@ normalize_glyphs_cluster (hb_buffer_t *buffer, * hb_buffer_normalize_glyphs: * @buffer: an #hb_buffer_t. * - * + * 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. * * Since: 0.9.2 **/ diff --git a/src/hb-buffer.h b/src/hb-buffer.h index 9b72383ba..062c4e719 100644 --- a/src/hb-buffer.h +++ b/src/hb-buffer.h @@ -58,7 +58,7 @@ HB_BEGIN_DECLS * hb_buffer_set_cluster_level() allow selecting more fine-grained * cluster handling. * - * The #hb_glyph_info_t is the structure that holds informations about the + * The #hb_glyph_info_t is the structure that holds information about the * glyphs and their relation to input text. * */ @@ -98,7 +98,16 @@ typedef struct hb_glyph_position_t { hb_var_int_t var; } hb_glyph_position_t; - +/** + * hb_segment_properties_t: + * @direction: the #hb_direction_t of the buffer, see hb_buffer_set_direction(). + * @script: the #hb_script_t of the buffer, see hb_buffer_set_script(). + * @language: the #hb_language_t of the buffer, see hb_buffer_set_language(). + * + * 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. + */ typedef struct hb_segment_properties_t { hb_direction_t direction; hb_script_t script; @@ -123,8 +132,11 @@ hb_segment_properties_hash (const hb_segment_properties_t *p); -/* - * 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. */ typedef struct hb_buffer_t hb_buffer_t; @@ -262,10 +274,16 @@ hb_buffer_set_cluster_level (hb_buffer_t *buffer, HB_EXTERN hb_buffer_cluster_level_t hb_buffer_get_cluster_level (hb_buffer_t *buffer); +/** + * HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT: + * + * The default code point for replacing invalid characters in a given encoding. + * Set to U+FFFD REPLACEMENT CHARACTER. + * + * Since: 0.9.31 + */ #define HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT 0xFFFDu -/* Sets codepoint used to replace invalid UTF-8/16/32 entries. - * Default is 0xFFFDu. */ HB_EXTERN void hb_buffer_set_replacement_codepoint (hb_buffer_t *buffer, hb_codepoint_t replacement); @@ -274,22 +292,17 @@ HB_EXTERN hb_codepoint_t hb_buffer_get_replacement_codepoint (hb_buffer_t *buffer); -/* Resets the buffer. Afterwards it's as if it was just created, - * except that it has a larger buffer allocated perhaps... */ HB_EXTERN void hb_buffer_reset (hb_buffer_t *buffer); -/* Like reset, but does NOT clear unicode_funcs and replacement_codepoint. */ HB_EXTERN void hb_buffer_clear_contents (hb_buffer_t *buffer); -/* Returns false if allocation failed */ HB_EXTERN hb_bool_t hb_buffer_pre_allocate (hb_buffer_t *buffer, unsigned int size); -/* Returns false if allocation has failed before */ HB_EXTERN hb_bool_t hb_buffer_allocation_successful (hb_buffer_t *buffer); @@ -332,7 +345,6 @@ hb_buffer_add_utf32 (hb_buffer_t *buffer, unsigned int item_offset, int item_length); -/* Allows only access to first 256 Unicode codepoints. */ HB_EXTERN void hb_buffer_add_latin1 (hb_buffer_t *buffer, const uint8_t *text, @@ -340,7 +352,6 @@ hb_buffer_add_latin1 (hb_buffer_t *buffer, unsigned int item_offset, int item_length); -/* Like add_utf32 but does NOT check for invalid Unicode codepoints. */ HB_EXTERN void hb_buffer_add_codepoints (hb_buffer_t *buffer, const hb_codepoint_t *text, @@ -349,31 +360,24 @@ hb_buffer_add_codepoints (hb_buffer_t *buffer, int item_length); -/* Clears any new items added at the end */ HB_EXTERN hb_bool_t hb_buffer_set_length (hb_buffer_t *buffer, unsigned int length); -/* Return value valid as long as buffer not modified */ HB_EXTERN unsigned int hb_buffer_get_length (hb_buffer_t *buffer); /* Getting glyphs out of the buffer */ -/* Return value valid as long as buffer not modified */ HB_EXTERN hb_glyph_info_t * hb_buffer_get_glyph_infos (hb_buffer_t *buffer, unsigned int *length); -/* Return value valid as long as buffer not modified */ HB_EXTERN hb_glyph_position_t * hb_buffer_get_glyph_positions (hb_buffer_t *buffer, unsigned int *length); -/* 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. */ HB_EXTERN void hb_buffer_normalize_glyphs (hb_buffer_t *buffer); @@ -382,7 +386,16 @@ hb_buffer_normalize_glyphs (hb_buffer_t *buffer); * Serialize */ -/* +/** + * hb_buffer_serialize_flags_t: + * @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. + * + * Flags that control what glyph information are serialized in hb_buffer_serialize_glyphs(). + * * Since: 0.9.20 */ typedef enum { /*< flags >*/ @@ -393,13 +406,23 @@ typedef enum { /*< flags >*/ HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS = 0x00000008u } hb_buffer_serialize_flags_t; +/** + * hb_buffer_serialize_format_t: + * @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. + * + * The buffer serialization and de-serialization format used in + * hb_buffer_serialize_glyphs() and hb_buffer_deserialize_glyphs(). + * + * Since: 0.9.2 + */ typedef enum { HB_BUFFER_SERIALIZE_FORMAT_TEXT = HB_TAG('T','E','X','T'), HB_BUFFER_SERIALIZE_FORMAT_JSON = HB_TAG('J','S','O','N'), HB_BUFFER_SERIALIZE_FORMAT_INVALID = HB_TAG_NONE } hb_buffer_serialize_format_t; -/* len=-1 means str is NUL-terminated. */ HB_EXTERN hb_buffer_serialize_format_t hb_buffer_serialize_format_from_string (const char *str, int len); @@ -409,24 +432,23 @@ hb_buffer_serialize_format_to_string (hb_buffer_serialize_format_t format); HB_EXTERN const char ** hb_buffer_serialize_list_formats (void); -/* Returns number of items, starting at start, that were serialized. */ HB_EXTERN 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, /* May be NULL */ - hb_font_t *font, /* May be NULL */ + unsigned int *buf_consumed, + hb_font_t *font, hb_buffer_serialize_format_t format, hb_buffer_serialize_flags_t flags); HB_EXTERN hb_bool_t hb_buffer_deserialize_glyphs (hb_buffer_t *buffer, const char *buf, - int buf_len, /* -1 means nul-terminated */ - const char **end_ptr, /* May be NULL */ - hb_font_t *font, /* May be NULL */ + int buf_len, + const char **end_ptr, + hb_font_t *font, hb_buffer_serialize_format_t format); diff --git a/src/hb-shape.cc b/src/hb-shape.cc index 8a9858398..352d42c83 100644 --- a/src/hb-shape.cc +++ b/src/hb-shape.cc @@ -210,13 +210,15 @@ parse_one_feature (const char **pp, const char *end, hb_feature_t *feature) /** * hb_feature_from_string: * @str: (array length=len) (element-type uint8_t): a string to parse - * @len: length of @str, or -1 if string is nul-terminated + * @len: length of @str, or -1 if string is %NULL terminated * @feature: (out): the #hb_feature_t to initialize with the parsed values * - * Parses a string into a #hb_feature_t. If @len is -1 then @str is - * %NULL-terminated. + * Parses a string into a #hb_feature_t. * - * Return value: %TRUE if @str is successfully parsed, %FALSE otherwise + * TODO: document the syntax here. + * + * Return value: + * %true if @str is successfully parsed, %false otherwise. * * Since: 0.9.5 **/