docs/html/integration-freetype.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>FreeType integration: 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="integration.html" title="Platform Integration Guide">
   9 <link rel="prev" href="integration.html" title="Platform Integration Guide">
  10 <link rel="next" href="integration-cairo.html" title="Cairo 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="integration.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="integration.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="integration-cairo.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="section">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="integration-freetype"></a>FreeType integration</h2></div></div></div>
  25 <p>
  26       FreeType is the free-software font-rendering engine included in
  27       desktop Linux distributions, Android, ChromeOS, iOS, and multiple Unix
  28       operating systems, and used by cross-platform programs like
  29       Chrome, Java, and GhostScript. Used together, HarfBuzz can
  30       perform shaping on Unicode text segments, outputting the glyph
  31       IDs that FreeType should rasterize from the active font as well
  32       as the positions at which those glyphs should be drawn.
  33     </p>
  34 <p>
  35       HarfBuzz provides integration points with FreeType at the
  36       face-object and font-object level and for the font-functions
  37       virtual-method structure of a font object. These functions
  38       make it easy for clients that use FreeType for rasterization
  39       or font-loading, to use HarfBuzz for shaping. To use the
  40       FreeType-integration API, include the
  41       <code class="filename">hb-ft.h</code> header.
  42     </p>
  43 <p>
  44       In a typical client program, you will create your
  45       <span class="type">hb_face_t</span> face object and <span class="type">hb_font_t</span>
  46       font object from a FreeType <span class="type">FT_Face</span>. HarfBuzz
  47       provides a suite of functions for doing this.
  48     </p>
  49 <p>
  50       In the most common case, you will want to use
  51       <code class="function">hb_ft_font_create_referenced()</code>, which
  52       creates both an <span class="type">hb_face_t</span> face object and
  53       <span class="type">hb_font_t</span> font object (linked to that face object),
  54       and provides lifecycle management.
  55     </p>
  56 <p>
  57       It is important to note,
  58       though, that while HarfBuzz makes a distinction between its face and
  59       font objects, FreeType's <span class="type">FT_Face</span> does not. After
  60       you create your <span class="type">FT_Face</span>, you must set its size
  61       parameter using <code class="function">FT_Set_Char_Size()</code>, because
  62       an <span class="type">hb_font_t</span> is defined as an instance of an
  63       <span class="type">hb_face_t</span> with size specified.
  64     </p>
  65 <pre class="programlisting">
  66       #include &lt;hb-ft.h&gt;
  67       ...
  68       FT_New_Face(ft_library, font_path, index, &amp;face);
  69       FT_Set_Char_Size(face, 0, 1000, 0, 0);
  70       hb_font_t *font = hb_ft_font_create(face);
  71     </pre>
  72 <p>
  73       <code class="function">hb_ft_font_create_referenced()</code> is
  74       the recommended function for creating an <span class="type">hb_face_t</span> face
  75       object. This function calls <code class="function">FT_Reference_Face()</code>
  76       before using the <span class="type">FT_Face</span> and calls
  77       <code class="function">FT_Done_Face()</code> when it is finished using the
  78       <span class="type">FT_Face</span>. Consequently, your client program does not need
  79       to worry about destroying the <span class="type">FT_Face</span> while HarfBuzz
  80       is still using it.
  81     </p>
  82 <p>
  83       Although <code class="function">hb_ft_font_create_referenced()</code> is
  84       the recommended function, there is another variant for client code
  85       where special circumstances make it necessary. The simpler
  86       version of the function is <code class="function">hb_ft_font_create()</code>,
  87       which takes an <span class="type">FT_Face</span> and an optional destroy callback
  88       as its arguments. Because <code class="function">hb_ft_font_create()</code>
  89       does not offer lifecycle management, however, your client code will
  90       be responsible for tracking references to the <span class="type">FT_Face</span>
  91       objects and destroying them when they are no longer needed. If you
  92       do not have a valid reason for doing this, use
  93       <code class="function">hb_ft_font_create_referenced()</code>.
  94     </p>
  95 <p>
  96       After you have created your font object from your
  97       <span class="type">FT_Face</span>, you can set or retrieve the
  98       <em class="structfield"><code>load_flags</code></em> of the
  99       <span class="type">FT_Face</span> through the <span class="type">hb_font_t</span>
 100       object. HarfBuzz provides
 101       <code class="function">hb_ft_font_set_load_flags()</code> and
 102       <code class="function">hb_ft_font_get_load_flags()</code> for this
 103       purpose. The ability to set the
 104       <em class="structfield"><code>load_flags</code></em> through the font object
 105       could be useful for enabling or disabling hinting, for example,
 106       or to activate vertical layout.
 107     </p>
 108 <p>
 109       HarfBuzz also provides a utility function called
 110       <code class="function">hb_ft_font_has_changed()</code> that you should
 111       call whenever you have altered the properties of your underlying
 112       <span class="type">FT_Face</span>, as well as a
 113       <code class="function">hb_ft_get_face()</code> that you can call on an
 114       <span class="type">hb_font_t</span> font object to fetch its underlying <span class="type">FT_Face</span>.
 115     </p>
 116 <p>
 117       With an <span class="type">hb_face_t</span> and <span class="type">hb_font_t</span> both linked
 118       to your <span class="type">FT_Face</span>, you will typically also want to
 119       use FreeType for the <em class="structfield"><code>font_funcs</code></em>
 120       vtable of your <span class="type">hb_font_t</span>. As a reminder, this
 121       font-functions structure is the set of methods that HarfBuzz
 122       will use to fetch important information from the font, such as
 123       the advances and extents of individual glyphs.
 124     </p>
 125 <p>
 126       All you need to do is call
 127     </p>
 128 <pre class="programlisting">
 129       hb_ft_font_set_funcs(font);
 130     </pre>
 131 <p>
 132       and HarfBuzz will use FreeType for the font-functions in
 133       <code class="literal">font</code>.
 134     </p>
 135 <p>
 136       As we noted above, an <span class="type">hb_font_t</span> is derived from an
 137       <span class="type">hb_face_t</span> with size (and, perhaps, other
 138       parameters, such as variation-axis coordinates)
 139       specified. Consequently, you can reuse an <span class="type">hb_face_t</span>
 140       with several <span class="type">hb_font_t</span> objects, and HarfBuzz
 141       provides functions to simplify this.
 142     </p>
 143 <p>
 144       The <code class="function">hb_ft_face_create_referenced()</code>
 145       function creates just an <span class="type">hb_face_t</span> from a FreeType
 146       <span class="type">FT_Face</span> and, as with
 147       <code class="function">hb_ft_font_create_referenced()</code> above,
 148       provides lifecycle management for the <span class="type">FT_Face</span>.
 149     </p>
 150 <p>
 151       Similarly, there is an <code class="function">hb_ft_face_create()</code>
 152       function variant that does not provide the lifecycle-management
 153       feature. As with the font-object case, if you use this version
 154       of the function, it will be your client code's respsonsibility
 155       to track usage of the <span class="type">FT_Face</span> objects.
 156     </p>
 157 <p>
 158       A third variant of this function is
 159       <code class="function">hb_ft_face_create_cached()</code>, which is the
 160       same as <code class="function">hb_ft_face_create()</code> except that it
 161       also uses the <em class="structfield"><code>generic</code></em> field of the
 162       <span class="type">FT_Face</span> structure to save a pointer to the newly
 163       created <span class="type">hb_face_t</span>. Subsequently, function calls
 164       that pass the same <span class="type">FT_Face</span> will get the same
 165       <span class="type">hb_face_t</span> returned — and the
 166       <span class="type">hb_face_t</span> will be correctly reference
 167       counted. Still, as with
 168       <code class="function">hb_ft_face_create()</code>, your client code must
 169       track references to the <span class="type">FT_Face</span> itself, and destroy
 170       it when it is unneeded.
 171     </p>
 172 </div>
 173 <div class="footer">
 174 <hr>Generated by GTK-Doc V1.32</div>
 175 </body>
 176 </html>