docs/html/shaping-opentype-features.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>OpenType features: 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="shaping-and-shape-plans.html" title="Shaping and shape plans">
   9 <link rel="prev" href="shaping-and-shape-plans.html" title="Shaping and shape plans">
  10 <link rel="next" href="shaping-shaper-selection.html" title="Shaper selection">
  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="shaping-and-shape-plans.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="shaping-and-shape-plans.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="shaping-shaper-selection.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="shaping-opentype-features"></a>OpenType features</h2></div></div></div>
  25 <p>
  26       OpenType features enable fonts to include smart behavior,
  27       implemented as "lookup" rules stored in the GSUB and GPOS
  28       tables. The OpenType specification defines a long list of
  29       standard features that fonts can use for these behaviors; each
  30       feature has a four-character reserved name and a well-defined
  31       semantic meaning.
  32     </p>
  33 <p>
  34       Some OpenType features are defined for the purpose of supporting
  35       script-specific shaping, and are automatically activated, but
  36       only when a buffer's script property is set to a script that the
  37       feature supports.
  38     </p>
  39 <p>
  40       Other features are more generic and can apply to several (or
  41       any) script, and shaping engines are expected to implement
  42       them. By default, HarfBuzz activates several of these features
  43       on every text run. They include <code class="literal">abvm</code>,
  44       <code class="literal">blwm</code>, <code class="literal">ccmp</code>,
  45       <code class="literal">locl</code>, <code class="literal">mark</code>,
  46       <code class="literal">mkmk</code>, and <code class="literal">rlig</code>.
  47     </p>
  48 <p>
  49       In addition, if the text direction is horizontal, HarfBuzz
  50       also applies the <code class="literal">calt</code>,
  51       <code class="literal">clig</code>, <code class="literal">curs</code>,
  52       <code class="literal">dist</code>, <code class="literal">kern</code>,
  53       <code class="literal">liga</code> and <code class="literal">rclt</code>, features.
  54     </p>
  55 <p>
  56       Additionally, when HarfBuzz encounters a fraction slash
  57       (<code class="literal">U+2044</code>), it looks backward and forward for decimal
  58       digits (Unicode General Category = Nd), and enables features
  59       <code class="literal">numr</code> on the sequence before the fraction slash,
  60       <code class="literal">dnom</code> on the sequence after the fraction slash,
  61       and <code class="literal">frac</code> on the whole sequence including the fraction
  62       slash.
  63     </p>
  64 <p>
  65       Some script-specific shaping models
  66       (see <a class="xref" href="opentype-shaping-models.html" title="OpenType shaping models">the section called “OpenType shaping models”</a>) disable some of the
  67       features listed above:
  68     </p>
  69 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  70 <li class="listitem"><p>
  71           Hangul: <code class="literal">calt</code>
  72         </p></li>
  73 <li class="listitem"><p>
  74           Indic: <code class="literal">liga</code>
  75         </p></li>
  76 <li class="listitem"><p>
  77           Khmer: <code class="literal">liga</code>
  78         </p></li>
  79 </ul></div>
  80 <p>
  81       If the text direction is vertical, HarfBuzz applies
  82       the <code class="literal">vert</code> feature by default.
  83     </p>
  84 <p>
  85       Still other features are designed to be purely optional and left
  86       up to the application or the end user to enable or disable as desired.
  87     </p>
  88 <p>
  89       You can adjust the set of features that HarfBuzz applies to a
  90       buffer by supplying an array of <span class="type">hb_feature_t</span>
  91       features as the third argument to
  92       <code class="function">hb_shape()</code>. For a simple case, let's just
  93       enable the <code class="literal">dlig</code> feature, which turns on any
  94       "discretionary" ligatures in the font:
  95     </p>
  96 <pre class="programlisting">
  97       hb_feature_t userfeatures[1];
  98       userfeatures[0].tag = HB_TAG('d','l','i','g');
  99       userfeatures[0].value = 1;
 100       userfeatures[0].start = HB_FEATURE_GLOBAL_START;
 101       userfeatures[0].end = HB_FEATURE_GLOBAL_END;
 102     </pre>
 103 <p>
 104       <code class="literal">HB_FEATURE_GLOBAL_END</code> and
 105       <code class="literal">HB_FEATURE_GLOBAL_END</code> are macros we can use
 106       to indicate that the features will be applied to the entire
 107       buffer. We could also have used a literal <code class="literal">0</code>
 108       for the start and a <code class="literal">-1</code> to indicate the end of
 109       the buffer (or have selected other start and end positions, if needed).
 110     </p>
 111 <p>
 112       When we pass the <code class="varname">userfeatures</code> array to
 113       <code class="function">hb_shape()</code>, any discretionary ligature
 114       substitutions from our font that match the text in our buffer
 115       will get performed:
 116     </p>
 117 <pre class="programlisting">
 118       hb_shape(font, buf, userfeatures, num_features);
 119     </pre>
 120 <p>
 121       Just like we enabled the <code class="literal">dlig</code> feature by
 122       setting its <em class="parameter"><code>value</code></em> to
 123       <code class="literal">1</code>, you would disable a feature by setting its
 124       <em class="parameter"><code>value</code></em> to <code class="literal">0</code>. Some
 125       features can take other <em class="parameter"><code>value</code></em> settings;
 126       be sure you read the full specification of each feature tag to
 127       understand what it does and how to control it.
 128     </p>
 129 </div>
 130 <div class="footer">
 131 <hr>Generated by GTK-Doc V1.32</div>
 132 </body>
 133 </html>