One Hat Cyber Team

View File Name : integration.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Platform Integration Guide: HarfBuzz Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="HarfBuzz Manual">
<link rel="up" href="pt01.html" title="Part I. User's manual">
<link rel="prev" href="utilities-ucdn.html" title="UCDN">
<link rel="next" href="integration-freetype.html" title="FreeType integration">
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="utilities-ucdn.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="integration-freetype.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="integration"></a>Platform Integration Guide</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="integration.html#integration-glib">GNOME integration, GLib, and GObject</a></span></dt>
<dt><span class="section"><a href="integration-freetype.html">FreeType integration</a></span></dt>
<dt><span class="section"><a href="integration-uniscribe.html">Uniscribe integration</a></span></dt>
<dt><span class="section"><a href="integration-coretext.html">Core Text integration</a></span></dt>
<dt><span class="section"><a href="integration-icu.html">ICU integration</a></span></dt>
<dt><span class="section"><a href="integration-python.html">Python bindings</a></span></dt>
</dl></div>
<p>
    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.
  </p>
<p>
    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.
  </p>
<p>
    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
    <span class="type">hb_buffer_t</span> 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).
  </p>
<p>
    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 <span class="type">hb_face_t</span> and
    <span class="type">hb_font_t</span> objects directly from FreeType
    objects. HarfBuzz can use FreeType's built-in functions for
    <em class="structfield"><code>font_funcs</code></em> vtable in an <span class="type">hb_font_t</span>.
  </p>
<p>
    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.
  </p>
<p>
    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.
  </p>
<p>
    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.
  </p>
<p>
    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.
  </p>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="integration-glib"></a>GNOME integration, GLib, and GObject</h2></div></div></div>
<p>
      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. 
    </p>
<p>
      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.
    </p>
<p>
      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
      <code class="filename">hb-glib.h</code> header file.
    </p>
<p>
      GLib's <a class="ulink" href="https://developer.gnome.org/glib/stable/glib-Unicode-Manipulation.html" target="_top">Unicode
      manipulation API</a> includes all the functionality
      necessary to retrieve Unicode data for the
      <em class="structfield"><code>unicode_funcs</code></em> structure of a HarfBuzz
      <span class="type">hb_buffer_t</span>. 
    </p>
<p>
      The function <code class="function">hb_glib_get_unicode_funcs()</code>
      sets up a <span class="type">hb_unicode_funcs_t</span> structure configured
      with the GLib Unicode functions and returns a pointer to it.
    </p>
<p>
      You can attach this Unicode-functions structure to your buffer,
      and it will be ready for use with GLib:
    </p>
<pre class="programlisting">
      #include &lt;hb-glib.h&gt;
      ...
      hb_unicode_funcs_t *glibufunctions;
      glibufunctions = hb_glib_get_unicode_funcs();
      hb_buffer_set_unicode_funcs(buf, glibufunctions);
    </pre>
<p>
      For script information, GLib uses the
      <span class="type">GUnicodeScript</span> type. Like HarfBuzz's own
      <span class="type">hb_script_t</span>, this data type is an enumeration
      of Unicode scripts, but text segments passed in from GLib code
      will be tagged with a <span class="type">GUnicodeScript</span>. Therefore,
      when setting the script property on a <span class="type">hb_buffer_t</span>,
      you will need to convert between the <span class="type">GUnicodeScript</span>
      of the input provided by GLib and HarfBuzz's
      <span class="type">hb_script_t</span> type.
    </p>
<p>
      The <code class="function">hb_glib_script_to_script()</code> function
      takes an <span class="type">GUnicodeScript</span> script identifier as its
      sole argument and returns the corresponding <span class="type">hb_script_t</span>.
      The <code class="function">hb_glib_script_from_script()</code> does the
      reverse, taking an <span class="type">hb_script_t</span> and returning the
      <span class="type">GUnicodeScript</span> identifier for GLib.
    </p>
<p>
      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>
      that is used for accessing raw memory segments with the benefits
      of GLib's lifecycle management. HarfBuzz provides a
      <code class="function">hb_glib_blob_create()</code> function that lets
      you create an <span class="type">hb_blob_t</span> directly from a
      <span class="type">GBytes</span> object. This function takes only the
      <span class="type">GBytes</span> object as its input; HarfBuzz registers the
      GLib <code class="function">destroy</code> callback automatically.
    </p>
<p>
      The GNOME platform also features an object system called
      GObject. For HarfBuzz, the main advantage of GObject is a
      feature called <a class="ulink" href="https://gi.readthedocs.io/en/latest/" target="_top">GObject
      Introspection</a>. 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.
    </p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>