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