docs/html/integration.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Platform Integration Guide: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="pt01.html" title="Part I. User's manual">
   9 <link rel="prev" href="utilities-ucdn.html" title="UCDN">
  10 <link rel="next" href="integration-freetype.html" title="FreeType integration">
  11 <meta name="generator" content="GTK-Doc V1.32.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="utilities-ucdn.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="integration-freetype.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="chapter">
  23 <div class="titlepage"><div><div><h2 class="title">
  24 <a name="integration"></a>Platform Integration Guide</h2></div></div></div>
  25 <div class="toc"><dl class="toc">
  26 <dt><span class="section"><a href="integration.html#integration-glib">GNOME integration, GLib, and GObject</a></span></dt>
  27 <dt><span class="section"><a href="integration-freetype.html">FreeType integration</a></span></dt>
  28 <dt><span class="section"><a href="integration-uniscribe.html">Uniscribe integration</a></span></dt>
  29 <dt><span class="section"><a href="integration-coretext.html">Core Text integration</a></span></dt>
  30 <dt><span class="section"><a href="integration-icu.html">ICU integration</a></span></dt>
  31 <dt><span class="section"><a href="integration-python.html">Python bindings</a></span></dt>
  32 </dl></div>
  33 <p>
  34     HarfBuzz was first developed for use with the GNOME and GTK
  35     software stack commonly found in desktop Linux
  36     distributions. Nevertheless, it can be used on other operating
  37     systems and platforms, from iOS and macOS to Windows. It can also
  38     be used with other application frameworks and components, such as
  39     Android, Qt, or application-specific widget libraries.
  40   </p>
  41 <p>
  42     This chapter will look at how HarfBuzz fits into a typical
  43     text-rendering pipeline, and will discuss the APIs available to
  44     integrate HarfBuzz with contemporary Linux, Mac, and Windows
  45     software. It will also show how HarfBuzz integrates with popular
  46     external libraries like FreeType and International Components for
  47     Unicode (ICU) and describe the HarfBuzz language bindings for
  48     Python.
  49   </p>
  50 <p>
  51     On a GNOME system, HarfBuzz is designed to tie in with several
  52     other common system libraries. The most common architecture uses
  53     Pango at the layer directly "above" HarfBuzz; Pango is responsible
  54     for text segmentation and for ensuring that each input
  55     <span class="type">hb_buffer_t</span> passed to HarfBuzz for shaping contains
  56     Unicode code points that share the same segment properties
  57     (namely, direction, language, and script, but also higher-level
  58     properties like the active font, font style, and so on).
  59   </p>
  60 <p>
  61     The layer directly "below" HarfBuzz is typically FreeType, which
  62     is used to rasterize glyph outlines at the necessary optical size,
  63     hinting settings, and pixel resolution. FreeType provides APIs for
  64     accessing font and face information, so HarfBuzz includes
  65     functions to create <span class="type">hb_face_t</span> and
  66     <span class="type">hb_font_t</span> objects directly from FreeType
  67     objects. HarfBuzz can use FreeType's built-in functions for
  68     <em class="structfield"><code>font_funcs</code></em> vtable in an <span class="type">hb_font_t</span>.
  69   </p>
  70 <p>
  71     FreeType's output is bitmaps of the rasterized glyphs; on a
  72     typical Linux system these will then be drawn by a graphics
  73     library like Cairo, but those details are beyond HarfBuzz's
  74     control. On the other hand, at the top end of the stack, Pango is
  75     part of the larger GNOME framework, and HarfBuzz does include APIs
  76     for working with key components of GNOME's higher-level libraries
  77     — most notably GLib.
  78   </p>
  79 <p>
  80     For other operating systems or application frameworks, the
  81     critical integration points are where HarfBuzz gets font and face
  82     information about the font used for shaping and where HarfBuzz
  83     gets Unicode data about the input-buffer code points.
  84   </p>
  85 <p>
  86     The font and face information is necessary for text shaping
  87     because HarfBuzz needs to retrieve the glyph indices for
  88     particular code points, and to know the extents and advances of
  89     glyphs. Note that, in an OpenType variable font, both of those
  90     types of information can change with different variation-axis
  91     settings.
  92   </p>
  93 <p>
  94     The Unicode information is necessary for shaping because the
  95     properties of a code point (such as its General Category (gc),
  96     Canonical Combining Class (ccc), and decomposition) can directly
  97     impact the shaping moves that HarfBuzz performs.
  98   </p>
  99 <div class="section">
 100 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 101 <a name="integration-glib"></a>GNOME integration, GLib, and GObject</h2></div></div></div>
 102 <p>
 103       As mentioned in the preceding section, HarfBuzz offers
 104       integration APIs to help client programs using the
 105       GNOME and GTK framework commonly found in desktop Linux
 106       distributions.
 107     </p>
 108 <p>
 109       GLib is the main utility library for GNOME applications. It
 110       provides basic data types and conversions, file abstractions,
 111       string manipulation, and macros, as well as facilities like
 112       memory allocation and the main event loop.
 113     </p>
 114 <p>
 115       Where text shaping is concerned, GLib provides several utilities
 116       that HarfBuzz can take advantage of, including a set of
 117       Unicode-data functions and a data type for script
 118       information. Both are useful when working with HarfBuzz
 119       buffers. To make use of them, you will need to include the
 120       <code class="filename">hb-glib.h</code> header file.
 121     </p>
 122 <p>
 123       GLib's <a class="ulink" href="https://developer.gnome.org/glib/stable/glib-Unicode-Manipulation.html" target="_top">Unicode
 124       manipulation API</a> includes all the functionality
 125       necessary to retrieve Unicode data for the
 126       <em class="structfield"><code>unicode_funcs</code></em> structure of a HarfBuzz
 127       <span class="type">hb_buffer_t</span>.
 128     </p>
 129 <p>
 130       The function <code class="function">hb_glib_get_unicode_funcs()</code>
 131       sets up a <span class="type">hb_unicode_funcs_t</span> structure configured
 132       with the GLib Unicode functions and returns a pointer to it.
 133     </p>
 134 <p>
 135       You can attach this Unicode-functions structure to your buffer,
 136       and it will be ready for use with GLib:
 137     </p>
 138 <pre class="programlisting">
 139       #include &lt;hb-glib.h&gt;
 140       ...
 141       hb_unicode_funcs_t *glibufunctions;
 142       glibufunctions = hb_glib_get_unicode_funcs();
 143       hb_buffer_set_unicode_funcs(buf, glibufunctions);
 144     </pre>
 145 <p>
 146       For script information, GLib uses the
 147       <span class="type">GUnicodeScript</span> type. Like HarfBuzz's own
 148       <span class="type">hb_script_t</span>, this data type is an enumeration
 149       of Unicode scripts, but text segments passed in from GLib code
 150       will be tagged with a <span class="type">GUnicodeScript</span>. Therefore,
 151       when setting the script property on a <span class="type">hb_buffer_t</span>,
 152       you will need to convert between the <span class="type">GUnicodeScript</span>
 153       of the input provided by GLib and HarfBuzz's
 154       <span class="type">hb_script_t</span> type.
 155     </p>
 156 <p>
 157       The <code class="function">hb_glib_script_to_script()</code> function
 158       takes an <span class="type">GUnicodeScript</span> script identifier as its
 159       sole argument and returns the corresponding <span class="type">hb_script_t</span>.
 160       The <code class="function">hb_glib_script_from_script()</code> does the
 161       reverse, taking an <span class="type">hb_script_t</span> and returning the
 162       <span class="type">GUnicodeScript</span> identifier for GLib.
 163     </p>
 164 <p>
 165       Finally, GLib also provides a reference-counted object type called <a class="ulink" href="https://developer.gnome.org/glib/stable/glib-Byte-Arrays.html#GBytes" target="_top"><span class="type">GBytes</span></a>
 166       that is used for accessing raw memory segments with the benefits
 167       of GLib's lifecycle management. HarfBuzz provides a
 168       <code class="function">hb_glib_blob_create()</code> function that lets
 169       you create an <span class="type">hb_blob_t</span> directly from a
 170       <span class="type">GBytes</span> object. This function takes only the
 171       <span class="type">GBytes</span> object as its input; HarfBuzz registers the
 172       GLib <code class="function">destroy</code> callback automatically.
 173     </p>
 174 <p>
 175       The GNOME platform also features an object system called
 176       GObject. For HarfBuzz, the main advantage of GObject is a
 177       feature called <a class="ulink" href="https://gi.readthedocs.io/en/latest/" target="_top">GObject
 178       Introspection</a>. This is a middleware facility that can be
 179       used to generate language bindings for C libraries. HarfBuzz uses it
 180       to build its Python bindings, which we will look at in a separate section.
 181     </p>
 182 </div>
 183 </div>
 184 <div class="footer">
 185 <hr>Generated by GTK-Doc V1.32.1</div>
 186 </body>
 187 </html>