docs/html/integration-coretext.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>Core Text 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-uniscribe.html" title="Uniscribe integration">
  10 <link rel="next" href="integration-icu.html" title="ICU 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-uniscribe.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="integration-icu.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-coretext"></a>Core Text integration</h2></div></div></div>
  25 <p>
  26       If your client program is running on macOS or iOS, HarfBuzz offers
  27       an additional API that can help integrate with Apple's
  28       Core Text engine and the underlying Core Graphics
  29       framework. HarfBuzz does not attempt to offer the same
  30       drop-in-replacement functionality for Core Text that it strives
  31       for with Uniscribe on Windows, but you can still use HarfBuzz
  32       to perform text shaping in native macOS and iOS applications.
  33     </p>
  34 <p>
  35       Note, though, that if your interest is just in using fonts that
  36       contain Apple Advanced Typography (AAT) features, then you do
  37       not need to add Core Text integration. HarfBuzz natively
  38       supports AAT features and will shape AAT fonts (on any platform)
  39       automatically, without requiring additional work on your
  40       part. This includes support for AAT-specific TrueType tables
  41       such as <code class="literal">mort</code>, <code class="literal">morx</code>, and
  42       <code class="literal">kerx</code>, which AAT fonts use instead of
  43       <code class="literal">GSUB</code> and <code class="literal">GPOS</code>.
  44     </p>
  45 <p>
  46       On a macOS or iOS system, the primary integration points offered
  47       by HarfBuzz are for face objects and font objects.
  48     </p>
  49 <p>
  50       The Apple APIs offer a pair of data structures that map well to
  51       HarfBuzz's face and font objects. The Core Graphics API, which
  52       is slightly lower-level than Core Text, provides
  53       <a class="ulink" href="https://developer.apple.com/documentation/coregraphics/cgfontref" target="_top"><span class="type">CGFontRef</span></a>, which enables access to typeface
  54       properties, but does not include size information. Core Text's
  55       <a class="ulink" href="https://developer.apple.com/documentation/coretext/ctfont-q6r" target="_top"><span class="type">CTFontRef</span></a> is analagous to a HarfBuzz font object,
  56       with all of the properties required to render text at a specific
  57       size and configuration.
  58       Consequently, a HarfBuzz <span class="type">hb_font_t</span> font object can
  59       be hooked up to a Core Text <span class="type">CTFontRef</span>, and a HarfBuzz
  60       <span class="type">hb_face_t</span> face object can be hooked up to a
  61       <span class="type">CGFontRef</span>.
  62     </p>
  63 <p>
  64       You can create a <span class="type">hb_face_t</span> from a
  65       <span class="type">CGFontRef</span> by using the
  66       <code class="function">hb_coretext_face_create()</code>. Subsequently,
  67       you can retrieve the <span class="type">CGFontRef</span> from a
  68       <span class="type">hb_face_t</span> with <code class="function">hb_coretext_face_get_cg_font()</code>.
  69     </p>
  70 <p>
  71       Likewise, you create a <span class="type">hb_font_t</span> from a
  72       <span class="type">CTFontRef</span> by calling
  73       <code class="function">hb_coretext_font_create()</code>, and you can
  74       fetch the associated <span class="type">CTFontRef</span> from a
  75       <span class="type">hb_font_t</span> font object with
  76       <code class="function">hb_coretext_face_get_ct_font()</code>.
  77     </p>
  78 <p>
  79       HarfBuzz also offers a <code class="function">hb_font_set_ptem()</code>
  80       that you an use to set the nominal point size on any
  81       <span class="type">hb_font_t</span> font object. Core Text uses this value to
  82       implement optical scaling.
  83     </p>
  84 <p>
  85       When integrating your client code with Core Text, it is
  86       important to recognize that Core Text <code class="literal">points</code>
  87       are not typographic points (standardized at 72 per inch) as the
  88       term is used elsewhere in OpenType. Instead, Core Text points
  89       are CSS points, which are standardized at 96 per inch.
  90     </p>
  91 <p>
  92       HarfBuzz's font functions take this distinction into account,
  93       but it can be an easy detail to miss in cross-platform
  94       code.
  95     </p>
  96 <p>
  97       As a final note, you may notice a reference to an optional
  98       <code class="literal">coretext</code> shaper back-end in the <a class="xref" href="building.html#configuration" title="Configuration options">the section called “Configuration options”</a> section of the HarfBuzz manual. This
  99       option is not a Core Text-integration facility.
 100     </p>
 101 <p>
 102       Instead, it is a internal code path used in the
 103       <span class="command"><strong>hb-shape</strong></span> command-line utility, which hands
 104       shaping functionality over to Core Text entirely, when run on a
 105       macOS system. That allows testing HarfBuzz's native output
 106       against the Core Text engine, for tracking compatibility and debugging.
 107     </p>
 108 <p>
 109       Because this back-end is only used when testing HarfBuzz
 110       functionality, it is disabled by default when building the
 111       HarfBuzz binaries.
 112     </p>
 113 </div>
 114 <div class="footer">
 115 <hr>Generated by GTK-Doc V1.32.1</div>
 116 </body>
 117 </html>