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 Vsnapshot">
   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-uniscribe.html" title="Uniscribe 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="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-uniscribe.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. To use the
  38       FreeType-integration API, include the
  39       <code class="filename">hb-ft.h</code> header.
  40     </p>
  41 <p>
  42       In a typical client program, you will create your
  43       <span class="type">hb_face_t</span> face object and <span class="type">hb_font_t</span>
  44       font object from a FreeType <span class="type">FT_Face</span>. HarfBuzz
  45       provides a suite of functions for doing this.
  46     </p>
  47 <p>
  48       In the most common case, you will want to use
  49       <code class="function">hb_ft_font_create_referenced()</code>, which
  50       creates both an <span class="type">hb_face_t</span> face object and
  51       <span class="type">hb_font_t</span> font object (linked to that face object),
  52       and provides lifecycle management.
  53     </p>
  54 <p>
  55       It is important to note,
  56       though, that while HarfBuzz makes a distinction between its face and
  57       font objects, FreeType's <span class="type">FT_Face</span> does not. After
  58       you create your <span class="type">FT_Face</span>, you must set its size
  59       parameter using <code class="function">FT_Set_Char_Size()</code>, because
  60       an <span class="type">hb_font_t</span> is defined as an instance of an
  61       <span class="type">hb_face_t</span> with size specified.
  62     </p>
  63 <pre class="programlisting">
  64       #include &lt;hb-ft.h&gt;
  65       ...
  66       FT_New_Face(ft_library, font_path, index, &amp;face);
  67       FT_Set_Char_Size(face, 0, 1000, 0, 0);
  68       hb_font_t *font = hb_ft_font_create(face);
  69     </pre>
  70 <p>
  71       <code class="function">hb_ft_font_create_referenced()</code> is
  72       the recommended function for creating an <span class="type">hb_face_t</span> face
  73       object. This function calls <code class="function">FT_Reference_Face()</code>
  74       before using the <span class="type">FT_Face</span> and calls
  75       <code class="function">FT_Done_Face()</code> when it is finished using the
  76       <span class="type">FT_Face</span>. Consequently, your client program does not need
  77       to worry about destroying the <span class="type">FT_Face</span> while HarfBuzz
  78       is still using it.
  79     </p>
  80 <p>
  81       Although <code class="function">hb_ft_font_create_referenced()</code> is
  82       the recommended function, there is another variant for client code
  83       where special circumstances make it necessary. The simpler
  84       version of the function is <code class="function">hb_ft_font_create()</code>,
  85       which takes an <span class="type">FT_Face</span> and an optional destroy callback
  86       as its arguments. Because <code class="function">hb_ft_font_create()</code>
  87       does not offer lifecycle management, however, your client code will
  88       be responsible for tracking references to the <span class="type">FT_Face</span>
  89       objects and destroying them when they are no longer needed. If you
  90       do not have a valid reason for doing this, use
  91       <code class="function">hb_ft_font_create_referenced()</code>.
  92     </p>
  93 <p>
  94       After you have created your font object from your
  95       <span class="type">FT_Face</span>, you can set or retrieve the
  96       <em class="structfield"><code>load_flags</code></em> of the
  97       <span class="type">FT_Face</span> through the <span class="type">hb_font_t</span>
  98       object. HarfBuzz provides
  99       <code class="function">hb_ft_font_set_load_flags()</code> and
 100       <code class="function">hb_ft_font_get_load_flags()</code> for this
 101       purpose. The ability to set the
 102       <em class="structfield"><code>load_flags</code></em> through the font object
 103       could be useful for enabling or disabling hinting, for example,
 104       or to activate vertical layout.
 105     </p>
 106 <p>
 107       HarfBuzz also provides a utility function called
 108       <code class="function">hb_ft_font_has_changed()</code> that you should
 109       call whenever you have altered the properties of your underlying
 110       <span class="type">FT_Face</span>, as well as a
 111       <code class="function">hb_ft_get_face()</code> that you can call on an
 112       <span class="type">hb_font_t</span> font object to fetch its underlying <span class="type">FT_Face</span>.
 113     </p>
 114 <p>
 115       With an <span class="type">hb_face_t</span> and <span class="type">hb_font_t</span> both linked
 116       to your <span class="type">FT_Face</span>, you will typically also want to
 117       use FreeType for the <em class="structfield"><code>font_funcs</code></em>
 118       vtable of your <span class="type">hb_font_t</span>. As a reminder, this
 119       font-functions structure is the set of methods that HarfBuzz
 120       will use to fetch important information from the font, such as
 121       the advances and extents of individual glyphs.
 122     </p>
 123 <p>
 124       All you need to do is call
 125     </p>
 126 <pre class="programlisting">
 127       hb_ft_font_set_funcs(font);
 128     </pre>
 129 <p>
 130       and HarfBuzz will use FreeType for the font-functions in
 131       <code class="literal">font</code>.
 132     </p>
 133 <p>
 134       As we noted above, an <span class="type">hb_font_t</span> is derived from an
 135       <span class="type">hb_face_t</span> with size (and, perhaps, other
 136       parameters, such as variation-axis coordinates)
 137       specified. Consequently, you can reuse an <span class="type">hb_face_t</span>
 138       with several <span class="type">hb_font_t</span> objects, and HarfBuzz
 139       provides functions to simplify this.
 140     </p>
 141 <p>
 142       The <code class="function">hb_ft_face_create_referenced()</code>
 143       function creates just an <span class="type">hb_face_t</span> from a FreeType
 144       <span class="type">FT_Face</span> and, as with
 145       <code class="function">hb_ft_font_create_referenced()</code> above,
 146       provides lifecycle management for the <span class="type">FT_Face</span>.
 147     </p>
 148 <p>
 149       Similarly, there is an <code class="function">hb_ft_face_create()</code>
 150       function variant that does not provide the lifecycle-management
 151       feature. As with the font-object case, if you use this version
 152       of the function, it will be your client code's respsonsibility
 153       to track usage of the <span class="type">FT_Face</span> objects.
 154     </p>
 155 <p>
 156       A third variant of this function is
 157       <code class="function">hb_ft_face_create_cached()</code>, which is the
 158       same as <code class="function">hb_ft_face_create()</code> except that it
 159       also uses the <em class="structfield"><code>generic</code></em> field of the
 160       <span class="type">FT_Face</span> structure to save a pointer to the newly
 161       created <span class="type">hb_face_t</span>. Subsequently, function calls
 162       that pass the same <span class="type">FT_Face</span> will get the same
 163       <span class="type">hb_face_t</span> returned — and the
 164       <span class="type">hb_face_t</span> will be correctly reference
 165       counted. Still, as with
 166       <code class="function">hb_ft_face_create()</code>, your client code must
 167       track references to the <span class="type">FT_Face</span> itself, and destroy
 168       it when it is unneeded.
 169     </p>
 170 </div>
 171 <div class="footer">
 172 <hr>Generated by GTK-Doc V1.32.1</div>
 173 </body>
 174 </html>