diff --git a/docs/Makefile.am b/docs/Makefile.am
index f4bf2fdbc..d1b985078 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -83,6 +83,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 433c20659..96965f422 100644
--- a/docs/harfbuzz-docs.xml
+++ b/docs/harfbuzz-docs.xml
@@ -39,6 +39,7 @@
+
diff --git a/docs/usermanual-integration.xml b/docs/usermanual-integration.xml
new file mode 100644
index 000000000..78c9a0e38
--- /dev/null
+++ b/docs/usermanual-integration.xml
@@ -0,0 +1,603 @@
+
+
+
+]>
+
+ 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 libraries 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, 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 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 its 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);
+
+
+ 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 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().
+
+
+ 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
+
+ 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 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
+ duplicating known shaping bugs or deviations from the
+ specification — so you can be confident that your users'
+ documents with their existing fonts will not be affected adversely 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.
+
+
+
+ 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.
+
+
+
+
+ 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 use 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 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 Core Text entirely, when run on a
+ macOS system. That allows testing HarfBuzz's native output
+ against the Core Text 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.
+
+
+
+
+ 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 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
+ 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, 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.
+
+
+
+
+
+ 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.
+
+
+
+
diff --git a/src/hb-coretext.cc b/src/hb-coretext.cc
index 7a900e255..2b065384d 100644
--- a/src/hb-coretext.cc
+++ b/src/hb-coretext.cc
@@ -278,13 +278,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 (_hb_cg_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
@@ -351,10 +370,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)
{
@@ -375,6 +401,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')
diff --git a/src/hb-ft.cc b/src/hb-ft.cc
index d1eeeff7b..b18b990b9 100644
--- a/src/hb-ft.cc
+++ b/src/hb-ft.cc
@@ -48,8 +48,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.
**/
@@ -127,10 +132,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
**/
@@ -150,11 +158,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
@@ -169,12 +181,14 @@ hb_ft_font_get_load_flags (hb_font_t *font)
}
/**
- * hb_ft_font_get_face:
- * @font:
+ * 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
*
- * Return value:
* Since: 0.9.2
**/
FT_Face
@@ -645,12 +659,22 @@ _hb_ft_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 *
@@ -680,11 +704,20 @@ 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. 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.
+ *
+ * Return value: (transfer full): the new #hb_face_t face object
*
- * Return value: (transfer full):
* Since: 0.9.38
**/
hb_face_t *
@@ -702,11 +735,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 *
@@ -724,15 +767,34 @@ 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.
+ *
+ * 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
*
- * Return value: (transfer full):
* Since: 0.9.2
**/
hb_font_t *
@@ -750,6 +812,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)
{
@@ -805,11 +877,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 *
@@ -868,6 +952,28 @@ _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.
+ *
+ * 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.
+*
+ *
+ * Since: 1.0.5
+ **/
void
hb_ft_font_set_funcs (hb_font_t *font)
{
diff --git a/src/hb-glib.cc b/src/hb-glib.cc
index db02b6760..058f65ae6 100644
--- a/src/hb-glib.cc
+++ b/src/hb-glib.cc
@@ -41,7 +41,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.
**/
@@ -169,6 +173,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)
{
@@ -185,6 +200,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)
{
@@ -373,6 +399,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 none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure
+ *
+ * Since: 0.9.38
+ **/
hb_unicode_funcs_t *
hb_glib_get_unicode_funcs ()
{
@@ -391,6 +427,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 7f4922ef1..7c46e2640 100644
--- a/src/hb-gobject-structs.cc
+++ b/src/hb-gobject-structs.cc
@@ -32,11 +32,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.
**/
diff --git a/src/hb-graphite2.cc b/src/hb-graphite2.cc
index 20599b986..d8a72dc2f 100644
--- a/src/hb-graphite2.cc
+++ b/src/hb-graphite2.cc
@@ -45,7 +45,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 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
+ * not enable `graphite2` shaping.
**/
@@ -152,7 +156,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..f299da9f7 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 Graphite
+ * features.
+ *
+ * For more information, see http://graphite.sil.org/
+ *
+ **/
#define HB_GRAPHITE2_TAG_SILF HB_TAG('S','i','l','f')
diff --git a/src/hb-icu.cc b/src/hb-icu.cc
index 985ff02dc..c1dcc24c2 100644
--- a/src/hb-icu.cc
+++ b/src/hb-icu.cc
@@ -54,7 +54,21 @@
* @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
@@ -66,6 +80,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)
{
@@ -350,6 +374,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 none): a pointer to the #hb_unicode_funcs_t Unicode-functions structure
+ *
+ * Since: 0.9.38
+ **/
hb_unicode_funcs_t *
hb_icu_get_unicode_funcs ()
{
diff --git a/src/hb-uniscribe.cc b/src/hb-uniscribe.cc
index d2204cbad..48a5dc50a 100644
--- a/src/hb-uniscribe.cc
+++ b/src/hb-uniscribe.cc
@@ -55,7 +55,7 @@
* @short_description: Windows integration
* @include: hb-uniscribe.h
*
- * Functions for using HarfBuzz with the Windows fonts.
+ * Functions for using HarfBuzz with Windows fonts.
**/
typedef HRESULT (WINAPI *SIOT) /*ScriptItemizeOpenType*/(
@@ -583,6 +583,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)
{
@@ -590,6 +600,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)
{