From 32ae0d3e78c4e1f7299cb4fa251c0e66b3d5ae78 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 20 May 2019 17:35:39 +0100 Subject: [PATCH 01/29] [Docs] Add gtk-doc comments to hb-coretext. --- src/hb-coretext.cc | 45 +++++++++++++++++++++++++++++++++++++++++---- src/hb-coretext.h | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 73 insertions(+), 4 deletions(-) diff --git a/src/hb-coretext.cc b/src/hb-coretext.cc index 66f0fce1a..8e46e1a9d 100644 --- a/src/hb-coretext.cc +++ b/src/hb-coretext.cc @@ -293,13 +293,32 @@ _hb_coretext_shaper_face_data_destroy (hb_coretext_face_data_t *data) CFRelease ((CGFontRef) data); } +/** + * hb_coretext_face_create: + * @cg_font: The CGFontRef to work upon + * + * Creates an #hb_face_t face object from the specified + * CGFontRef. + * + * Return value: the new #hb_face_t face object + * + * Since: 0.9.10 + */ hb_face_t * hb_coretext_face_create (CGFontRef cg_font) { return hb_face_create_for_tables (reference_table, CGFontRetain (cg_font), _hb_cg_font_release); } -/* +/** + * hb_coretext_face_get_cg_font: + * @face: The #hb_face_t to work upon + * + * Fetches the CGFontRef associated with an #hb_face_t + * face object + * + * Return value: the CGFontRef found + * * Since: 0.9.10 */ CGFontRef @@ -365,10 +384,17 @@ retry: return font->data.coretext; } - -/* +/** + * hb_coretext_font_create: + * @ct_font: The CTFontRef to work upon + * + * Creates an #hb_font_t font object from the specified + * CTFontRef. + * + * Return value: the new #hb_font_t font object + * * Since: 1.7.2 - */ + **/ hb_font_t * hb_coretext_font_create (CTFontRef ct_font) { @@ -389,6 +415,17 @@ hb_coretext_font_create (CTFontRef ct_font) return font; } +/** + * hb_coretext_face_get_ct_font: + * @font: #hb_font_t to work upon + * + * Fetches the CTFontRef associated with the specified + * #hb_font_t font object. + * + * Return value: the CTFontRef found + * + * Since: 0.9.10 + */ CTFontRef hb_coretext_font_get_ct_font (hb_font_t *font) { diff --git a/src/hb-coretext.h b/src/hb-coretext.h index 4b0a6f01b..e53dbaf2c 100644 --- a/src/hb-coretext.h +++ b/src/hb-coretext.h @@ -40,8 +40,40 @@ HB_BEGIN_DECLS +/** + * HB_CORETEXT_TAG_MORT: + * + * The #hb_tag_t tag for the `mort` (glyph metamorphosis) table, + * which holds AAT features. + * + * For more information, see + * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6mort.html + * + **/ #define HB_CORETEXT_TAG_MORT HB_TAG('m','o','r','t') + +/** + * HB_CORETEXT_TAG_MORX: + * + * The #hb_tag_t tag for the `morx` (extended glyph metamorphosis) + * table, which holds AAT features. + * + * For more information, see + * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6morx.html + * + **/ #define HB_CORETEXT_TAG_MORX HB_TAG('m','o','r','x') + +/** + * HB_CORETEXT_TAG_KERX: + * + * The #hb_tag_t tag for the `kerx` (extended kerning) table, which + * holds AAT kerning information. + * + * For more information, see + * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6kerx.html + * + **/ #define HB_CORETEXT_TAG_KERX HB_TAG('k','e','r','x') From 27222253d42d0485ec5a9a3db602f5cba64df94e Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 20 May 2019 17:36:18 +0100 Subject: [PATCH 02/29] [Docs] Add gtk-doc comments to hb-uniscribe. --- src/hb-uniscribe.cc | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/src/hb-uniscribe.cc b/src/hb-uniscribe.cc index 4bbbf6122..d79296944 100644 --- a/src/hb-uniscribe.cc +++ b/src/hb-uniscribe.cc @@ -44,7 +44,7 @@ * @short_description: Windows integration * @include: hb-uniscribe.h * - * Functions for using HarfBuzz with the Windows fonts. + * Functions for using HarfBuzz with Windows fonts. **/ @@ -578,6 +578,16 @@ _hb_uniscribe_shaper_font_data_destroy (hb_uniscribe_font_data_t *data) free (data); } +/** + * hb_uniscribe_font_get_logfontw: + * @font: The #hb_font_t to work upon + * + * Fetches the LOGFONTW structure that corresponds to the + * specified #hb_font_t font. + * + * Return value: a pointer to the LOGFONTW retrieved + * + **/ LOGFONTW * hb_uniscribe_font_get_logfontw (hb_font_t *font) { @@ -585,6 +595,16 @@ hb_uniscribe_font_get_logfontw (hb_font_t *font) return data ? &data->log_font : nullptr; } +/** + * hb_uniscribe_font_get_hfont: + * @font: The #hb_font_t to work upon + * + * Fetches the HFONT handle that corresponds to the + * specified #hb_font_t font. + * + * Return value: the HFONT retreieved + * + **/ HFONT hb_uniscribe_font_get_hfont (hb_font_t *font) { From bfa7b0af02a6ec66898723fe3e82f74760996a10 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 20 May 2019 17:36:55 +0100 Subject: [PATCH 03/29] [Docs] Add gtk-doc comments to hb-gobject and hb-glib. --- src/hb-glib.cc | 44 ++++++++++++++++++++++++++++++++++++++- src/hb-gobject-structs.cc | 13 ++++++++++-- 2 files changed, 54 insertions(+), 3 deletions(-) diff --git a/src/hb-glib.cc b/src/hb-glib.cc index 576375460..b441efe0e 100644 --- a/src/hb-glib.cc +++ b/src/hb-glib.cc @@ -39,7 +39,11 @@ * @short_description: GLib integration * @include: hb-glib.h * - * Functions for using HarfBuzz with the GLib library to provide Unicode data. + * Functions for using HarfBuzz with the GLib library. + * + * HarfBuzz supports using GLib to provide Unicode data, by attaching + * GLib functions to the virtual methods in a #hb_unicode_funcs_t function + * structure. **/ @@ -167,6 +171,17 @@ glib_script_to_script[] = }; #endif +/** + * hb_glib_script_to_script: + * @script: The GUnicodeScript identifier to query + * + * Fetches the #hb_script_t script that corresponds to the + * specified GUnicodeScript identifier. + * + * Return value: the #hb_script_t script found + * + * Since: 0.9.38 + **/ hb_script_t hb_glib_script_to_script (GUnicodeScript script) { @@ -183,6 +198,17 @@ hb_glib_script_to_script (GUnicodeScript script) #endif } +/** + * hb_glib_script_from_script: + * @script: The #hb_script_t to query + * + * Fetches the GUnicodeScript identifier that corresponds to the + * specified #hb_script_t script. + * + * Return value: the GUnicodeScript identifier found + * + * Since: 0.9.38 + **/ GUnicodeScript hb_glib_script_from_script (hb_script_t script) { @@ -371,6 +397,16 @@ void free_static_glib_funcs () } #endif +/** + * hb_glib_get_unicode_funcs: + * + * Fetches a Unicode-functions structure that is populated + * with the appropriate GLib function for each method. + * + * Return value: (transfer full): a pointer to the #hb_unicode_funcs_t Unicode-functions structure + * + * Since: 0.9.38 + **/ hb_unicode_funcs_t * hb_glib_get_unicode_funcs () { @@ -389,6 +425,12 @@ _hb_g_bytes_unref (void *data) /** * hb_glib_blob_create: + * @gbytes: the GBytes structure to work upon + * + * Creates an #hb_blob_t blob from the specified + * GBytes data structure. + * + * Return value: (transfer full): the new #hb_blob_t blob object * * Since: 0.9.38 **/ diff --git a/src/hb-gobject-structs.cc b/src/hb-gobject-structs.cc index 3cff880aa..b91bbb416 100644 --- a/src/hb-gobject-structs.cc +++ b/src/hb-gobject-structs.cc @@ -30,11 +30,20 @@ /** * SECTION:hb-gobject * @title: hb-gobject - * @short_description: GObject integration + * @short_description: GObject integration support * @include: hb-gobject.h * - * Functions for using HarfBuzz with the GObject library to provide + * Support for using HarfBuzz with the GObject library to provide * type data. + * + * The types and functions listed here are solely a linkage between + * HarfBuzz's public data types and the GTypes used by the GObject framework. + * HarfBuzz uses GObject introspection to generate its Python bindings + * (and potentially other language bindings); client programs should never need + * to access the GObject-integration mechanics. + * + * For client programs using the GNOME and GTK software stack, please see the + * GLib and FreeType integration pages. **/ From 9126a5ff070fe1191dfaf852aa601d506ddcffcb Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 20 May 2019 17:37:56 +0100 Subject: [PATCH 04/29] [Docs] Add gtk-doc comments to hb-ft. --- src/hb-ft.cc | 135 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 117 insertions(+), 18 deletions(-) diff --git a/src/hb-ft.cc b/src/hb-ft.cc index 48434dc8c..dfafaf19e 100644 --- a/src/hb-ft.cc +++ b/src/hb-ft.cc @@ -46,8 +46,13 @@ * @short_description: FreeType integration * @include: hb-ft.h * - * Functions for using HarfBuzz with the FreeType library to provide face and + * Functions for using HarfBuzz with the FreeType library. + * + * HarfBuzz supports using FreeType to provide face and * font data. + * + * Note that FreeType is not thread-safe, therefore these + * functions are not thread-safe either. **/ @@ -125,10 +130,13 @@ _hb_ft_font_destroy (void *data) /** * hb_ft_font_set_load_flags: - * @font: - * @load_flags: + * @font: #hb_font_t to work upon + * @load_flags: The FreeType load flags to set * + * Sets the FT_Load_Glyph load flags for the specified #hb_font_t. * + * For more information, see + * https://www.freetype.org/freetype2/docs/reference/ft2-base_interface.html#ft_load_xxx * * Since: 1.0.5 **/ @@ -148,11 +156,15 @@ hb_ft_font_set_load_flags (hb_font_t *font, int load_flags) /** * hb_ft_font_get_load_flags: - * @font: + * @font: #hb_font_t to work upon * + * Fetches the FT_Load_Glyph load flags of the specified #hb_font_t. * + * For more information, see + * https://www.freetype.org/freetype2/docs/reference/ft2-base_interface.html#ft_load_xxx + * + * Return value: FT_Load_Glyph flags found * - * Return value: * Since: 1.0.5 **/ int @@ -166,6 +178,17 @@ hb_ft_font_get_load_flags (hb_font_t *font) return ft_font->load_flags; } +/** + * hb_ft_get_face: + * @font: #hb_font_t to work upon + * + * Fetches the FT_Face associated with the specified #hb_font_t + * font object. + * + * Return value: the FT_Face found + * + * Since: 1.0.5 + **/ FT_Face hb_ft_font_get_face (hb_font_t *font) { @@ -570,12 +593,22 @@ reference_table (hb_face_t *face HB_UNUSED, hb_tag_t tag, void *user_data) /** * hb_ft_face_create: - * @ft_face: (destroy destroy) (scope notified): - * @destroy: + * @ft_face: (destroy destroy) (scope notified): FT_Face to work upon + * @destroy: A callback to call when the face object is not needed anymore * + * Creates an #hb_face_t face object from the specified FT_Face. * + * This variant of the function does not provide any life-cycle management. + * + * Most client programs should use hb_ft_face_create_referenced() + * (or, perhaps, hb_ft_face_create_cached()) instead. + * + * If you know you have valid reasons not to use hb_ft_face_create_referenced(), + * then it is the client program's responsibility to destroy @ft_face + * after the #hb_face_t face object has been destroyed. + * + * Return value: (transfer full): the new #hb_face_t face object * - * Return value: (transfer full): * Since: 0.9.2 **/ hb_face_t * @@ -605,11 +638,19 @@ hb_ft_face_create (FT_Face ft_face, /** * hb_ft_face_create_referenced: - * @ft_face: + * @ft_face: FT_Face to work upon * + * Creates an #hb_face_t face object from the specified FT_Face. * + * This is the preferred variant of the hb_ft_face_create* + * function family, because it calls FT_Reference_Face() on @ft_face, + * ensuring that @ft_face remains alive as long as the resulting + * #hb_face_t face object remains alive. + * + * Use this version unless you know you have good reasons not to. + * + * Return value: (transfer full): the new #hb_face_t face object * - * Return value: (transfer full): * Since: 0.9.38 **/ hb_face_t * @@ -627,11 +668,21 @@ hb_ft_face_finalize (FT_Face ft_face) /** * hb_ft_face_create_cached: - * @ft_face: + * @ft_face: FT_Face to work upon * + * Creates an #hb_face_t face object from the specified FT_Face. * + * This variant of the function caches the newly created #hb_face_t + * face object, using the generic pointer of @ft_face. Subsequent function + * calls that are passed the same @ft_face parameter will have the same + * #hb_face_t returned to them, and that #hb_face_t will be correctly + * reference counted. + * + * However, client programs are still responsible for destroying + * @ft_face after the last #hb_face_t face object has been destroyed. + * + * Return value: (transfer full): the new #hb_face_t face object * - * Return value: (transfer full): * Since: 0.9.2 **/ hb_face_t * @@ -649,15 +700,28 @@ hb_ft_face_create_cached (FT_Face ft_face) return hb_face_reference ((hb_face_t *) ft_face->generic.data); } - /** * hb_ft_font_create: - * @ft_face: (destroy destroy) (scope notified): - * @destroy: + * @ft_face: (destroy destroy) (scope notified): FT_Face to work upon + * @destroy: (optional): A callback to call when the font object is not needed anymore * + * Creates an #hb_font_t font object from the specified FT_Face. * + * Note: You must set the face size on @ft_face before calling + * hb_ft_font_create() on it. Otherwise, HarfBuzz will not pick up + * the face size. + * + * This variant of the function does not provide any life-cycle management. + * + * Most client programs should use hb_ft_font_create_referenced() + * instead. + * + * If you know you have valid reasons not to use hb_ft_font_create_referenced(), + * then it is the client program's responsibility to destroy @ft_face + * after the #hb_font_t font object has been destroyed. + * + * Return value: (transfer full): the new #hb_font_t font object * - * Return value: (transfer full): * Since: 0.9.2 **/ hb_font_t * @@ -675,6 +739,16 @@ hb_ft_font_create (FT_Face ft_face, return font; } +/** + * hb_ft_font_has_changed: + * @font: #hb_font_t to work upon + * + * Refreshes the state of @font when the underlying FT_Face has changed. + * This function should be called after changing the size or + * variation-axis settings on the FT_Face. + * + * Since: 1.0.5 + **/ void hb_ft_font_changed (hb_font_t *font) { @@ -730,11 +804,23 @@ hb_ft_font_changed (hb_font_t *font) /** * hb_ft_font_create_referenced: - * @ft_face: + * @ft_face: FT_Face to work upon * + * Creates an #hb_font_t font object from the specified FT_Face. * + * Note: You must set the face size on @ft_face before calling + * hb_ft_font_create_references() on it. Otherwise, HarfBuzz will not pick up + * the face size. + * + * This is the preferred variant of the hb_ft_font_create* + * function family, because it calls FT_Reference_Face() on @ft_face, + * ensuring that @ft_face remains alive as long as the resulting + * #hb_font_t font object remains alive. + * + * Use this version unless you know you have good reasons not to. + * + * Return value: (transfer full): the new #hb_font_t font object * - * Return value: (transfer full): * Since: 0.9.38 **/ hb_font_t * @@ -793,6 +879,19 @@ _release_blob (FT_Face ft_face) hb_blob_destroy ((hb_blob_t *) ft_face->generic.data); } +/** + * hb_ft_font_set_funcs: + * @font: #hb_font_t to work upon + * + * Configures the font-functions structure of the specified + * #hb_font_t font object to use FreeType font functions. + * + * Note: Internally, this function creates an FT_Face. + * You should use this FT_Face when you create an #hb_face_t + * with hb_ft_face_create(). + * + * Since: 1.0.5 + **/ void hb_ft_font_set_funcs (hb_font_t *font) { From 0a5a8fcbceb49f317a16803da090864f9ea03577 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 20 May 2019 17:38:13 +0100 Subject: [PATCH 05/29] [Docs] Add gtk-doc comments to hb-icu. --- src/hb-icu.cc | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/src/hb-icu.cc b/src/hb-icu.cc index c26c91d48..ad75710bd 100644 --- a/src/hb-icu.cc +++ b/src/hb-icu.cc @@ -46,10 +46,23 @@ * @short_description: ICU integration * @include: hb-icu.h * - * Functions for using HarfBuzz with the ICU library to provide Unicode data. + * Functions for using HarfBuzz with the International Components for Unicode + * (ICU) library. HarfBuzz supports using ICU to provide Unicode data, by attaching + * ICU functions to the virtual methods in a #hb_unicode_funcs_t function + * structure. **/ +/** + * hb_icu_script_to_script: + * @script: The UScriptCode identifier to query + * + * Fetches the #hb_script_t script that corresponds to the + * specified UScriptCode identifier. + * + * Return value: the #hb_script_t script found + * + **/ hb_script_t hb_icu_script_to_script (UScriptCode script) { @@ -59,6 +72,16 @@ hb_icu_script_to_script (UScriptCode script) return hb_script_from_string (uscript_getShortName (script), -1); } +/** + * hb_icu_script_from_script: + * @script: The #hb_script_t script to query + * + * Fetches the UScriptCode identifier that corresponds to the + * specified #hb_script_t script. + * + * Return value: the UScriptCode identifier found + * + **/ UScriptCode hb_icu_script_from_script (hb_script_t script) { @@ -343,6 +366,16 @@ void free_static_icu_funcs () } #endif +/** + * hb_icu_get_unicode_funcs: + * + * Fetches a Unicode-functions structure that is populated + * with the appropriate ICU function for each method. + * + * Return value: (transfer full): a pointer to the #hb_unicode_funcs_t Unicode-functions structure + * + * Since: 0.9.38 + **/ hb_unicode_funcs_t * hb_icu_get_unicode_funcs () { From d00a20bedc5706d4d764f78ea108ca4316651b11 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Mon, 20 May 2019 17:38:38 +0100 Subject: [PATCH 06/29] [Docs] Add gtk-doc comments to hb-graphite2. --- src/hb-graphite2.cc | 16 ++++++++++++++-- src/hb-graphite2.h | 10 +++++++++- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/src/hb-graphite2.cc b/src/hb-graphite2.cc index fdb545342..32446c669 100644 --- a/src/hb-graphite2.cc +++ b/src/hb-graphite2.cc @@ -41,7 +41,11 @@ * @short_description: Graphite2 integration * @include: hb-graphite2.h * - * Functions for using HarfBuzz with the Graphite2 fonts. + * Functions for using HarfBuzz with fonts that include Graphite2 features. + * + * For Graphite2 features to work, you must be sure that HarfBuzz was compiled + * with the `graphite2` shaping engine enabled. Currently, the default is to + * not enable `graphite2` shaping. **/ @@ -174,7 +178,15 @@ _hb_graphite2_shaper_face_data_destroy (hb_graphite2_face_data_t *data) free (data); } -/* +/** + * hb_graphite2_face_get_gr_face: + * @face: @hb_face_t to query + * + * Fetches the Graphite2 gr_face corresponding to the specified + * #hb_face_t face object. + * + * Return value: the gr_face found + * * Since: 0.9.10 */ gr_face * diff --git a/src/hb-graphite2.h b/src/hb-graphite2.h index 1720191b4..632a02895 100644 --- a/src/hb-graphite2.h +++ b/src/hb-graphite2.h @@ -32,7 +32,15 @@ HB_BEGIN_DECLS - +/** + * HB_GRAPHITE2_TAG_SILF: + * + * The #hb_tag_t tag for the `Silf` table, which holds Graphite2 + * features. + * + * For more information, see http://graphite.sil.org/ + * + **/ #define HB_GRAPHITE2_TAG_SILF HB_TAG('S','i','l','f') From 2da567e7b69da95738015b445901afb00094d92b Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Fri, 24 May 2019 11:13:53 +0100 Subject: [PATCH 07/29] [Docs] Usermanual: platform integration chapter; add intro, GLib, FreeType sections. Update XML TOCs to match. --- docs/Makefile.am | 1 + docs/harfbuzz-docs.xml | 1 + docs/usermanual-integration.xml | 365 ++++++++++++++++++++++++++++++++ 3 files changed, 367 insertions(+) create mode 100644 docs/usermanual-integration.xml diff --git a/docs/Makefile.am b/docs/Makefile.am index 0c76b2ed3..f8b38219d 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -82,6 +82,7 @@ content_files= \ usermanual-opentype-features.xml \ usermanual-clusters.xml \ usermanual-utilities.xml \ + usermanual-integration.xml \ version.xml # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded diff --git a/docs/harfbuzz-docs.xml b/docs/harfbuzz-docs.xml index e3f314d92..7a175f357 100644 --- a/docs/harfbuzz-docs.xml +++ b/docs/harfbuzz-docs.xml @@ -43,6 +43,7 @@ + diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml new file mode 100644 index 000000000..b8a52c9f7 --- /dev/null +++ b/docs/usermanual-integration.xml @@ -0,0 +1,365 @@ + + + +]> + + Platform Integration Guide + + HarfBuzz was first developed for use with the GNOME and GTK + software stack commonly found in desktop Linux + distributions. Nevertheless, it can be used on other operating + systems and platforms, from iOS and macOS to Windows. It can also + be used with other application frameworks and components, such as + Android, Qt, or application-specific widget libraries. + + + This chapter will look at how HarfBuzz fits into a typical + text-rendering pipeline, and will discuss the APIs available to + integrate HarfBuzz with contemporary Linux, Mac, and Windows + software. It will also show how HarfBuzz integrates with popular + external libaries like FreeType and International Components for + Unicode (ICU) and describe the HarfBuzz language bindings for + Python. + + + On a GNOME system, HarfBuzz is designed to tie in with several + other common system libraries. The most common architecture uses + Pango at the layer directly "above" HarfBuzz; Pango is responsible + for text segmentation and for ensuring that each input + hb_buffer_t passed to HarfBuzz for shaping contains + Unicode code points that share the same segment properties + (namely, direction, language, and script, but also higher-level + properties like the active font, font style, color, and so on). + + + The layer directly "below" HarfBuzz is typically FreeType, which + is used to rasterize glyph outlines at the necessary optical size, + hinting settings, and pixel resolution. FreeType provides APIs for + accessing font and face information, so HarfBuzz includes + functions to create hb_face_t and + hb_font_t objects directly from FreeType + objects. HarfBuzz will can use FreeType's built-in functions for + font_funcs vtable in an hb_font_t. + + + FreeType's output is bitmaps of the rasterized glyphs; on a + typical Linux system these will then be drawn by a graphics + library like Cairo, but those details are beyond HarfBuzz's + control. On the other hand, at the top end of the stack, Pango is + part of the larger GNOME framework, and HarfBuzz does include APIs + for working with key components of GNOME's higher-level libraries + — most notably GLib. + + + For other operating systems or application frameworks, the + critical integration points are where HarfBuzz gets font and face + information about the font used for shaping and where HarfBuzz + gets Unicode data about the input-buffer code points. + + + The font and face information is necessary for text shaping + because HarfBuzz needs to retrieve the glyph indices for + particular code points, and to know the extents and advances of + glyphs. Note that, in an OpenType variable font, both of those + types of information can change with different variation-axis + settings. + + + The Unicode information is necessary for shaping because the + properties of a code point (such as it's General Category (gc), + Canonical Combining Class (ccc), and decomposition) can directly + impact the shaping moves that HarfBuzz performs. + + +
+ GNOME integration, GLib, and GObject + + As mentioned in the preceding section, HarfBuzz offers + integration APIs to help client programs using the + GNOME and GTK framework commonly found in desktop Linux + distributions. + + + GLib is the main utility library for GNOME applications. It + provides basic data types and conversions, file abstractions, + string manipulation, and macros, as well as facilities like + memory allocation and the main event loop. + + + Where text shaping is concerned, GLib provides several utilities + that HarfBuzz can take advantage of, including a set of + Unicode-data functions and a data type for script + information. Both are useful when working with HarfBuzz + buffers. To make use of them, you will need to include the + hb-glib.h header file. + + + GLib's Unicode + manipulation API includes all the functionality + necessary to retrieve Unicode data for the + unicode_funcs structure of a HarfBuzz + hb_buffer_t. + + + The function hb_glib_get_unicode_funcs() + sets up a hb_unicode_funcs_t structure configured + with the GLib Unicode functions and returns a pointer to it. + + + You can attach this Unicode-functions structure to your buffer, + and it will be ready for use with GLib: + + + #include <hb-glib.h> + ... + hb_unicode_funcs_t *glibufunctions; + glibufunctions = hb_glib_get_unicode_funcs(); + hb_buffer_set_unicode_funcs(buf, glibufunctions); + + + For script information, GLib uses the + GUnicodeScript type. Like HarfBuzz's own + hb_script_t, this data type is an enumeration + of Unicode scripts, but text segments passed in from GLib code + will be tagged with a GUnicodeScript. Therefore, + when setting the script property on a hb_buffer_t, + you will need to convert between the GUnicodeScript + of the input provided by GLib and HarfBuzz's + hb_script_t type. + + + The hb_glib_script_to_script() function + takes an GUnicodeScript script identifier as its + sole argument and returns the corresponding hb_script_t. + The hb_glib_script_from_script() does the + reverse, taking an hb_script_t and returning the + GUnicodeScript identifier for GLib. + + + Finally, GLib also provides a reference-counted object type called GBytes + that is used for accessing raw memory segments with the benefits + of GLib's lifecycle management. HarfBuzz provides a + hb_glib_blob_create() function that lets + you create an hb_blob_t directly from a + GBytes object. This function takes only the + GBytes object as its input; HarfBuzz registers the + GLib destroy callback automatically. + + + The GNOME platform also features an object system called + GObject. For HarfBuzz, the main advantage of GObject is a + feature called GObject + Introspection. This is a middleware facility that can be + used to generate language bindings for C libraries. HarfBuzz uses it + to build its Python bindings, which we will look at in a separate section. + +
+ +
+ FreeType integration + + FreeType is the free-software font-rendering engine included in + desktop Linux distributions, Android, ChromeOS, iOS, and multiple Unix + operating systems, and used by cross-platform programs like + Chrome, Java, and GhostScript. Used together, HarfBuzz can + perform shaping on Unicode text segments, outputting the glyph + IDs that FreeType should rasterize from the active font as well + as the positions at which those glyphs should be drawn. + + + HarfBuzz provides integration points with FreeType at the + face-object and font-object level and for the font-functions + virtual-method structure of a font object. To use the + FreeType-integration API, include the + hb-ft.h header. + + + In a typical client program, you will create your + hb_face_t face object and hb_font_t + font object from a FreeType FT_Face. HarfBuzz + provides a suite of functions for doing this. + + + In the most common case, you will want to use + hb_ft_font_create_referenced(), which + creates both an hb_face_t face object and + hb_font_t font object (linked to that face object), + and provides lifecycle management. + + + It is important to note, + though, that while HarfBuzz makes a distinction between its face and + font objects, FreeType's FT_Face does not. After + you create your FT_Face, you must set its size + parameter using FT_Set_Char_Size(), because + an hb_font_t is defined as an instance of an + hb_face_t with size specified. + + + #include <hb-ft.h> + ... + FT_New_Face(ft_library, font_path, index, &face); + FT_Set_Char_Size(face, 0, 1000, 0, 0); + hb_font_t *font = hb_ft_font_create(face); + + + Although hb_ft_font_create_referenced() is + the recommended function, there is another variant. The simpler + version of the function is + hb_ft_font_create(), which takes an + FT_Face and an optional destroy callback as its + arguments. The critical difference between the two is that + hb_ft_font_create() does not offer the + lifecycle-management feature. Your client code will be + responsible for tracking references to the FT_Face objects and + destroying them when they are no longer needed. If you do not + have a valid reason for doing this, user + hb_ft_font_create_referenced(). + + + After you have created your font object from your + FT_Face, you can set or retrieve the + load_flags of the + FT_Face through the hb_font_t + object. HarfBuzz provides + hb_ft_font_set_load_flags() and + hb_ft_font_get_load_flags() for this + purpose. The ability to set the + load_flags through the font object + could be useful for enabling or disabling hinting, for example, + or to activate vertical layout. + + + HarfBuzz also provides a utility function called + hb_ft_font_has_changed() that you should + call whenever you have altered the properties of your underlying + FT_Face, as well as a + hb_ft_get_face() that you can call on an + hb_font_t font object to fetch its underlying FT_Face. + + + With an hb_face_t and hb_font_t both linked + to your FT_Face, you will typically also want to + use FreeType for the font_funcs + vtable of your hb_font_t. As a reminder, this + font-functions structure is the set of methods that HarfBuzz + will use to fetch important information from the font, such as + the advances and extents of individual glyphs. + + + All you need to do is call + + + hb_ft_font_set_funcs(font); + + + and HarfBuzz will use FreeType for the font-functions in + font. + + + As we noted above, an hb_font_t is derived from an + hb_face_t with size (and, perhaps, other + parameters, such as variation-axis coordinates) + specified. Consequently, you can reuse an hb_face_t + with several hb_font_t objects, and HarfBuzz + provides functions to simplify this. + + + The hb_ft_face_create_referenced() + function creates just an hb_face_t from a FreeType + FT_Face and, as with + hb_ft_font_create_referenced() above, + provides lifecycle management for the FT_Face. + + + Similarly, there is an hb_ft_face_create() + function variant that does not provide the lifecycle-management + feature. As with the font-object case, if you use this version + of the function, it will be your client code's respsonsibility + to track usage of the FT_Face objects. + + + A third variant of this function is + hb_ft_face_create_cached(), which is the + same as hb_ft_face_create() except that it + also uses the generic field of the + FT_Face structure to save a pointer to the newly + created hb_face_t. Subsequently, function calls + that pass the same FT_Face will get the same + hb_face_t returned — and the + hb_face_t will be correctly reference + counted. Still, as with + hb_ft_face_create(), your client code must + track references to the FT_Face itself, and destroy + it when it is unneeded. + +
+ +
+ Uniscribe integration + + + + + + + + + +
+ +
+ CoreText integration + + + + + + + + + +
+ +
+ ICU integration + + + + + + + + + +
+ +
+ Python bindings + + + + + + + + + +
+ +
+ + + + + + + +
+ + From dd1c7656a5918702a81bc3aaf66e0e54fdb3c545 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Fri, 24 May 2019 14:30:15 +0100 Subject: [PATCH 08/29] [Docs] Usermanual: integration chapter; add Uniscribe/Windows section. --- docs/usermanual-integration.xml | 110 ++++++++++++++++++++++++++++++-- 1 file changed, 105 insertions(+), 5 deletions(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index b8a52c9f7..9fd94c85a 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -19,7 +19,7 @@ text-rendering pipeline, and will discuss the APIs available to integrate HarfBuzz with contemporary Linux, Mac, and Windows software. It will also show how HarfBuzz integrates with popular - external libaries like FreeType and International Components for + external libraries like FreeType and International Components for Unicode (ICU) and describe the HarfBuzz language bindings for Python. @@ -203,7 +203,7 @@ #include <hb-ft.h> ... - FT_New_Face(ft_library, font_path, index, &face); + FT_New_Face(ft_library, font_path, index, &face); FT_Set_Char_Size(face, 0, 1000, 0, 0); hb_font_t *font = hb_ft_font_create(face); @@ -303,16 +303,101 @@
Uniscribe integration - + If your client program is running on Windows, HarfBuzz can + integrate with the Uniscribe engine. - + Overall, the Uniscribe API covers a broader set of typographic + layout functions than HarfBuzz implements, but HarfBuzz's + shaping API can serve as a drop-in replacement for the shaping + functionality. In fact, one of HarfBuzz's design goals is to + accurately reproduce the same output for shaping a given text + segment that Uniscribe produces — even to the point of + duplicating known shaping bugs or deviations from the + specification — so you can be sure that your users' + documents with their existing fonts will not be affected by + switching to HarfBuzz. + At a basic level, HarfBuzz's hb_shape() + function replaces both the ScriptShape() + and ScriptPlace() functions from + Uniscribe. + + + However, whereas ScriptShape() returns the + glyphs and clusters for a shaped sequence and + ScriptPlace() returns the advances and + offsets for those glyphs, hb_shape() + handles both. After hb_shape() shapes a + buffer, the output glyph IDs and cluster IDs are returned as + an array of hb_glyph_info_t structures, and the + glyph advances and offsets are returned as an array of + hb_glyph_position_t structures. + + + Your client program only needs to ensure that it coverts + correctly between HarfBuzz's low-level data types (such as + hb_position_t) and Windows's corresponding types + (such as GOFFSET and ABC). Be sure you + read the + chapter for a full explanation of how HarfBuzz input buffers are + used, and see for the + details of what hb_shape() returns in the + output buffer when shaping is complete. + + + Although hb_shape() itself is functionally + equivalent to Uniscribe's shaping routines, there are two + additional HarfBuzz functions you may want to use to integrate + the libraries in your code. Both are used to link HarfBuzz font + objects to the equivalent Windows structures. + + + The hb_uniscribe_font_get_logfontw() + function takes a hb_font_t font object and returns + a pointer to the LOGFONTW + "logical font" that corresponds to it. A LOGFONTW + structure holds font-wide attributes, including metrics, size, + and style information. + +SCRIPT_CACHE holds context, including LOGFONT https://docs.microsoft.com/en-us/windows/desktop/Intl/script-cache + https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-logfontw + + + The hb_uniscribe_font_get_hfont() function + also takes a hb_font_t font object, but it returns + an HFONT — a handle to the underlying logical + font — instead. + + + LOGFONTWs and HFONTs are both needed + by other Uniscribe functions. + + + As a final note, you may notice a reference to an optional + uniscribe shaper back-end in the section of the HarfBuzz manual. This + option is not a Uniscribe-integration facility. + + + Instead, it is a internal code path used in the + hb-shape command-line utility, which hands + shaping functionality over to Uniscribe entirely, when run on a + Windows system. That allows testing HarfBuzz's native output + against the Uniscribe engine, for tracking compatibility and + debugging. + + + Because this back-end is only used when testing HarfBuzz + functionality, it is disabled by default when building the + HarfBuzz binaries.
- +
CoreText integration @@ -323,6 +408,21 @@ + + + + + + + + + + + + + + +
From c0bb66ecbff712221fb7c97f628ed026926229b2 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Fri, 24 May 2019 18:49:40 +0100 Subject: [PATCH 09/29] [Docs] Usermanual: integration chapter; add CoreText/Mac section. --- docs/usermanual-integration.xml | 107 ++++++++++++++++++++++++++------ 1 file changed, 89 insertions(+), 18 deletions(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 9fd94c85a..7ed85dd30 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -303,13 +303,14 @@
Uniscribe integration - If your client program is running on Windows, HarfBuzz can - integrate with the Uniscribe engine. + If your client program is running on Windows, HarfBuzz offers + an additional API that can help integrate with Microsoft's + Uniscribe engine and the Windows GDI. Overall, the Uniscribe API covers a broader set of typographic layout functions than HarfBuzz implements, but HarfBuzz's - shaping API can serve as a drop-in replacement for the shaping + shaping API can serve as a drop-in replacement for Uniscribe's shaping functionality. In fact, one of HarfBuzz's design goals is to accurately reproduce the same output for shaping a given text segment that Uniscribe produces — even to the point of @@ -321,8 +322,9 @@ At a basic level, HarfBuzz's hb_shape() function replaces both the ScriptShape() - and ScriptPlace() functions from - Uniscribe. + and ScriptPlace() + functions from Uniscribe. However, whereas ScriptShape() returns the @@ -363,10 +365,14 @@ structure holds font-wide attributes, including metrics, size, and style information. - -SCRIPT_CACHE holds context, including LOGFONT https://docs.microsoft.com/en-us/windows/desktop/Intl/script-cache - https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-logfontw - + The hb_uniscribe_font_get_hfont() function also takes a hb_font_t font object, but it returns @@ -399,30 +405,95 @@ SCRIPT_CACHE holds context, including LOGFONT https://docs.microsoft.com/en
- CoreText integration + Core Text integration - + If your client program is running on macOS or iOS, HarfBuzz offers + an additional API that can help integrate with Apple's + Core Text engine and the underlying Core Graphics + framework. HarfBuzz does not attempt to offer the same + drop-in-replacement functionality for Core Text that it strives + for with Uniscribe on Windows, but you can still user HarfBuzz + to perform text shaping in native macOS and iOS applications. - + Note, though, that if your interest is just in using fonts that + contain Apple Advanced Typography (AAT) features, then you do + not need to add Core Text integration. HarfBuzz natively + supports AAT features and will shape AAT fonts (on any platform) + automatically, without requiring additional work on your + part. This includes support for AAT-specific TrueType tables + such as mort, morx, and + kerx, which AAT fonts use instead of + GSUB and GPOS. - + On a macOS or iOS system, the primary integration points offered + by HarfBuzz are for face objects and font objects. - + The Apple APIs offer a pair of data structures that map well to + HarfBuzz's face and font objects. The Core Graphics API, which + is slightly lower-level than Core Text, provides + CGFontRef, which enables access to typeface + properties, but does not include size information. Core Text's + CTFontRef is analagous to a HarfBuzz font object, + with all of the properties required to render text at a specific + size and configuration. + Consequently, a HarfBuzz hb_font_t font object can + be hooked up to a Core Text CTFontRef, and a HarfBuzz + hb_face_t face object can be hooked up to a + CGFontRef. - + You can create a hb_face_t from a + CGFontRef by using the + hb_coretext_face_create(). Subsequently, + you can retrieve the CGFontRef from a + hb_face_t with hb_coretext_face_get_cg_font(). - + Likewise, you create a hb_font_t from a + CTFontRef by calling + hb_coretext_font_create(), and you can + fetch the associated CTFontRef from a + hb_font_t font object with + hb_coretext_face_get_ct_font(). - + HarfBuzz also offers a hb_font_set_ptem() + that you an use to set the nominal point size on any + hb_font_t font object. Core Text uses this value to + implement optical scaling. - + When integrating your client code with Core Text, it is + important to recognize that Core Text points + are not typographic points (standardized at 72 per inch) as the + term is used elsewhere in OpenType. Instead, Core Text points + are CSS points, which are standardized at 96 per inch. + + + HarfBuzz's font functions take this distinction into account, + but it can be an easy detail to miss in cross-platform + code. + + + As a final note, you may notice a reference to an optional + coretext shaper back-end in the section of the HarfBuzz manual. This + option is not a CoreText-integration facility. + + + Instead, it is a internal code path used in the + hb-shape command-line utility, which hands + shaping functionality over to CoreText entirely, when run on a + macOS system. That allows testing HarfBuzz's native output + against the CoreText engine, for tracking compatibility and debugging. + + + Because this back-end is only used when testing HarfBuzz + functionality, it is disabled by default when building the + HarfBuzz binaries.
From 773c85f343e8958daf271d91d64033514289c236 Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Fri, 24 May 2019 19:23:19 +0100 Subject: [PATCH 10/29] [Docs] Usermanual: integration chapter; add ICU section. --- docs/usermanual-integration.xml | 51 ++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 7ed85dd30..d46361e7e 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -500,14 +500,57 @@
ICU integration - - - - + Although HarfBuzz includes its own Unicode-data functions, it + also provides integration APIs for using the International + Components for Unicode (ICU) library as a source of Unicode data + on any supported platform. + + + The principle integration point with ICU is the + hb_unicode_funcs_t Unicode-functions structure + attached to a buffer. This structure holds the virtual methods + used for retrieving Unicode character properties, such as + General Category, Script, Combining Class, decomposition + mappings, and mirroring information. + + + To use ICU in your client program, you need to call + hb_icu_get_unicode_funcs(), which creates a + Unicode-functions structure populated with the ICU function for + each included method. Subsequently, you can attach the + Unicode-functions structure to your buffer: + + + hb_unicode_funcs_t *icufunctions; + icufunctions = hb_icu_get_unicode_funcs(); + hb_buffer_set_unicode_funcs(buf, icufunctions); + + + and ICU will be used for Unicode-data access. + + + HarfBuzz also supplies a pair of functions + (hb_icu_script_from_script() and + hb_icu_script_to_script()) for converting + between ICU's and HarfBuzz's internal enumerations of Unicode + scripts. The hb_icu_script_from_script() + function converts from a HarfBuzz hb_script_t to an + ICU UScriptCode. The + hb_icu_script_to_script() function does the + reverse: converting from a UScriptCode identifier + to a hb_script_t. + + + By default, ICU support is included when compiling HarfBuzz from + source. The build system will look for the ICU library and link + to it if it is found. You can also build HarfBuzz with it own, + internal copy of ICU, by specifying the + --with-icu=builtin compile-time option. +
From 322df806eef74247c8bf0da200a2cde29133950e Mon Sep 17 00:00:00 2001 From: Nathan Willis Date: Fri, 24 May 2019 19:49:19 +0100 Subject: [PATCH 11/29] [Docs] Usermanual: integration chapter; add GI-Python section. --- docs/usermanual-integration.xml | 35 ++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index d46361e7e..1085e96c5 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -547,32 +547,43 @@ internal copy of ICU, by specifying the --with-icu=builtin compile-time option. - - -
Python bindings - + As noted in the section, + HarfBuzz uses a feature called GObject + Introspection (GI) to provide bindings for Python. - + At compile time, the GI scanner analyzes the HarfBuzz C source + and builds metadata objects connecting the language bindings to + the C library. Your Python code can then use the HarfBuzz binary + through its Python interface. - + HarfBuzz's Python bindings support Python 2 and Python 3. To use + them, you will need to have the pygobject + package installed. Then you should import + HarfBuzz from + gi.repository: -
- -
- + + from gi.repository import HarfBuzz + - + and you can call HarfBuzz functions from Python. Sample code can + be found in the sample.py script in the + HarfBuzz src directory. - + Do note, however, that the Python API is subject to change + without advance notice. GI allows the bindings to be + automatically updated, which is one of its advantages, but you + may need to update your Python code.
From ccc235698394aab2cea69bd2e00a0caa766d577b Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 15:13:56 +0100 Subject: [PATCH 12/29] Update src/hb-graphite2.h Co-Authored-By: Khaled Hosny --- src/hb-graphite2.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/hb-graphite2.h b/src/hb-graphite2.h index 632a02895..f299da9f7 100644 --- a/src/hb-graphite2.h +++ b/src/hb-graphite2.h @@ -35,7 +35,7 @@ HB_BEGIN_DECLS /** * HB_GRAPHITE2_TAG_SILF: * - * The #hb_tag_t tag for the `Silf` table, which holds Graphite2 + * The #hb_tag_t tag for the `Silf` table, which holds Graphite * features. * * For more information, see http://graphite.sil.org/ From aff21795b2da558e8f595706e7a46f11b891f8be Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 15:14:06 +0100 Subject: [PATCH 13/29] Update src/hb-icu.cc Co-Authored-By: Khaled Hosny --- src/hb-icu.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/hb-icu.cc b/src/hb-icu.cc index ad75710bd..da2ff57de 100644 --- a/src/hb-icu.cc +++ b/src/hb-icu.cc @@ -372,7 +372,7 @@ void free_static_icu_funcs () * Fetches a Unicode-functions structure that is populated * with the appropriate ICU function for each method. * - * Return value: (transfer full): a pointer to the #hb_unicode_funcs_t Unicode-functions structure + * Return value: (transfer none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure * * Since: 0.9.38 **/ From a199eab20eca8710e58fab845b8c330aada797a3 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 15:14:28 +0100 Subject: [PATCH 14/29] Update src/hb-graphite2.cc Co-Authored-By: Khaled Hosny --- src/hb-graphite2.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/hb-graphite2.cc b/src/hb-graphite2.cc index 32446c669..5db524a9f 100644 --- a/src/hb-graphite2.cc +++ b/src/hb-graphite2.cc @@ -43,7 +43,7 @@ * * Functions for using HarfBuzz with fonts that include Graphite2 features. * - * For Graphite2 features to work, you must be sure that HarfBuzz was compiled + * For Graphite features to work, you must be sure that HarfBuzz was compiled * with the `graphite2` shaping engine enabled. Currently, the default is to * not enable `graphite2` shaping. **/ From fb9d106797f4ae458717dd9e9d0b2c9eca4b89c2 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 15:14:42 +0100 Subject: [PATCH 15/29] Update src/hb-graphite2.cc Co-Authored-By: Khaled Hosny --- src/hb-graphite2.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/hb-graphite2.cc b/src/hb-graphite2.cc index 5db524a9f..a061d413e 100644 --- a/src/hb-graphite2.cc +++ b/src/hb-graphite2.cc @@ -41,7 +41,7 @@ * @short_description: Graphite2 integration * @include: hb-graphite2.h * - * Functions for using HarfBuzz with fonts that include Graphite2 features. + * Functions for using HarfBuzz with fonts that include Graphite features. * * For Graphite features to work, you must be sure that HarfBuzz was compiled * with the `graphite2` shaping engine enabled. Currently, the default is to From fd59cc700ade05fa86b89d10cf07eef7f57c9973 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 15:15:00 +0100 Subject: [PATCH 16/29] Update src/hb-glib.cc Co-Authored-By: Khaled Hosny --- src/hb-glib.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/hb-glib.cc b/src/hb-glib.cc index b441efe0e..e530c5197 100644 --- a/src/hb-glib.cc +++ b/src/hb-glib.cc @@ -403,7 +403,7 @@ void free_static_glib_funcs () * Fetches a Unicode-functions structure that is populated * with the appropriate GLib function for each method. * - * Return value: (transfer full): a pointer to the #hb_unicode_funcs_t Unicode-functions structure + * Return value: (transfer none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure * * Since: 0.9.38 **/ From c241e82f00dad423bf1d15cc8e365224fb7a8575 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 15:28:42 +0100 Subject: [PATCH 17/29] Update docs/usermanual-integration.xml Co-Authored-By: Khaled Hosny --- docs/usermanual-integration.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 1085e96c5..8a3dd26a1 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -40,7 +40,7 @@ accessing font and face information, so HarfBuzz includes functions to create hb_face_t and hb_font_t objects directly from FreeType - objects. HarfBuzz will can use FreeType's built-in functions for + objects. HarfBuzz can use FreeType's built-in functions for font_funcs vtable in an hb_font_t. From a29578c17a10f409db651ed55f20ca3eb20953ae Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 15:30:18 +0100 Subject: [PATCH 18/29] Update usermanual-integration.xml --- docs/usermanual-integration.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 8a3dd26a1..f6425b4b4 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -31,7 +31,7 @@ hb_buffer_t passed to HarfBuzz for shaping contains Unicode code points that share the same segment properties (namely, direction, language, and script, but also higher-level - properties like the active font, font style, color, and so on). + properties like the active font, font style, and so on). The layer directly "below" HarfBuzz is typically FreeType, which From 3a47921e88ad20873e08e19dff22205ecdf48f98 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 15:42:00 +0100 Subject: [PATCH 19/29] Update usermanual-integration.xml --- docs/usermanual-integration.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index f6425b4b4..5b1180511 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -68,7 +68,7 @@ The Unicode information is necessary for shaping because the - properties of a code point (such as it's General Category (gc), + properties of a code point (such as its General Category (gc), Canonical Combining Class (ccc), and decomposition) can directly impact the shaping moves that HarfBuzz performs. From 9b91669cb4e92281f155e4b1b1cef26ba562e786 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 16:40:15 +0100 Subject: [PATCH 20/29] Update hb-ft.cc --- src/hb-ft.cc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/hb-ft.cc b/src/hb-ft.cc index dfafaf19e..2dadc02db 100644 --- a/src/hb-ft.cc +++ b/src/hb-ft.cc @@ -673,7 +673,7 @@ hb_ft_face_finalize (FT_Face ft_face) * Creates an #hb_face_t face object from the specified FT_Face. * * This variant of the function caches the newly created #hb_face_t - * face object, using the generic pointer of @ft_face. Subsequent function + * face object, using the @generic pointer of @ft_face. Subsequent function * calls that are passed the same @ft_face parameter will have the same * #hb_face_t returned to them, and that #hb_face_t will be correctly * reference counted. From 17b60efc38fbc32953424fa9a21daf3738ff8935 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 16:51:58 +0100 Subject: [PATCH 21/29] Update docs/usermanual-integration.xml Co-Authored-By: Khaled Hosny --- docs/usermanual-integration.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 5b1180511..43c0ce335 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -412,7 +412,7 @@ Core Text engine and the underlying Core Graphics framework. HarfBuzz does not attempt to offer the same drop-in-replacement functionality for Core Text that it strives - for with Uniscribe on Windows, but you can still user HarfBuzz + for with Uniscribe on Windows, but you can still use HarfBuzz to perform text shaping in native macOS and iOS applications. From f782d736cefa7808ef31712bcc6a51cfa2d02826 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 16:57:36 +0100 Subject: [PATCH 22/29] Update usermanual-integration.xml --- docs/usermanual-integration.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 43c0ce335..6bb4a8c12 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -481,14 +481,14 @@ As a final note, you may notice a reference to an optional coretext shaper back-end in the section of the HarfBuzz manual. This - option is not a CoreText-integration facility. + option is not a Core Text-integration facility. Instead, it is a internal code path used in the hb-shape command-line utility, which hands - shaping functionality over to CoreText entirely, when run on a + shaping functionality over to Core Text entirely, when run on a macOS system. That allows testing HarfBuzz's native output - against the CoreText engine, for tracking compatibility and debugging. + against the Core Text engine, for tracking compatibility and debugging. Because this back-end is only used when testing HarfBuzz From 05b7bdb4dd57d1bf233379e0f4ae5ec6451113d7 Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 16:59:41 +0100 Subject: [PATCH 23/29] Update usermanual-integration.xml --- docs/usermanual-integration.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 6bb4a8c12..85f6022b6 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -506,7 +506,7 @@ on any supported platform. - The principle integration point with ICU is the + The principal integration point with ICU is the hb_unicode_funcs_t Unicode-functions structure attached to a buffer. This structure holds the virtual methods used for retrieving Unicode character properties, such as From 9457b60edc6f3c7b3b4ccf7460d4569c072bc98e Mon Sep 17 00:00:00 2001 From: n8willis Date: Mon, 13 Apr 2020 17:01:15 +0100 Subject: [PATCH 24/29] Update usermanual-integration.xml --- docs/usermanual-integration.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 85f6022b6..66060f466 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -315,8 +315,8 @@ accurately reproduce the same output for shaping a given text segment that Uniscribe produces — even to the point of duplicating known shaping bugs or deviations from the - specification — so you can be sure that your users' - documents with their existing fonts will not be affected by + specification — so you can be confident that your users' + documents with their existing fonts will not be affected adversely by switching to HarfBuzz. From 80c01d768734faafe5701414bd63c63cd243a404 Mon Sep 17 00:00:00 2001 From: n8willis Date: Wed, 15 Apr 2020 18:08:55 +0100 Subject: [PATCH 25/29] Update hb-ft.cc --- src/hb-ft.cc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/hb-ft.cc b/src/hb-ft.cc index 2dadc02db..efe3dd0a0 100644 --- a/src/hb-ft.cc +++ b/src/hb-ft.cc @@ -645,7 +645,8 @@ hb_ft_face_create (FT_Face ft_face, * This is the preferred variant of the hb_ft_face_create* * function family, because it calls FT_Reference_Face() on @ft_face, * ensuring that @ft_face remains alive as long as the resulting - * #hb_face_t face object remains alive. + * #hb_face_t face object remains alive. Also calls FT_Done_Face() + * when the #hb_face_t face object is destroyed. * * Use this version unless you know you have good reasons not to. * From 1bca2be256ce1c2c4d74efac2286db80dbfa5c48 Mon Sep 17 00:00:00 2001 From: n8willis Date: Wed, 15 Apr 2020 18:30:47 +0100 Subject: [PATCH 26/29] Rewrite hb_ft_font_set_funcs inline explanation --- src/hb-ft.cc | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/hb-ft.cc b/src/hb-ft.cc index efe3dd0a0..804897ce4 100644 --- a/src/hb-ft.cc +++ b/src/hb-ft.cc @@ -887,9 +887,18 @@ _release_blob (FT_Face ft_face) * Configures the font-functions structure of the specified * #hb_font_t font object to use FreeType font functions. * + * In particular, you can use this function to configure an + * existing #hb_face_t face object for use with FreeType font + * functions even if that #hb_face_t face object was initially + * created with hb_face_create(), and therefore was not + * initially configured to use FreeType font functions. + * + * An #hb_face_t face object created with hb_ft_face_create() + * is preconfigured for FreeType font functions and does not + * require this function to be used. + * * Note: Internally, this function creates an FT_Face. - * You should use this FT_Face when you create an #hb_face_t - * with hb_ft_face_create(). +* * * Since: 1.0.5 **/ From b57b9042420538f998cc0941407be8059b6e7562 Mon Sep 17 00:00:00 2001 From: n8willis Date: Wed, 15 Apr 2020 18:46:31 +0100 Subject: [PATCH 27/29] Add detail to hb_ft_font_create inline comments Providing lengthier explanation for how the destroy function works on the hb_font_t but that destroying the FT_Face (and not destroying it too early) remains the client's responsibility. --- src/hb-ft.cc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/hb-ft.cc b/src/hb-ft.cc index 804897ce4..d62198342 100644 --- a/src/hb-ft.cc +++ b/src/hb-ft.cc @@ -721,6 +721,12 @@ hb_ft_face_create_cached (FT_Face ft_face) * then it is the client program's responsibility to destroy @ft_face * after the #hb_font_t font object has been destroyed. * + * HarfBuzz will use the @destroy callback on the #hb_font_t font object + * if it is supplied when you use this function. However, even if @destroy + * is provided, it is the client program's responsibility to destroy @ft_face, + * and it is the client program's responsibility to ensure that @ft_face is + * destroyed only after the #hb_font_t font object has been destroyed. + * * Return value: (transfer full): the new #hb_font_t font object * * Since: 0.9.2 From d6edd9a4083f523b6290ba29c1fcbb5a6b7f96bb Mon Sep 17 00:00:00 2001 From: n8willis Date: Sun, 19 Apr 2020 15:26:28 +0100 Subject: [PATCH 28/29] [Docs, usermanual] Reword hb_ft_font_create_referenced explanation --- docs/usermanual-integration.xml | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 66060f466..5f922ab10 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -207,18 +207,27 @@ FT_Set_Char_Size(face, 0, 1000, 0, 0); hb_font_t *font = hb_ft_font_create(face); + + hb_ft_font_create_referenced() is + the recommended function for creating an hb_face_t face + object. This function calls FT_Reference_Face() + before using the FT_Face and calls + FT_Done_Face() when it is finished using the + FT_Face. Consequently, your client program does not need + to worry about destroying the FT_Face while HarfBuzz + is still using it. + Although hb_ft_font_create_referenced() is - the recommended function, there is another variant. The simpler - version of the function is - hb_ft_font_create(), which takes an - FT_Face and an optional destroy callback as its - arguments. The critical difference between the two is that - hb_ft_font_create() does not offer the - lifecycle-management feature. Your client code will be - responsible for tracking references to the FT_Face objects and - destroying them when they are no longer needed. If you do not - have a valid reason for doing this, user + the recommended function, there is another variant for client code + where special circumstances make it necessary. The simpler + version of the function is hb_ft_font_create(), + which takes an FT_Face and an optional destroy callback + as its arguments. Because hb_ft_font_create() + does not offer lifecycle management, however, your client code will + be responsible for tracking references to the FT_Face + objects and destroying them when they are no longer needed. If you + do not have a valid reason for doing this, use hb_ft_font_create_referenced(). From 1ed30515cb6308f1cf651cd502012ee5c8bd24ef Mon Sep 17 00:00:00 2001 From: n8willis Date: Sun, 19 Apr 2020 15:38:52 +0100 Subject: [PATCH 29/29] [Docs, usernmanual] Fix with-icu=builtin explanation --- docs/usermanual-integration.xml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml index 5f922ab10..78c9a0e38 100644 --- a/docs/usermanual-integration.xml +++ b/docs/usermanual-integration.xml @@ -550,11 +550,15 @@ to a hb_script_t. - By default, ICU support is included when compiling HarfBuzz from - source. The build system will look for the ICU library and link - to it if it is found. You can also build HarfBuzz with it own, - internal copy of ICU, by specifying the - --with-icu=builtin compile-time option. + By default, HarfBuzz's ICU support is built as a separate shared + library (libharfbuzz-icu.so) + when compiling HarfBuzz from source. This allows client programs + that do not need ICU to link against HarfBuzz without unnecessarily + adding ICU as a dependency. You can also build HarfBuzz with ICU + support built directly into the main HarfBuzz shared library + (libharfbuzz.so), + by specifying the --with-icu=builtin + compile-time option.