From b111b3de020cde6fb0686efc224cace4608f2e45 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Wed, 10 Apr 2019 15:38:15 -0400 Subject: [PATCH 01/14] Don't use any default unicode funcs if HB_NO_UNICODE_FUNCS is defined Part of https://github.com/harfbuzz/harfbuzz/issues/1652 --- src/hb-unicode.cc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/hb-unicode.cc b/src/hb-unicode.cc index 4ac521d38..d32cace64 100644 --- a/src/hb-unicode.cc +++ b/src/hb-unicode.cc @@ -130,11 +130,11 @@ extern "C" hb_unicode_funcs_t *hb_ucdn_get_unicode_funcs (); hb_unicode_funcs_t * hb_unicode_funcs_get_default () { -#if defined(HAVE_UCDN) +#if !defined(HB_NO_UNICODE_FUNCS) && defined(HAVE_UCDN) return hb_ucdn_get_unicode_funcs (); -#elif defined(HAVE_GLIB) +#elif !defined(HB_NO_UNICODE_FUNCS) && defined(HAVE_GLIB) return hb_glib_get_unicode_funcs (); -#elif defined(HAVE_ICU) && defined(HAVE_ICU_BUILTIN) +#elif !defined(HB_NO_UNICODE_FUNCS) && defined(HAVE_ICU) && defined(HAVE_ICU_BUILTIN) return hb_icu_get_unicode_funcs (); #else #define HB_UNICODE_FUNCS_NIL 1 From 4d31662b5da20790f6f860cec8f5fdabf48210f0 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Wed, 10 Apr 2019 15:40:03 -0400 Subject: [PATCH 02/14] Don't install ot-font funcs on new fonts if HB_NO_OT_FONT defined Currently linker cannot GC hb-ot-font completely because we install it on fonts by default. Don't do that if HB_NO_OT_FONT defined. Part of https://github.com/harfbuzz/harfbuzz/issues/1652 --- src/hb-font.cc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/hb-font.cc b/src/hb-font.cc index 817a1a7b0..20daefd27 100644 --- a/src/hb-font.cc +++ b/src/hb-font.cc @@ -1347,8 +1347,10 @@ hb_font_create (hb_face_t *face) { hb_font_t *font = _hb_font_create (face); +#if !defined(HB_NO_OT_FONT) /* Install our in-house, very lightweight, funcs. */ hb_ot_font_set_funcs (font); +#endif return font; } From edfc6be4a0362efa5c1d39f4792a28b5726c3ce5 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Wed, 10 Apr 2019 15:53:48 -0400 Subject: [PATCH 03/14] [arabic] Disable fallback shaping if HB_NO_OT_SHAPE_COMPLEX_ARABIC_FALLBACK defined Part of https://github.com/harfbuzz/harfbuzz/issues/1652 --- src/hb-ot-shape-complex-arabic-fallback.hh | 1 - src/hb-ot-shape-complex-arabic.cc | 4 ++++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/src/hb-ot-shape-complex-arabic-fallback.hh b/src/hb-ot-shape-complex-arabic-fallback.hh index dad5100ca..ecf345049 100644 --- a/src/hb-ot-shape-complex-arabic-fallback.hh +++ b/src/hb-ot-shape-complex-arabic-fallback.hh @@ -91,7 +91,6 @@ arabic_fallback_synthesize_lookup_single (const hb_ot_shape_plan_t *plan HB_UNUS hb_sorted_array (glyphs, num_glyphs), hb_array (substitutes, num_glyphs)); c.end_serialize (); - /* TODO sanitize the results? */ return ret ? c.copy () : nullptr; } diff --git a/src/hb-ot-shape-complex-arabic.cc b/src/hb-ot-shape-complex-arabic.cc index bdebde0f4..4daf2a666 100644 --- a/src/hb-ot-shape-complex-arabic.cc +++ b/src/hb-ot-shape-complex-arabic.cc @@ -383,6 +383,10 @@ arabic_fallback_shape (const hb_ot_shape_plan_t *plan, hb_font_t *font, hb_buffer_t *buffer) { +#if defined(HB_NO_OT_SHAPE_COMPLEX_ARABIC_FALLBACK) + return; +#endif + const arabic_shape_plan_t *arabic_plan = (const arabic_shape_plan_t *) plan->data; if (!arabic_plan->do_fallback) From 824fd342d5d66584a5ed88951e05975f33c55617 Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Thu, 11 Apr 2019 11:16:01 -0400 Subject: [PATCH 04/14] Rename a few macros --- src/hb-map.hh | 2 +- src/hb-open-type.hh | 10 +++++----- src/hb-set.hh | 2 +- src/hb.hh | 12 ++++++------ 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/hb-map.hh b/src/hb-map.hh index 834a99497..b99fb8f4b 100644 --- a/src/hb-map.hh +++ b/src/hb-map.hh @@ -41,7 +41,7 @@ template struct hb_hashmap_t { - HB_NO_COPY_ASSIGN (hb_hashmap_t); + HB_DELETE_COPY_ASSIGN (hb_hashmap_t); hb_hashmap_t () { init (); } ~hb_hashmap_t () { fini (); } diff --git a/src/hb-open-type.hh b/src/hb-open-type.hh index 761a70f58..379baebd2 100644 --- a/src/hb-open-type.hh +++ b/src/hb-open-type.hh @@ -378,7 +378,7 @@ struct UnsizedArrayOf typedef Type item_t; static constexpr unsigned item_size = hb_static_size (Type); - HB_NO_CREATE_COPY_ASSIGN_TEMPLATE (UnsizedArrayOf, Type); + HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE (UnsizedArrayOf, Type); const Type& operator [] (int i_) const { @@ -534,7 +534,7 @@ struct ArrayOf typedef Type item_t; static constexpr unsigned item_size = hb_static_size (Type); - HB_NO_CREATE_COPY_ASSIGN_TEMPLATE2 (ArrayOf, Type, LenType); + HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2 (ArrayOf, Type, LenType); const Type& operator [] (int i_) const { @@ -715,7 +715,7 @@ struct HeadlessArrayOf { static constexpr unsigned item_size = Type::static_size; - HB_NO_CREATE_COPY_ASSIGN_TEMPLATE2 (HeadlessArrayOf, Type, LenType); + HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2 (HeadlessArrayOf, Type, LenType); const Type& operator [] (int i_) const { @@ -780,7 +780,7 @@ struct HeadlessArrayOf template struct ArrayOfM1 { - HB_NO_CREATE_COPY_ASSIGN_TEMPLATE2 (ArrayOfM1, Type, LenType); + HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2 (ArrayOfM1, Type, LenType); const Type& operator [] (int i_) const { @@ -945,7 +945,7 @@ struct VarSizedBinSearchArrayOf { static constexpr unsigned item_size = Type::static_size; - HB_NO_CREATE_COPY_ASSIGN_TEMPLATE (VarSizedBinSearchArrayOf, Type); + HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE (VarSizedBinSearchArrayOf, Type); bool last_is_terminator () const { diff --git a/src/hb-set.hh b/src/hb-set.hh index 34498d9a8..76100f6bc 100644 --- a/src/hb-set.hh +++ b/src/hb-set.hh @@ -39,7 +39,7 @@ struct hb_set_t { - HB_NO_COPY_ASSIGN (hb_set_t); + HB_DELETE_COPY_ASSIGN (hb_set_t); hb_set_t () { init (); } ~hb_set_t () { fini (); } diff --git a/src/hb.hh b/src/hb.hh index 896b59025..1aef23bf6 100644 --- a/src/hb.hh +++ b/src/hb.hh @@ -408,24 +408,24 @@ static_assert ((sizeof (hb_position_t) == 4), ""); static_assert ((sizeof (hb_mask_t) == 4), ""); static_assert ((sizeof (hb_var_int_t) == 4), ""); -#define HB_NO_COPY_ASSIGN(TypeName) \ +#define HB_DELETE_COPY_ASSIGN(TypeName) \ TypeName(const TypeName&); \ void operator=(const TypeName&) -#define HB_NO_COPY_ASSIGN_TEMPLATE(TypeName, T) \ +#define HB_DELETE_COPY_ASSIGN_TEMPLATE(TypeName, T) \ TypeName(const TypeName&); \ void operator=(const TypeName&) -#define HB_NO_COPY_ASSIGN_TEMPLATE2(TypeName, T1, T2) \ +#define HB_DELETE_COPY_ASSIGN_TEMPLATE2(TypeName, T1, T2) \ TypeName(const TypeName&); \ void operator=(const TypeName&) -#define HB_NO_CREATE_COPY_ASSIGN(TypeName) \ +#define HB_DELETE_CREATE_COPY_ASSIGN(TypeName) \ TypeName(); \ TypeName(const TypeName&); \ void operator=(const TypeName&) -#define HB_NO_CREATE_COPY_ASSIGN_TEMPLATE(TypeName, T) \ +#define HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE(TypeName, T) \ TypeName(); \ TypeName(const TypeName&); \ void operator=(const TypeName&) -#define HB_NO_CREATE_COPY_ASSIGN_TEMPLATE2(TypeName, T1, T2) \ +#define HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2(TypeName, T1, T2) \ TypeName(); \ TypeName(const TypeName&); \ void operator=(const TypeName&) From baf1e79075b0f917b79484446cd2ca47b58f50aa Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Thu, 11 Apr 2019 11:18:04 -0400 Subject: [PATCH 05/14] [C++11] Use deleted methods --- src/hb.hh | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/src/hb.hh b/src/hb.hh index 1aef23bf6..2e381a2eb 100644 --- a/src/hb.hh +++ b/src/hb.hh @@ -409,26 +409,26 @@ static_assert ((sizeof (hb_mask_t) == 4), ""); static_assert ((sizeof (hb_var_int_t) == 4), ""); #define HB_DELETE_COPY_ASSIGN(TypeName) \ - TypeName(const TypeName&); \ - void operator=(const TypeName&) + TypeName(const TypeName&) = delete; \ + void operator=(const TypeName&) = delete #define HB_DELETE_COPY_ASSIGN_TEMPLATE(TypeName, T) \ - TypeName(const TypeName&); \ - void operator=(const TypeName&) + TypeName(const TypeName&) = delete; \ + void operator=(const TypeName&) = delete #define HB_DELETE_COPY_ASSIGN_TEMPLATE2(TypeName, T1, T2) \ - TypeName(const TypeName&); \ - void operator=(const TypeName&) + TypeName(const TypeName&) = delete; \ + void operator=(const TypeName&) = delete #define HB_DELETE_CREATE_COPY_ASSIGN(TypeName) \ - TypeName(); \ - TypeName(const TypeName&); \ - void operator=(const TypeName&) + TypeName() = delete; \ + TypeName(const TypeName&) = delete; \ + void operator=(const TypeName&) = delete #define HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE(TypeName, T) \ - TypeName(); \ - TypeName(const TypeName&); \ - void operator=(const TypeName&) + TypeName() = delete; \ + TypeName(const TypeName&) = delete; \ + void operator=(const TypeName&) = delete #define HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2(TypeName, T1, T2) \ - TypeName(); \ - TypeName(const TypeName&); \ - void operator=(const TypeName&) + TypeName() = delete; \ + TypeName(const TypeName&) = delete; \ + void operator=(const TypeName&) = delete /* From b52c0e54b9855a1f3d400e4dbcd0372520f2c2fc Mon Sep 17 00:00:00 2001 From: Behdad Esfahbod Date: Thu, 11 Apr 2019 11:20:10 -0400 Subject: [PATCH 06/14] Use injected class name to simplify macros --- src/hb-open-type.hh | 10 +++++----- src/hb.hh | 14 -------------- 2 files changed, 5 insertions(+), 19 deletions(-) diff --git a/src/hb-open-type.hh b/src/hb-open-type.hh index 379baebd2..c4707294f 100644 --- a/src/hb-open-type.hh +++ b/src/hb-open-type.hh @@ -378,7 +378,7 @@ struct UnsizedArrayOf typedef Type item_t; static constexpr unsigned item_size = hb_static_size (Type); - HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE (UnsizedArrayOf, Type); + HB_DELETE_CREATE_COPY_ASSIGN (UnsizedArrayOf); const Type& operator [] (int i_) const { @@ -534,7 +534,7 @@ struct ArrayOf typedef Type item_t; static constexpr unsigned item_size = hb_static_size (Type); - HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2 (ArrayOf, Type, LenType); + HB_DELETE_CREATE_COPY_ASSIGN (ArrayOf); const Type& operator [] (int i_) const { @@ -715,7 +715,7 @@ struct HeadlessArrayOf { static constexpr unsigned item_size = Type::static_size; - HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2 (HeadlessArrayOf, Type, LenType); + HB_DELETE_CREATE_COPY_ASSIGN (HeadlessArrayOf); const Type& operator [] (int i_) const { @@ -780,7 +780,7 @@ struct HeadlessArrayOf template struct ArrayOfM1 { - HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2 (ArrayOfM1, Type, LenType); + HB_DELETE_CREATE_COPY_ASSIGN (ArrayOfM1); const Type& operator [] (int i_) const { @@ -945,7 +945,7 @@ struct VarSizedBinSearchArrayOf { static constexpr unsigned item_size = Type::static_size; - HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE (VarSizedBinSearchArrayOf, Type); + HB_DELETE_CREATE_COPY_ASSIGN (VarSizedBinSearchArrayOf); bool last_is_terminator () const { diff --git a/src/hb.hh b/src/hb.hh index 2e381a2eb..4ea10976e 100644 --- a/src/hb.hh +++ b/src/hb.hh @@ -411,24 +411,10 @@ static_assert ((sizeof (hb_var_int_t) == 4), ""); #define HB_DELETE_COPY_ASSIGN(TypeName) \ TypeName(const TypeName&) = delete; \ void operator=(const TypeName&) = delete -#define HB_DELETE_COPY_ASSIGN_TEMPLATE(TypeName, T) \ - TypeName(const TypeName&) = delete; \ - void operator=(const TypeName&) = delete -#define HB_DELETE_COPY_ASSIGN_TEMPLATE2(TypeName, T1, T2) \ - TypeName(const TypeName&) = delete; \ - void operator=(const TypeName&) = delete #define HB_DELETE_CREATE_COPY_ASSIGN(TypeName) \ TypeName() = delete; \ TypeName(const TypeName&) = delete; \ void operator=(const TypeName&) = delete -#define HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE(TypeName, T) \ - TypeName() = delete; \ - TypeName(const TypeName&) = delete; \ - void operator=(const TypeName&) = delete -#define HB_DELETE_CREATE_COPY_ASSIGN_TEMPLATE2(TypeName, T1, T2) \ - TypeName() = delete; \ - TypeName(const TypeName&) = delete; \ - void operator=(const TypeName&) = delete /* From 930f6fc3da04ce1897e65862fccb03afa9d3a780 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Sat, 16 Mar 2019 15:10:21 +0000 Subject: [PATCH 07/14] [Docs] Add inlind gtk-doc comments for hb-ot-layout functions. --- src/hb-ot-layout.cc | 456 +++++++++++++++++++++++++++++++++++++++++++- src/hb-ot-layout.h | 11 ++ 2 files changed, 462 insertions(+), 5 deletions(-) diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index 1365a3e21..02aef6460 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -62,18 +62,50 @@ * kern */ +/** + * hb_ot_layout_has_kerning: + * @face: The #hb_face_t to work on + * + * Tests whether a face includes any kerning data. Examines the 'kern' table. + * + * Return value: true if data found, false otherwise + * + **/ bool hb_ot_layout_has_kerning (hb_face_t *face) { return face->table.kern->has_data (); } + +/** + * hb_ot_layout_has_machine_kerning: + * @face: The #hb_face_t to work on + * + * Tests whether a face includes any state-machine kerning. + * + * Return value: true if data found, false otherwise + * + **/ bool hb_ot_layout_has_machine_kerning (hb_face_t *face) { return face->table.kern->has_state_machine (); } + +/** + * hb_ot_layout_has_cross_kerning: + * @face: The #hb_face_t to work on + * + * Tests whether a face has any cross-stream kerning (i.e., kerns + * that make adjustments perpendicular to the direction of the text + * flow: Y adjustments in horizontal text or X adjustments in + * vertical text). + * + * Return value: true is data found, false otherwise + * + **/ bool hb_ot_layout_has_cross_kerning (hb_face_t *face) { @@ -219,6 +251,15 @@ _hb_ot_layout_set_glyph_props (hb_font_t *font, /* Public API */ +/** + * hb_ot_layout_has_glyph_classes: + * @face: #hb_face_t to work upon + * + * Tests whether a face has any glyph classes defined in its GDEF table. + * + * Return value: true if data found, false otherwise + * + **/ hb_bool_t hb_ot_layout_has_glyph_classes (hb_face_t *face) { @@ -227,6 +268,14 @@ hb_ot_layout_has_glyph_classes (hb_face_t *face) /** * hb_ot_layout_get_glyph_class: + * @face: The #hb_face_t to work on + * @glyph: The #hb_codepoint_t code point to query + * + * Fetches the GDEF class of the requested glyph in the specified face. + * + * Return value: Glyph class (UnclassifiedGlyph, BaseGlyph, LigatureGlyph, MarkGlyph, + * ComponentGlyph) of the given code point in the GDEF table of the + * face. * * Since: 0.9.7 **/ @@ -239,6 +288,13 @@ hb_ot_layout_get_glyph_class (hb_face_t *face, /** * hb_ot_layout_get_glyphs_in_class: + * @face: The #hb_face_t to work on + * @klass: The #hb_ot_layout_glyph_class_t GDEF class to retrieve + * @glyphs: (out): The #hb_set_t set of all glyphs belonging to the requested + * class. + * + * Retrieves the set of all glyphs from the face that belong to the requested + * glyph class in the face's GDEF table. * * Since: 0.9.7 **/ @@ -250,6 +306,22 @@ hb_ot_layout_get_glyphs_in_class (hb_face_t *face, return face->table.GDEF->table->get_glyphs_in_class (klass, glyphs); } + +/** + * hb_ot_layout_get_attach_points: + * @face: The #hb_face_t to work on + * @glyph: The #hb_codepoint_t code point to query + * @start_offset: The offset into the attachment-point array to start returning + * @point_count: (in) The number of attachment points to return + * (out) The number of attachment points returned in the array + * @point_array: (out) The array of attachment points found for the query + * + * Fetches a list of all attachment points for the specified glyph in the GDEF + * table of the face. The list returned will begin at the offset provided. + * + * Useful if the client program wishes to cache the list. + * + **/ unsigned int hb_ot_layout_get_attach_points (hb_face_t *face, hb_codepoint_t glyph, @@ -263,6 +335,21 @@ hb_ot_layout_get_attach_points (hb_face_t *face, point_array); } + +/** + * hb_ot_layout_get_ligature_carets: + * @font: The #hb_font_t to work on + * @direction: The #hb_direction_t text direction to use + * @glyph: The #hb_codepoint_t code point to query + * @start_offset: The offset into the caret array to start returning + * @caret_count: (in) The number of caret positions to return + * (out) The number of caret positions returned in the array + * @caret_array: (out) The array of caret positions found for the query + * + * Fetches a list of the caret positions defined for a ligature glyph in the GDEF + * table of the font. The list returned will begin at the offset provided. + * + **/ unsigned int hb_ot_layout_get_ligature_carets (hb_font_t *font, hb_direction_t direction, @@ -331,6 +418,19 @@ get_gsubgpos_table (hb_face_t *face, } +/** + * hb_ot_layout_table_get_script_tags: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @start_offset: The offset into the script-tag array to start returning + * @script_count: (in) The number of script tags to return + * (out) The number of script tags returned in the array + * @script_tags: (out) The array of #hb_tag_t script tags found for the query + * + * Fetches a list of all scripts enumerated in the specified face's GSUB table + * or GPOS table. The list returned will begin at the offset provided. + * + **/ unsigned int hb_ot_layout_table_get_script_tags (hb_face_t *face, hb_tag_t table_tag, @@ -345,11 +445,24 @@ hb_ot_layout_table_get_script_tags (hb_face_t *face, #define HB_OT_TAG_LATIN_SCRIPT HB_TAG ('l', 'a', 't', 'n') +/** + * hb_ot_layout_table_find_script: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_tag: #hb_tag_t of the script tag requested + * @script_index: (out) The index of the requested script tag + * + * Fetches the index if a given script tag in the specified face's GSUB table + * or GPOS table. + * + * Return value: true if the script is found, false otherwise + * + **/ hb_bool_t hb_ot_layout_table_find_script (hb_face_t *face, hb_tag_t table_tag, hb_tag_t script_tag, - unsigned int *script_index) + unsigned int *script_index /* OUT */) { static_assert ((OT::Index::NOT_FOUND_INDEX == HB_OT_LAYOUT_NO_SCRIPT_INDEX), ""); const OT::GSUBGPOS &g = get_gsubgpos_table (face, table_tag); @@ -375,6 +488,16 @@ hb_ot_layout_table_find_script (hb_face_t *face, return false; } +/** + * hb_ot_layout_table_choose_script: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_tags: Array of #hb_tag_t script tags + * @script_index: The index of the requested script tag + * @chosen_script: #hb_tag_t of the script tag requested + * + * Deprecated + **/ hb_bool_t hb_ot_layout_table_choose_script (hb_face_t *face, hb_tag_t table_tag, @@ -389,6 +512,12 @@ hb_ot_layout_table_choose_script (hb_face_t *face, /** * hb_ot_layout_table_select_script: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_count: Number of script tags in the array + * @script_tags: Array of #hb_tag_t script tags + * @script_index: (out) The index of the requested script + * @chosen_script: (out) #hb_tag_t of the requested script * * Since: 2.0.0 **/ @@ -442,6 +571,19 @@ hb_ot_layout_table_select_script (hb_face_t *face, return false; } + +/** + * hb_ot_layout_table_get_feature_tags: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @start_offset: The offset into the feature-tag array to start returning + * @feature_count: (in) The number of feature tags to return + * (out) The number of feature tags returned in the array + * @feature_tags: (out) Array of feature tags found in the table + * + * Fetches a list of all feature tags in the given face's GSUB or GPOS table. + * + **/ unsigned int hb_ot_layout_table_get_feature_tags (hb_face_t *face, hb_tag_t table_tag, @@ -454,11 +596,24 @@ hb_ot_layout_table_get_feature_tags (hb_face_t *face, return g.get_feature_tags (start_offset, feature_count, feature_tags); } + +/** + * hb_ot_layout_table_find_feature: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @feature_tag: The #hb_tag_t og the requested feature tag + * @feature_index: The index of the requested feature + * + * Fetches the index for a given feature tag in the specified face's GSUB table + * or GPOS table. + * + * Return value: true if the feature is found, false otherwise + **/ bool hb_ot_layout_table_find_feature (hb_face_t *face, hb_tag_t table_tag, hb_tag_t feature_tag, - unsigned int *feature_index) + unsigned int *feature_index /* OUT */) { static_assert ((OT::Index::NOT_FOUND_INDEX == HB_OT_LAYOUT_NO_FEATURE_INDEX), ""); const OT::GSUBGPOS &g = get_gsubgpos_table (face, table_tag); @@ -477,6 +632,20 @@ hb_ot_layout_table_find_feature (hb_face_t *face, } +/** + * hb_ot_layout_script_get_language_tags: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_index: The index of the requested script tag + * @start_offset: The offset into the language-tag array to start returning + * @language_count: (in) The number of language tags to return + * (out) The number of language tags returned in the array + * @language_tags: (out) Array of language tags found in the table + * + * Fetches a list of language tags in the given face's GSUB or GPOS table, underneath + * the specified script index. The list returned will begin at the offset provided. + * + **/ unsigned int hb_ot_layout_script_get_language_tags (hb_face_t *face, hb_tag_t table_tag, @@ -490,6 +659,21 @@ hb_ot_layout_script_get_language_tags (hb_face_t *face, return s.get_lang_sys_tags (start_offset, language_count, language_tags); } + +/** + * hb_ot_layout_script_find_language: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_index: The index of the requested script tag + * @language_tag: The #hb_tag_t of the requested language + * @language_index: The index of the requested language + * + * Fetches the index of a given language tag in the specified face's GSUB table + * or GPOS table, underneath the specified script tag. + * + * Return value: true if the language tag is found, false otherwise + * + **/ hb_bool_t hb_ot_layout_script_find_language (hb_face_t *face, hb_tag_t table_tag, @@ -505,8 +689,21 @@ hb_ot_layout_script_find_language (hb_face_t *face, language_index); } + /** * hb_ot_layout_script_select_language: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_index: The index of the requested script tag + * @language_count: The number of languages in the specified script + * @language_tags: The array of language tags + * @language_index: (out) The index of the requested language + * + * Fetches the index of a given language tag in the specified face's GSUB table + * or GPOS table, underneath the specified script index. + * + * Return value: true if the language tag is found, false otherwise + * * * Since: 2.0.0 **/ @@ -536,6 +733,21 @@ hb_ot_layout_script_select_language (hb_face_t *face, return false; } + +/** + * hb_ot_layout_language_get_required_feature_index: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_index: The index of the requested script tag + * @language_index: The index of the requested language tag + * @feature_index: (out) The index of the requested feature + * + * Fetches the index of a requested feature in the given face's GSUB or GPOS table, + * underneath the specified script and language. + * + * Return value: true if the feature is found, false otherwise + * + **/ hb_bool_t hb_ot_layout_language_get_required_feature_index (hb_face_t *face, hb_tag_t table_tag, @@ -551,8 +763,20 @@ hb_ot_layout_language_get_required_feature_index (hb_face_t *face, nullptr); } + /** * hb_ot_layout_language_get_required_feature: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_index: The index of the requested script tag + * @language_index: The index of the requested language tag + * @feature_index: The index of the requested feature + * @feature_tag: (out) The #hb_tag_t of the requested feature + * + * Fetches the tag of a requested feature index in the given face's GSUB or GPOS table, + * underneath the specified script and language. + * + * Return value: true if the feature is found, false otherwise * * Since: 0.9.30 **/ @@ -574,6 +798,22 @@ hb_ot_layout_language_get_required_feature (hb_face_t *face, return l.has_required_feature (); } + +/** + * hb_ot_layout_language_get_feature_indexes: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_index: The index of the requested script tag + * @language_index: The index of the requested language tag + * @start_offset: The offset into the feature-tag array to start returning + * @feature_count: (in) The number of feature tags to return + * (out) The number of feature tags returned in the array + * @feature_indexes: (out) The array of feature indexes found for the query + * + * Fetches a list of all features in the specified face's GSUB table + * or GPOS table, underneath the specified script and language. The list + * returned will begin at the offset provided. + **/ unsigned int hb_ot_layout_language_get_feature_indexes (hb_face_t *face, hb_tag_t table_tag, @@ -589,6 +829,23 @@ hb_ot_layout_language_get_feature_indexes (hb_face_t *face, return l.get_feature_indexes (start_offset, feature_count, feature_indexes); } + +/** + * hb_ot_layout_language_get_feature_tags: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_index: The index of the requested script tag + * @language_index: The index of the requested language tag + * @start_offset: The offset into the feature-tag array to start returning + * @feature_count: (in) The number of feature tags to return + * (out) The number of feature tags returned in the array + * @feature_tags: (out ) The array of #hb_tag_t feature tags found for the query + * + * Fetches a list of all features in the specified face's GSUB table + * or GPOS table, underneath the specified script and language. The list + * returned will begin at the offset provided. + * + **/ unsigned int hb_ot_layout_language_get_feature_tags (hb_face_t *face, hb_tag_t table_tag, @@ -614,13 +871,28 @@ hb_ot_layout_language_get_feature_tags (hb_face_t *face, } +/** + * hb_ot_layout_language_find_feature: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @script_index: The index of the requested script tag + * @language_index: The index of the requested language tag + * @feature_tag: #hb_tag_t of the feature tag requested + * @feature_index: (out) The index of the requested feature + * + * Fetches the index of a given feature tag in the specified face's GSUB table + * or GPOS table, underneath the specified script and language. + * + * Return value: true if the feature is found, false otherwise + * + **/ hb_bool_t hb_ot_layout_language_find_feature (hb_face_t *face, hb_tag_t table_tag, unsigned int script_index, unsigned int language_index, hb_tag_t feature_tag, - unsigned int *feature_index) + unsigned int *feature_index /* OUT */) { static_assert ((OT::Index::NOT_FOUND_INDEX == HB_OT_LAYOUT_NO_FEATURE_INDEX), ""); const OT::GSUBGPOS &g = get_gsubgpos_table (face, table_tag); @@ -640,8 +912,20 @@ hb_ot_layout_language_find_feature (hb_face_t *face, return false; } + /** * hb_ot_layout_feature_get_lookups: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @feature_index: The index of the requested feature + * @start_offset: The offset into the lookup array to start returning + * @lookup_count: (in) The number of lookups to return + * (out) The number of lookups returned in the array + * @lookup_indexes: (out) The array of lookup indexes found for the query + * + * Fetches a list of all lookups enumerated for the specified feature, in + * the specified face's GSUB table or GPOS table. The list returned will + * begin at the offset provided. * * Since: 0.9.7 **/ @@ -662,8 +946,14 @@ hb_ot_layout_feature_get_lookups (hb_face_t *face, lookup_indexes); } + /** * hb_ot_layout_table_get_lookup_count: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * + * Fetches the total number of lookups enumerated in the specified + * face's GSUB table or GPOS table. * * Since: 0.9.22 **/ @@ -805,8 +1095,21 @@ script_collect_features (hb_collect_features_context_t *c, } } + /** * hb_ot_layout_collect_features: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @scripts: The array of scripts to collect features for + * @languages: The array of languages to collect features for + * @features: The array of features to collect + * @feature_indexes: (out) The array of feature indexes found for the query + * + * Fetches a list of all feature indexes in the specified face's GSUB table + * or GPOS table, underneath the specified scripts, languages, and features. + * If no list of scripts is provided, all scripts will be queried. If no list + * of languages is provided, all languages will be queried. If no list of + * features is provided, all features will be queried. * * Since: 1.8.5 **/ @@ -843,8 +1146,21 @@ hb_ot_layout_collect_features (hb_face_t *face, } } + /** * hb_ot_layout_collect_lookups: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @scripts: The array of scripts to collect lookups for + * @languages: The array of languages to collect lookups for + * @features: The array of features to collect lookups for + * @lookup_indexes:: (out) The array of lookup indexes found for the query + * + * Fetches a list of all feature-lookup indexes in the specified face's GSUB + * table or GPOS table, underneath the specified scripts, languages, and + * features. If no list of scripts is provided, all scripts will be queried. + * If no list of languages is provided, all languages will be queried. If no + * list of features is provided, all features will be queried. * * Since: 0.9.8 **/ @@ -866,8 +1182,19 @@ hb_ot_layout_collect_lookups (hb_face_t *face, g.get_feature (feature_index).add_lookup_indexes_to (lookup_indexes); } + /** * hb_ot_layout_lookup_collect_glyphs: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @lookup_index: The index of the feature lookup to query + * @glyphs_before: (out) Array of glyphs preceding the substitution range + * @glyphs_input: (out) Array of input glyphs that would be substituted by the lookup + * @glyphs_after: (out) Array of glyphs following the substition range + * @glyphs_output: (out) Array of glyphs that would be the substitued output of the lookup + * + * Fetches a list of all glyphs affected by the specified lookup in the + * specified face's GSUB table of GPOS table. * * Since: 0.9.7 **/ @@ -906,6 +1233,19 @@ hb_ot_layout_lookup_collect_glyphs (hb_face_t *face, /* Variations support */ + +/** + * hb_ot_layout_table_find_feature_variations: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @coords: The variation coordinates to query + * @num_coords: The number of variation coorinates + * variations_index: (out) The array of feature variations found for the query + * + * Fetches a list of feature variations in the specified face's GSUB table + * or GPOS table, at the specified variation coordinates. + * + **/ hb_bool_t hb_ot_layout_table_find_feature_variations (hb_face_t *face, hb_tag_t table_tag, @@ -918,6 +1258,23 @@ hb_ot_layout_table_find_feature_variations (hb_face_t *face, return g.find_variations_index (coords, num_coords, variations_index); } + +/** + * hb_ot_layout_feature_with_variations_get_lookups: + * @face: #hb_face_t to work upon + * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS + * @feature_index: The index of the feature to query + * @variations_index: The index of the feature variation to query + * @start_offset: The offset into the lookup array to start returning + * @lookup_count: (in) The number of lookups to return + * (out) The number of lookups returned in the array + * @lookup_indexes: (out) The array of lookups found for the query + * + * Fetches a list of all lookups enumerated for the specified feature, in + * the specified face's GSUB table or GPOS table, enabled at the specified + * variations index. The list returned will begin at the offset provided. + * + **/ unsigned int hb_ot_layout_feature_with_variations_get_lookups (hb_face_t *face, hb_tag_t table_tag, @@ -940,14 +1297,35 @@ hb_ot_layout_feature_with_variations_get_lookups (hb_face_t *face, * OT::GSUB */ + +/** + * hb_ot_layout_has_substitution: + * @face: #hb_face_t to work upon + * + * Tests whether the specified face includes any GSUB substitutions. + * + * Return value: true if data found, false otherwise + * + **/ hb_bool_t hb_ot_layout_has_substitution (hb_face_t *face) { return face->table.GSUB->table->has_data (); } + /** * hb_ot_layout_lookup_would_substitute: + * @face: #hb_face_t to work upon + * @lookup_index: The index of the lookup to query + * @glyphs: The sequence of glyphs to query for substitution + * @glyphs_length: The length of the glyph sequence + * @zero_context: #hb_bool_t indicating whether substitutions should be context-free + * + * Tests whether a specified lookup in the specified face would + * trigger a substitution on the given glyph sequence. + * + * Return value: true if a substitution would be triggered, false otherwise * * Since: 0.9.7 **/ @@ -966,6 +1344,15 @@ hb_ot_layout_lookup_would_substitute (hb_face_t *face, return l.would_apply (&c, &face->table.GSUB->accels[lookup_index]); } + +/** + * hb_ot_layout_substitute_start: + * @font: #hb_font_t to use + * @buffer: #hb_buffer_t buffer to work upon + * + * Begins + * + **/ void hb_ot_layout_substitute_start (hb_font_t *font, hb_buffer_t *buffer) @@ -1025,13 +1412,19 @@ hb_ot_layout_delete_glyphs_inplace (hb_buffer_t *buffer, /** * hb_ot_layout_lookup_substitute_closure: + * @face: #hb_face_t to work upon + * @lookup_index: index of the feature lookup to query + * @glyphs: (out) Array of glyphs comprising the transitive closure of the lookup + * + * Compute the transitive closure of glyphs needed for a + * specified lookup. * * Since: 0.9.7 **/ void hb_ot_layout_lookup_substitute_closure (hb_face_t *face, unsigned int lookup_index, - hb_set_t *glyphs) + hb_set_t *glyphs /* OUT */) { hb_map_t done_lookups; OT::hb_closure_context_t c (face, glyphs, &done_lookups); @@ -1043,6 +1436,9 @@ hb_ot_layout_lookup_substitute_closure (hb_face_t *face, /** * hb_ot_layout_lookups_substitute_closure: + * @face: #hb_face_t to work upon + * @lookups: The set of lookups to query + * @glyphs: (out) Array of glyphs comprising the transitive closure of the lookups * * Compute the transitive closure of glyphs needed for all of the * provided lookups. @@ -1052,7 +1448,7 @@ hb_ot_layout_lookup_substitute_closure (hb_face_t *face, void hb_ot_layout_lookups_substitute_closure (hb_face_t *face, const hb_set_t *lookups, - hb_set_t *glyphs) + hb_set_t *glyphs /* OUT */) { hb_map_t done_lookups; OT::hb_closure_context_t c (face, glyphs, &done_lookups); @@ -1081,18 +1477,39 @@ hb_ot_layout_lookups_substitute_closure (hb_face_t *face, * OT::GPOS */ + +/** + * hb_ot_layout_has_positioning: + * @face: #hb_face_t to work upon + * + * Return value: true if the face has GPOS data, false otherwise + * + **/ hb_bool_t hb_ot_layout_has_positioning (hb_face_t *face) { return face->table.GPOS->table->has_data (); } +/** + * hb_ot_layout_position_start: + * @font: #hb_font_t to use + * @buffer: #hb_buffer_t buffer to work upon + * + **/ void hb_ot_layout_position_start (hb_font_t *font, hb_buffer_t *buffer) { OT::GPOS::position_start (font, buffer); } + +/** + * hb_ot_layout_position_finish_advances: + * @font: #hb_font_t to use + * @buffer: #hb_buffer_t buffer to work upon + * + **/ void hb_ot_layout_position_finish_advances (hb_font_t *font, hb_buffer_t *buffer) { @@ -1105,8 +1522,19 @@ hb_ot_layout_position_finish_offsets (hb_font_t *font, hb_buffer_t *buffer) OT::GPOS::position_finish_offsets (font, buffer); } + /** * hb_ot_layout_get_size_params: + * @face: #hb_face_t to work upon + * @design_size: (out) The design size of the face + * @subfamily_id: (out) The identifier of the face within the font subfamily + * @subfamily_name_id: (out) The ‘name’ table name ID of the face within the font subfamily + * @range_start: (out) The small end of the recommended size range for the face + * @range_end: (out) The big end of the recommended size range for the face + * + * Fetches optical-size feature data (i.e., the `size` feature from GPOS). + * + * Return value: true if data found, false otherwise * * Since: 0.9.10 **/ @@ -1151,6 +1579,7 @@ hb_ot_layout_get_size_params (hb_face_t *face, return false; } + /** * hb_ot_layout_feature_get_name_ids: * @face: #hb_face_t to work upon @@ -1226,6 +1655,7 @@ hb_ot_layout_feature_get_name_ids (hb_face_t *face, return false; } + /** * hb_ot_layout_feature_get_characters: * @face: #hb_face_t to work upon @@ -1507,6 +1937,22 @@ typedef enum { HB_OT_LAYOUT_BASELINE_ROMN = HB_TAG('r','o','m','n') } hb_ot_layout_baseline_t; + +/** + * hb_ot_layout_get_baseline: + * @font: The #hb_font_t to work upon + * @baseline: The #hb_ot_layout_baseline_t to query + * @direction: The #hb_direction_t text direction to use + * @script_tag: #hb_tag_t of the script to use + * @language_tag: #hb_tag_t of the language to use + * @coord: (out) The position of the requested baseline + * + * Fetches the coordinates of the specified baseline in the face, underneath + * the specified script and language and in the specified text direction. + * + * Return value: true if the baseline is found for the settings queried, false otherwise + * + **/ HB_EXTERN hb_bool_t hb_ot_layout_get_baseline (hb_font_t *font, hb_ot_layout_baseline_t baseline, diff --git a/src/hb-ot-layout.h b/src/hb-ot-layout.h index e47395412..2ffc24786 100644 --- a/src/hb-ot-layout.h +++ b/src/hb-ot-layout.h @@ -93,6 +93,17 @@ hb_ot_tags_to_script_and_language (hb_tag_t script_tag, HB_EXTERN hb_bool_t hb_ot_layout_has_glyph_classes (hb_face_t *face); +/** + * hb_ot_layout_get_glyph_class: + * @HB_OT_LAYOUT_GLYPH_CLASS_UNCLASSIFIED: + * @HB_OT_LAYOUT_GLYPH_CLASS_BASE_GLYPH: + * @HB_OT_LAYOUT_GLYPH_CLASS_LIGATURE: + * @HB_OT_LAYOUT_GLYPH_CLASS_MARK: + * @HB_OT_LAYOUT_GLYPH_CLASS_COMPONENT: + * + * The layout classes defined for glyphs. + * + **/ typedef enum { HB_OT_LAYOUT_GLYPH_CLASS_UNCLASSIFIED = 0, HB_OT_LAYOUT_GLYPH_CLASS_BASE_GLYPH = 1, From 3449031fad9dff7acedde7dceb0e47db708fc025 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Sat, 16 Mar 2019 15:38:08 +0000 Subject: [PATCH 08/14] [Docs] Add inline gtk-doc documentation of GDEF glyph classes. --- src/hb-ot-layout.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/hb-ot-layout.h b/src/hb-ot-layout.h index 2ffc24786..359ee1b6f 100644 --- a/src/hb-ot-layout.h +++ b/src/hb-ot-layout.h @@ -95,13 +95,13 @@ hb_ot_layout_has_glyph_classes (hb_face_t *face); /** * hb_ot_layout_get_glyph_class: - * @HB_OT_LAYOUT_GLYPH_CLASS_UNCLASSIFIED: - * @HB_OT_LAYOUT_GLYPH_CLASS_BASE_GLYPH: - * @HB_OT_LAYOUT_GLYPH_CLASS_LIGATURE: - * @HB_OT_LAYOUT_GLYPH_CLASS_MARK: - * @HB_OT_LAYOUT_GLYPH_CLASS_COMPONENT: + * @HB_OT_LAYOUT_GLYPH_CLASS_UNCLASSIFIED: Glyphs not matching the other classifications + * @HB_OT_LAYOUT_GLYPH_CLASS_BASE_GLYPH: Spacing, single characters, capable of accepting marks + * @HB_OT_LAYOUT_GLYPH_CLASS_LIGATURE: Glyphs that represent ligation of multiple characters + * @HB_OT_LAYOUT_GLYPH_CLASS_MARK: Non-spacing, combining glyphs that represent marks + * @HB_OT_LAYOUT_GLYPH_CLASS_COMPONENT: Spacing glyphs that represent part of a single character * - * The layout classes defined for glyphs. + * The GDEF classes defined for glyphs. * **/ typedef enum { From d3178aa52ae822ac6af606027ac8150ded0a2966 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Sun, 17 Mar 2019 14:27:27 +0000 Subject: [PATCH 09/14] [Docs] Fix gtk-doc references to 'kern' table functions, clarifying that GPOS is not examined. --- src/hb-ot-layout.cc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index 02aef6460..7374ea69c 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -66,7 +66,8 @@ * hb_ot_layout_has_kerning: * @face: The #hb_face_t to work on * - * Tests whether a face includes any kerning data. Examines the 'kern' table. + * Tests whether a face includes any kerning data in the 'kern' table. + * Does NOT test for kerning lookups in the GPOS table. * * Return value: true if data found, false otherwise * @@ -82,7 +83,8 @@ hb_ot_layout_has_kerning (hb_face_t *face) * hb_ot_layout_has_machine_kerning: * @face: The #hb_face_t to work on * - * Tests whether a face includes any state-machine kerning. + * Tests whether a face includes any state-machine kerning in the 'kern' table. + * Does NOT examine the GPOS table. * * Return value: true if data found, false otherwise * @@ -101,7 +103,9 @@ hb_ot_layout_has_machine_kerning (hb_face_t *face) * Tests whether a face has any cross-stream kerning (i.e., kerns * that make adjustments perpendicular to the direction of the text * flow: Y adjustments in horizontal text or X adjustments in - * vertical text). + * vertical text) in the 'kern' table. + * + * Does NOT examine the GPOS table. * * Return value: true is data found, false otherwise * From 5122805c740961d4fdfbff440ed68792b63d50ed Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Sun, 17 Mar 2019 14:43:06 +0000 Subject: [PATCH 10/14] [Docs] Fix gtk-doc formatting for (out) and (inout). --- src/hb-ot-layout.cc | 108 ++++++++++++++++++++++---------------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index 7374ea69c..381c69a89 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -316,9 +316,9 @@ hb_ot_layout_get_glyphs_in_class (hb_face_t *face, * @face: The #hb_face_t to work on * @glyph: The #hb_codepoint_t code point to query * @start_offset: The offset into the attachment-point array to start returning - * @point_count: (in) The number of attachment points to return - * (out) The number of attachment points returned in the array - * @point_array: (out) The array of attachment points found for the query + * @point_count: (inout): The number of attachment points to return as input; + * The number of attachment points returned in the array as output + * @point_array: (out): The array of attachment points found for the query * * Fetches a list of all attachment points for the specified glyph in the GDEF * table of the face. The list returned will begin at the offset provided. @@ -346,9 +346,9 @@ hb_ot_layout_get_attach_points (hb_face_t *face, * @direction: The #hb_direction_t text direction to use * @glyph: The #hb_codepoint_t code point to query * @start_offset: The offset into the caret array to start returning - * @caret_count: (in) The number of caret positions to return - * (out) The number of caret positions returned in the array - * @caret_array: (out) The array of caret positions found for the query + * @caret_count: (inout): The number of caret positions to return as input; + * The number of caret positions returned in the array as output + * @caret_array: (out): The array of caret positions found for the query * * Fetches a list of the caret positions defined for a ligature glyph in the GDEF * table of the font. The list returned will begin at the offset provided. @@ -427,9 +427,9 @@ get_gsubgpos_table (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @start_offset: The offset into the script-tag array to start returning - * @script_count: (in) The number of script tags to return - * (out) The number of script tags returned in the array - * @script_tags: (out) The array of #hb_tag_t script tags found for the query + * @script_count: (inout): The number of script tags to return as input; + * The number of script tags returned in the array as output + * @script_tags: (out): The array of #hb_tag_t script tags found for the query * * Fetches a list of all scripts enumerated in the specified face's GSUB table * or GPOS table. The list returned will begin at the offset provided. @@ -454,7 +454,7 @@ hb_ot_layout_table_get_script_tags (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @script_tag: #hb_tag_t of the script tag requested - * @script_index: (out) The index of the requested script tag + * @script_index: (out): The index of the requested script tag * * Fetches the index if a given script tag in the specified face's GSUB table * or GPOS table. @@ -520,8 +520,8 @@ hb_ot_layout_table_choose_script (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @script_count: Number of script tags in the array * @script_tags: Array of #hb_tag_t script tags - * @script_index: (out) The index of the requested script - * @chosen_script: (out) #hb_tag_t of the requested script + * @script_index: (out): The index of the requested script + * @chosen_script: (out): #hb_tag_t of the requested script * * Since: 2.0.0 **/ @@ -581,9 +581,9 @@ hb_ot_layout_table_select_script (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @start_offset: The offset into the feature-tag array to start returning - * @feature_count: (in) The number of feature tags to return - * (out) The number of feature tags returned in the array - * @feature_tags: (out) Array of feature tags found in the table + * @feature_count: (inout): The number of feature tags to return as input; + * The number of feature tags returned in the array as output + * @feature_tags: (out): Array of feature tags found in the table * * Fetches a list of all feature tags in the given face's GSUB or GPOS table. * @@ -606,7 +606,7 @@ hb_ot_layout_table_get_feature_tags (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @feature_tag: The #hb_tag_t og the requested feature tag - * @feature_index: The index of the requested feature + * @feature_index: (out): The index of the requested feature * * Fetches the index for a given feature tag in the specified face's GSUB table * or GPOS table. @@ -642,9 +642,9 @@ hb_ot_layout_table_find_feature (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @script_index: The index of the requested script tag * @start_offset: The offset into the language-tag array to start returning - * @language_count: (in) The number of language tags to return - * (out) The number of language tags returned in the array - * @language_tags: (out) Array of language tags found in the table + * @language_count: (inout): The number of language tags to return as input; + * The number of language tags returned in the array as output + * @language_tags: (out): Array of language tags found in the table * * Fetches a list of language tags in the given face's GSUB or GPOS table, underneath * the specified script index. The list returned will begin at the offset provided. @@ -701,7 +701,7 @@ hb_ot_layout_script_find_language (hb_face_t *face, * @script_index: The index of the requested script tag * @language_count: The number of languages in the specified script * @language_tags: The array of language tags - * @language_index: (out) The index of the requested language + * @language_index: (out): The index of the requested language * * Fetches the index of a given language tag in the specified face's GSUB table * or GPOS table, underneath the specified script index. @@ -744,7 +744,7 @@ hb_ot_layout_script_select_language (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @script_index: The index of the requested script tag * @language_index: The index of the requested language tag - * @feature_index: (out) The index of the requested feature + * @feature_index: (out): The index of the requested feature * * Fetches the index of a requested feature in the given face's GSUB or GPOS table, * underneath the specified script and language. @@ -775,7 +775,7 @@ hb_ot_layout_language_get_required_feature_index (hb_face_t *face, * @script_index: The index of the requested script tag * @language_index: The index of the requested language tag * @feature_index: The index of the requested feature - * @feature_tag: (out) The #hb_tag_t of the requested feature + * @feature_tag: (out): The #hb_tag_t of the requested feature * * Fetches the tag of a requested feature index in the given face's GSUB or GPOS table, * underneath the specified script and language. @@ -810,9 +810,9 @@ hb_ot_layout_language_get_required_feature (hb_face_t *face, * @script_index: The index of the requested script tag * @language_index: The index of the requested language tag * @start_offset: The offset into the feature-tag array to start returning - * @feature_count: (in) The number of feature tags to return - * (out) The number of feature tags returned in the array - * @feature_indexes: (out) The array of feature indexes found for the query + * @feature_count: (inout): The number of feature tags to return as input; + * The number of feature tags returned in the array as output + * @feature_indexes: (out): The array of feature indexes found for the query * * Fetches a list of all features in the specified face's GSUB table * or GPOS table, underneath the specified script and language. The list @@ -841,8 +841,8 @@ hb_ot_layout_language_get_feature_indexes (hb_face_t *face, * @script_index: The index of the requested script tag * @language_index: The index of the requested language tag * @start_offset: The offset into the feature-tag array to start returning - * @feature_count: (in) The number of feature tags to return - * (out) The number of feature tags returned in the array + * @feature_count: (inout): The number of feature tags to return as input; + * The number of feature tags returned in the array as output * @feature_tags: (out ) The array of #hb_tag_t feature tags found for the query * * Fetches a list of all features in the specified face's GSUB table @@ -882,7 +882,7 @@ hb_ot_layout_language_get_feature_tags (hb_face_t *face, * @script_index: The index of the requested script tag * @language_index: The index of the requested language tag * @feature_tag: #hb_tag_t of the feature tag requested - * @feature_index: (out) The index of the requested feature + * @feature_index: (out): The index of the requested feature * * Fetches the index of a given feature tag in the specified face's GSUB table * or GPOS table, underneath the specified script and language. @@ -923,9 +923,9 @@ hb_ot_layout_language_find_feature (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @feature_index: The index of the requested feature * @start_offset: The offset into the lookup array to start returning - * @lookup_count: (in) The number of lookups to return - * (out) The number of lookups returned in the array - * @lookup_indexes: (out) The array of lookup indexes found for the query + * @lookup_count: (inout): The number of lookups to return as input; + * The number of lookups returned in the array as output + * @lookup_indexes: (out): The array of lookup indexes found for the query * * Fetches a list of all lookups enumerated for the specified feature, in * the specified face's GSUB table or GPOS table. The list returned will @@ -1107,7 +1107,7 @@ script_collect_features (hb_collect_features_context_t *c, * @scripts: The array of scripts to collect features for * @languages: The array of languages to collect features for * @features: The array of features to collect - * @feature_indexes: (out) The array of feature indexes found for the query + * @feature_indexes: (out): The array of feature indexes found for the query * * Fetches a list of all feature indexes in the specified face's GSUB table * or GPOS table, underneath the specified scripts, languages, and features. @@ -1158,7 +1158,7 @@ hb_ot_layout_collect_features (hb_face_t *face, * @scripts: The array of scripts to collect lookups for * @languages: The array of languages to collect lookups for * @features: The array of features to collect lookups for - * @lookup_indexes:: (out) The array of lookup indexes found for the query + * @lookup_indexes: (out): The array of lookup indexes found for the query * * Fetches a list of all feature-lookup indexes in the specified face's GSUB * table or GPOS table, underneath the specified scripts, languages, and @@ -1192,10 +1192,10 @@ hb_ot_layout_collect_lookups (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @lookup_index: The index of the feature lookup to query - * @glyphs_before: (out) Array of glyphs preceding the substitution range - * @glyphs_input: (out) Array of input glyphs that would be substituted by the lookup - * @glyphs_after: (out) Array of glyphs following the substition range - * @glyphs_output: (out) Array of glyphs that would be the substitued output of the lookup + * @glyphs_before: (out): Array of glyphs preceding the substitution range + * @glyphs_input: (out): Array of input glyphs that would be substituted by the lookup + * @glyphs_after: (out): Array of glyphs following the substition range + * @glyphs_output: (out): Array of glyphs that would be the substitued output of the lookup * * Fetches a list of all glyphs affected by the specified lookup in the * specified face's GSUB table of GPOS table. @@ -1244,7 +1244,7 @@ hb_ot_layout_lookup_collect_glyphs (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @coords: The variation coordinates to query * @num_coords: The number of variation coorinates - * variations_index: (out) The array of feature variations found for the query + * variations_index: (out): The array of feature variations found for the query * * Fetches a list of feature variations in the specified face's GSUB table * or GPOS table, at the specified variation coordinates. @@ -1270,9 +1270,9 @@ hb_ot_layout_table_find_feature_variations (hb_face_t *face, * @feature_index: The index of the feature to query * @variations_index: The index of the feature variation to query * @start_offset: The offset into the lookup array to start returning - * @lookup_count: (in) The number of lookups to return - * (out) The number of lookups returned in the array - * @lookup_indexes: (out) The array of lookups found for the query + * @lookup_count: (inout): The number of lookups to return as input; + * The number of lookups returned in the array as output + * @lookup_indexes: (out): The array of lookups found for the query * * Fetches a list of all lookups enumerated for the specified feature, in * the specified face's GSUB table or GPOS table, enabled at the specified @@ -1418,7 +1418,7 @@ hb_ot_layout_delete_glyphs_inplace (hb_buffer_t *buffer, * hb_ot_layout_lookup_substitute_closure: * @face: #hb_face_t to work upon * @lookup_index: index of the feature lookup to query - * @glyphs: (out) Array of glyphs comprising the transitive closure of the lookup + * @glyphs: (out): Array of glyphs comprising the transitive closure of the lookup * * Compute the transitive closure of glyphs needed for a * specified lookup. @@ -1442,7 +1442,7 @@ hb_ot_layout_lookup_substitute_closure (hb_face_t *face, * hb_ot_layout_lookups_substitute_closure: * @face: #hb_face_t to work upon * @lookups: The set of lookups to query - * @glyphs: (out) Array of glyphs comprising the transitive closure of the lookups + * @glyphs: (out): Array of glyphs comprising the transitive closure of the lookups * * Compute the transitive closure of glyphs needed for all of the * provided lookups. @@ -1530,11 +1530,11 @@ hb_ot_layout_position_finish_offsets (hb_font_t *font, hb_buffer_t *buffer) /** * hb_ot_layout_get_size_params: * @face: #hb_face_t to work upon - * @design_size: (out) The design size of the face - * @subfamily_id: (out) The identifier of the face within the font subfamily - * @subfamily_name_id: (out) The ‘name’ table name ID of the face within the font subfamily - * @range_start: (out) The small end of the recommended size range for the face - * @range_end: (out) The big end of the recommended size range for the face + * @design_size: (out): The design size of the face + * @subfamily_id: (out): The identifier of the face within the font subfamily + * @subfamily_name_id: (out): The ‘name’ table name ID of the face within the font subfamily + * @range_start: (out): The small end of the recommended size range for the face + * @range_end: (out): The big end of the recommended size range for the face * * Fetches optical-size feature data (i.e., the `size` feature from GPOS). * @@ -1589,15 +1589,15 @@ hb_ot_layout_get_size_params (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: table tag to query, "GSUB" or "GPOS". * @feature_index: index of feature to query. - * @label_id: (out) (allow-none): The ‘name’ table name ID that specifies a string + * @label_id: (out): (allow-none): The ‘name’ table name ID that specifies a string * for a user-interface label for this feature. (May be NULL.) - * @tooltip_id: (out) (allow-none): The ‘name’ table name ID that specifies a string + * @tooltip_id: (out): (allow-none): The ‘name’ table name ID that specifies a string * that an application can use for tooltip text for this * feature. (May be NULL.) - * @sample_id: (out) (allow-none): The ‘name’ table name ID that specifies sample text + * @sample_id: (out): (allow-none): The ‘name’ table name ID that specifies sample text * that illustrates the effect of this feature. (May be NULL.) - * @num_named_parameters: (out) (allow-none): Number of named parameters. (May be zero.) - * @first_param_id: (out) (allow-none): The first ‘name’ table name ID used to specify + * @num_named_parameters: (out): (allow-none): Number of named parameters. (May be zero.) + * @first_param_id: (out): (allow-none): The first ‘name’ table name ID used to specify * strings for user-interface labels for the feature * parameters. (Must be zero if numParameters is zero.) * @@ -1949,7 +1949,7 @@ typedef enum { * @direction: The #hb_direction_t text direction to use * @script_tag: #hb_tag_t of the script to use * @language_tag: #hb_tag_t of the language to use - * @coord: (out) The position of the requested baseline + * @coord: (out): The position of the requested baseline * * Fetches the coordinates of the specified baseline in the face, underneath * the specified script and language and in the specified text direction. From 6c0a1e8cd67144d20c8b5fcad23953910eeeea51 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Sun, 17 Mar 2019 14:50:47 +0000 Subject: [PATCH 11/14] [Docs] Annotate gtk-doc formatting with some un-annotated (out)s. --- src/hb-ot-layout.cc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index 381c69a89..f7006df46 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -497,8 +497,8 @@ hb_ot_layout_table_find_script (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @script_tags: Array of #hb_tag_t script tags - * @script_index: The index of the requested script tag - * @chosen_script: #hb_tag_t of the script tag requested + * @script_index: (out): The index of the requested script tag + * @chosen_script: (out): #hb_tag_t of the script tag requested * * Deprecated **/ @@ -506,8 +506,8 @@ hb_bool_t hb_ot_layout_table_choose_script (hb_face_t *face, hb_tag_t table_tag, const hb_tag_t *script_tags, - unsigned int *script_index, - hb_tag_t *chosen_script) + unsigned int *script_index /* OUT */, + hb_tag_t *chosen_script /* OUT */) { const hb_tag_t *t; for (t = script_tags; *t; t++); From af5230bce39020cf6fc87ee5e21cca3ba201a417 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 18 Mar 2019 14:03:16 +0000 Subject: [PATCH 12/14] [Docs] Minor; fix formatting for gtk-doc multiple-annotations. --- src/hb-ot-layout.cc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index f7006df46..16ef7115d 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -843,7 +843,7 @@ hb_ot_layout_language_get_feature_indexes (hb_face_t *face, * @start_offset: The offset into the feature-tag array to start returning * @feature_count: (inout): The number of feature tags to return as input; * The number of feature tags returned in the array as output - * @feature_tags: (out ) The array of #hb_tag_t feature tags found for the query + * @feature_tags: (out): The array of #hb_tag_t feature tags found for the query * * Fetches a list of all features in the specified face's GSUB table * or GPOS table, underneath the specified script and language. The list @@ -1589,15 +1589,15 @@ hb_ot_layout_get_size_params (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: table tag to query, "GSUB" or "GPOS". * @feature_index: index of feature to query. - * @label_id: (out): (allow-none): The ‘name’ table name ID that specifies a string + * @label_id: (out) (allow-none): The ‘name’ table name ID that specifies a string * for a user-interface label for this feature. (May be NULL.) - * @tooltip_id: (out): (allow-none): The ‘name’ table name ID that specifies a string + * @tooltip_id: (out) (allow-none): The ‘name’ table name ID that specifies a string * that an application can use for tooltip text for this * feature. (May be NULL.) - * @sample_id: (out): (allow-none): The ‘name’ table name ID that specifies sample text + * @sample_id: (out) (allow-none): The ‘name’ table name ID that specifies sample text * that illustrates the effect of this feature. (May be NULL.) - * @num_named_parameters: (out): (allow-none): Number of named parameters. (May be zero.) - * @first_param_id: (out): (allow-none): The first ‘name’ table name ID used to specify + * @num_named_parameters: (out) (allow-none): Number of named parameters. (May be zero.) + * @first_param_id: (out) (allow-none): The first ‘name’ table name ID used to specify * strings for user-interface labels for the feature * parameters. (Must be zero if numParameters is zero.) * From c08ddbd91b7f0fffe761638a2ee4893304b012db Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Sun, 24 Mar 2019 15:07:07 +0000 Subject: [PATCH 13/14] [Docs] Minor edits to gtk-doc inline comment review. --- src/hb-ot-layout.cc | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index 16ef7115d..c0b68229d 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -277,9 +277,8 @@ hb_ot_layout_has_glyph_classes (hb_face_t *face) * * Fetches the GDEF class of the requested glyph in the specified face. * - * Return value: Glyph class (UnclassifiedGlyph, BaseGlyph, LigatureGlyph, MarkGlyph, - * ComponentGlyph) of the given code point in the GDEF table of the - * face. + * Return value: The #hb_ot_layout_glyph_class_t glyph class of the given code + * point in the GDEF table of the face. * * Since: 0.9.7 **/ @@ -500,7 +499,7 @@ hb_ot_layout_table_find_script (hb_face_t *face, * @script_index: (out): The index of the requested script tag * @chosen_script: (out): #hb_tag_t of the script tag requested * - * Deprecated + * Deprecated since 2.0.0 **/ hb_bool_t hb_ot_layout_table_choose_script (hb_face_t *face, @@ -1354,7 +1353,6 @@ hb_ot_layout_lookup_would_substitute (hb_face_t *face, * @font: #hb_font_t to use * @buffer: #hb_buffer_t buffer to work upon * - * Begins * **/ void @@ -1532,11 +1530,18 @@ hb_ot_layout_position_finish_offsets (hb_font_t *font, hb_buffer_t *buffer) * @face: #hb_face_t to work upon * @design_size: (out): The design size of the face * @subfamily_id: (out): The identifier of the face within the font subfamily - * @subfamily_name_id: (out): The ‘name’ table name ID of the face within the font subfamily + * @subfamily_name_id: (out): The ‘name’ table name ID of the face within the font subfamily * @range_start: (out): The small end of the recommended size range for the face * @range_end: (out): The big end of the recommended size range for the face * - * Fetches optical-size feature data (i.e., the `size` feature from GPOS). + * Fetches optical-size feature data (i.e., the `size` feature from GPOS). Note that + * the subfamily_id and the subfamily name string (accessible via the subfamily_name_id) + * as used here are defined as pertaining only to fonts within a font family that differ + * specifically in their respective size ranges; other ways to differentiate fonts within + * a subfamily are not covered by the `size` feature. + * + * For more information on this distinction, see the `size` documentation at + * https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-39size39 * * Return value: true if data found, false otherwise * @@ -1946,7 +1951,7 @@ typedef enum { * hb_ot_layout_get_baseline: * @font: The #hb_font_t to work upon * @baseline: The #hb_ot_layout_baseline_t to query - * @direction: The #hb_direction_t text direction to use + * @direction: The #hb_direction_t text direction to use (horizontal or vertical) * @script_tag: #hb_tag_t of the script to use * @language_tag: #hb_tag_t of the language to use * @coord: (out): The position of the requested baseline From 3db227265bc0790ffd718bf265d245c78598a49d Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Tue, 2 Apr 2019 18:49:40 +0100 Subject: [PATCH 14/14] Update gtk-doc annotations for inout counts on various getter functions. --- src/hb-ot-layout.cc | 118 +++++++++++++++++++++++++------------------- 1 file changed, 68 insertions(+), 50 deletions(-) diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc index c0b68229d..70c4601a2 100644 --- a/src/hb-ot-layout.cc +++ b/src/hb-ot-layout.cc @@ -314,10 +314,10 @@ hb_ot_layout_get_glyphs_in_class (hb_face_t *face, * hb_ot_layout_get_attach_points: * @face: The #hb_face_t to work on * @glyph: The #hb_codepoint_t code point to query - * @start_offset: The offset into the attachment-point array to start returning - * @point_count: (inout): The number of attachment points to return as input; - * The number of attachment points returned in the array as output - * @point_array: (out): The array of attachment points found for the query + * @start_offset: offset of the first attachment point to retrieve + * @point_count: (inout) (allow-none): Input = the maximum number of attachment points to return; + * Output = the actual number of attachment points returned (may be zero) + * @point_array: (out) (array length=point_count): The array of attachment points found for the query * * Fetches a list of all attachment points for the specified glyph in the GDEF * table of the face. The list returned will begin at the offset provided. @@ -344,10 +344,10 @@ hb_ot_layout_get_attach_points (hb_face_t *face, * @font: The #hb_font_t to work on * @direction: The #hb_direction_t text direction to use * @glyph: The #hb_codepoint_t code point to query - * @start_offset: The offset into the caret array to start returning - * @caret_count: (inout): The number of caret positions to return as input; - * The number of caret positions returned in the array as output - * @caret_array: (out): The array of caret positions found for the query + * @start_offset: offset of the first caret position to retrieve + * @caret_count: (inout) (allow-none): Input = the maximum number of caret positions to return; + * Output = the actual number of caret positions returned (may be zero) + * @caret_array: (out) (array length=caret_count): The array of caret positions found for the query * * Fetches a list of the caret positions defined for a ligature glyph in the GDEF * table of the font. The list returned will begin at the offset provided. @@ -425,10 +425,10 @@ get_gsubgpos_table (hb_face_t *face, * hb_ot_layout_table_get_script_tags: * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS - * @start_offset: The offset into the script-tag array to start returning - * @script_count: (inout): The number of script tags to return as input; - * The number of script tags returned in the array as output - * @script_tags: (out): The array of #hb_tag_t script tags found for the query + * @start_offset: offset of the first script tag to retrieve + * @script_count: (inout) (allow-none): Input = the maximum number of script tags to return; + * Output = the actual number of script tags returned (may be zero) + * @script_tags: (out) (array length=script_count): The array of #hb_tag_t script tags found for the query * * Fetches a list of all scripts enumerated in the specified face's GSUB table * or GPOS table. The list returned will begin at the offset provided. @@ -579,10 +579,10 @@ hb_ot_layout_table_select_script (hb_face_t *face, * hb_ot_layout_table_get_feature_tags: * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS - * @start_offset: The offset into the feature-tag array to start returning - * @feature_count: (inout): The number of feature tags to return as input; - * The number of feature tags returned in the array as output - * @feature_tags: (out): Array of feature tags found in the table + * @start_offset: offset of the first feature tag to retrieve + * @feature_count: (inout) (allow-none): Input = the maximum number of feature tags to return; + * Output = the actual number of feature tags returned (may be zero) + * @feature_tags: (out) (array length=feature_count): Array of feature tags found in the table * * Fetches a list of all feature tags in the given face's GSUB or GPOS table. * @@ -640,10 +640,10 @@ hb_ot_layout_table_find_feature (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @script_index: The index of the requested script tag - * @start_offset: The offset into the language-tag array to start returning - * @language_count: (inout): The number of language tags to return as input; - * The number of language tags returned in the array as output - * @language_tags: (out): Array of language tags found in the table + * @start_offset: offset of the first language tag to retrieve + * @language_count: (inout) (allow-none): Input = the maximum number of language tags to return; + * Output = the actual number of language tags returned (may be zero) + * @language_tags: (out) (array length=language_count): Array of language tags found in the table * * Fetches a list of language tags in the given face's GSUB or GPOS table, underneath * the specified script index. The list returned will begin at the offset provided. @@ -808,10 +808,10 @@ hb_ot_layout_language_get_required_feature (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @script_index: The index of the requested script tag * @language_index: The index of the requested language tag - * @start_offset: The offset into the feature-tag array to start returning - * @feature_count: (inout): The number of feature tags to return as input; - * The number of feature tags returned in the array as output - * @feature_indexes: (out): The array of feature indexes found for the query + * @start_offset: offset of the first feature tag to retrieve + * @feature_count: (inout) (allow-none): Input = the maximum number of feature tags to return; + * Output: the actual number of feature tags returned (may be zero) + * @feature_indexes: (out) (array length=feature_count): The array of feature indexes found for the query * * Fetches a list of all features in the specified face's GSUB table * or GPOS table, underneath the specified script and language. The list @@ -839,10 +839,10 @@ hb_ot_layout_language_get_feature_indexes (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @script_index: The index of the requested script tag * @language_index: The index of the requested language tag - * @start_offset: The offset into the feature-tag array to start returning - * @feature_count: (inout): The number of feature tags to return as input; - * The number of feature tags returned in the array as output - * @feature_tags: (out): The array of #hb_tag_t feature tags found for the query + * @start_offset: offset of the first feature tag to retrieve + * @feature_count: (inout) (allow-none): Input = the maximum number of feature tags to return; + * Output = the actual number of feature tags returned (may be zero) + * @feature_tags: (out) (array length=feature_count): The array of #hb_tag_t feature tags found for the query * * Fetches a list of all features in the specified face's GSUB table * or GPOS table, underneath the specified script and language. The list @@ -921,10 +921,10 @@ hb_ot_layout_language_find_feature (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @feature_index: The index of the requested feature - * @start_offset: The offset into the lookup array to start returning - * @lookup_count: (inout): The number of lookups to return as input; - * The number of lookups returned in the array as output - * @lookup_indexes: (out): The array of lookup indexes found for the query + * @start_offset: offset of the first lookup to retrieve + * @lookup_count: (inout) (allow-none): Input = the maximum number of lookups to return; + * Output = the actual number of lookups returned (may be zero) + * @lookup_indexes: (out) (array length=lookup_count): The array of lookup indexes found for the query * * Fetches a list of all lookups enumerated for the specified feature, in * the specified face's GSUB table or GPOS table. The list returned will @@ -1243,7 +1243,7 @@ hb_ot_layout_lookup_collect_glyphs (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @coords: The variation coordinates to query * @num_coords: The number of variation coorinates - * variations_index: (out): The array of feature variations found for the query + * @variations_index: (out): The array of feature variations found for the query * * Fetches a list of feature variations in the specified face's GSUB table * or GPOS table, at the specified variation coordinates. @@ -1268,10 +1268,10 @@ hb_ot_layout_table_find_feature_variations (hb_face_t *face, * @table_tag: HB_OT_TAG_GSUB or HB_OT_TAG_GPOS * @feature_index: The index of the feature to query * @variations_index: The index of the feature variation to query - * @start_offset: The offset into the lookup array to start returning - * @lookup_count: (inout): The number of lookups to return as input; - * The number of lookups returned in the array as output - * @lookup_indexes: (out): The array of lookups found for the query + * @start_offset: offset of the first lookup to retrieve + * @lookup_count: (inout) (allow-none): Input = the maximum number of lookups to return; + * Output = the actual number of lookups returned (may be zero) + * @lookup_indexes: (out) (array length=lookup_count): The array of lookups found for the query * * Fetches a list of all lookups enumerated for the specified feature, in * the specified face's GSUB table or GPOS table, enabled at the specified @@ -1353,6 +1353,8 @@ hb_ot_layout_lookup_would_substitute (hb_face_t *face, * @font: #hb_font_t to use * @buffer: #hb_buffer_t buffer to work upon * + * Called before substitution lookups are performed, to ensure that glyph + * class and other properties are set on the glyphs in the buffer. * **/ void @@ -1498,6 +1500,9 @@ hb_ot_layout_has_positioning (hb_face_t *face) * @font: #hb_font_t to use * @buffer: #hb_buffer_t buffer to work upon * + * Called before positioning lookups are performed, to ensure that glyph + * attachment types and glyph-attachment chains are set for the glyphs in the buffer. + * **/ void hb_ot_layout_position_start (hb_font_t *font, hb_buffer_t *buffer) @@ -1511,6 +1516,8 @@ hb_ot_layout_position_start (hb_font_t *font, hb_buffer_t *buffer) * @font: #hb_font_t to use * @buffer: #hb_buffer_t buffer to work upon * + * Called after positioning lookups are performed, to finish glyph advances. + * **/ void hb_ot_layout_position_finish_advances (hb_font_t *font, hb_buffer_t *buffer) @@ -1518,6 +1525,14 @@ hb_ot_layout_position_finish_advances (hb_font_t *font, hb_buffer_t *buffer) OT::GPOS::position_finish_advances (font, buffer); } +/** + * hb_ot_layout_position_finish_offsets: + * @font: #hb_font_t to use + * @buffer: #hb_buffer_t buffer to work upon + * + * Called after positioning lookups are performed, to finish glyph offsets. + * + **/ void hb_ot_layout_position_finish_offsets (hb_font_t *font, hb_buffer_t *buffer) { @@ -1531,8 +1546,8 @@ hb_ot_layout_position_finish_offsets (hb_font_t *font, hb_buffer_t *buffer) * @design_size: (out): The design size of the face * @subfamily_id: (out): The identifier of the face within the font subfamily * @subfamily_name_id: (out): The ‘name’ table name ID of the face within the font subfamily - * @range_start: (out): The small end of the recommended size range for the face - * @range_end: (out): The big end of the recommended size range for the face + * @range_start: (out): The minimum size of the recommended size range for the face + * @range_end: (out): The maximum size of the recommended size range for the face * * Fetches optical-size feature data (i.e., the `size` feature from GPOS). Note that * the subfamily_id and the subfamily name string (accessible via the subfamily_name_id) @@ -1670,19 +1685,22 @@ hb_ot_layout_feature_get_name_ids (hb_face_t *face, * @face: #hb_face_t to work upon * @table_tag: table tag to query, "GSUB" or "GPOS". * @feature_index: index of feature to query. - * @start_offset: In case the resulting char_count was equal to its input value, there - * is a chance there were more characters on the tag so this API can be - * called with an offset till resulting char_count gets to a number - * lower than input buffer (or consider using just a bigger buffer for - * one shot copying). - * @char_count: (inout) (allow-none): The count of characters for which this feature - * provides glyph variants. (May be zero.) - * @characters: (out caller-allocates) (array length=char_count): A buffer pointer. The Unicode codepoints - * of the characters for which this feature provides glyph variants. + * @start_offset: offset of the first character to retrieve + * @char_count: (inout) (allow-none): Input = the maximum number of characters to return; + * Output = the actual number of characters returned (may be zero) + * @characters: (out caller-allocates) (array length=char_count): A buffer pointer. + * The Unicode codepoints of the characters for which this feature provides + * glyph variants. * - * Fetches characters listed by designer under feature parameters for "Character - * Variant" ("cvXX") features. + * Fetches a list of the characters defined as having a variant under the specified + * "Character Variant" ("cvXX") feature tag. * + * Note: If the char_count output value is equal to its input value, then there + * is a chance there were more characters defined under the feature tag than were + * returned. This function can be called with incrementally larger start_offset + * until the char_count output value is lower than its input value, or the size + * of the characters array can be increased. + * * Return value: Number of total sample characters in the cvXX feature. * * Since: 2.0.0