docs/html/what-harfbuzz-doesnt-do.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>What HarfBuzz doesn't do: 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="what-is-harfbuzz.html" title="What is HarfBuzz?">
   9 <link rel="prev" href="ch01s03.html" title="What does HarfBuzz do?">
  10 <link rel="next" href="why-is-it-called-harfbuzz.html" title="Why is it called HarfBuzz?">
  11 <meta name="generator" content="GTK-Doc V1.25 (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="what-is-harfbuzz.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="ch01s03.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="why-is-it-called-harfbuzz.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="what-harfbuzz-doesnt-do"></a>What HarfBuzz doesn't do</h2></div></div></div>
  25 <p>
  26       HarfBuzz will take a Unicode string, shape it, and give you the
  27       information required to lay it out correctly on a single
  28       horizontal (or vertical) line using the font provided. That is the
  29       extent of HarfBuzz's responsibility.
  30     </p>
  31 <p>
  32       It is important to note that if you are implementing a complete
  33       text-layout engine you may have other responsibilities that
  34       HarfBuzz will <span class="emphasis"><em>not</em></span> help you with. For example:
  35     </p>
  36 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  37 <li class="listitem">
  38 <p>
  39           HarfBuzz won't help you with bidirectionality. If you want to
  40           lay out text that includes a mix of Hebrew and English, you
  41           will need to ensure that each buffer provided to HarfBuzz
  42           has all of its characters in the same order and that the
  43           directionality of the buffer is set correctly. This may mean
  44           segmenting the text before it is placed into HarfBuzz buffers. In
  45           other words, the user will hit the keys in the following
  46           sequence:
  47         </p>
  48 <pre class="programlisting">
  49           A B C [space] ג ב א [space] D E F
  50         </pre>
  51 <p>
  52           but will expect to see in the output:
  53         </p>
  54 <pre class="programlisting">
  55           ABC אבג DEF
  56         </pre>
  57 <p>
  58           This reordering is called <span class="emphasis"><em>bidi processing</em></span>
  59           ("bidi" is short for bidirectional), and there's an
  60           algorithm as an annex to the Unicode Standard which tells you how
  61           to process a string of mixed directionality.
  62           Before sending your string to HarfBuzz, you may need to apply the
  63           bidi algorithm to it. Libraries such as <a class="ulink" href="http://icu-project.org/" target="_top">ICU</a> and <a class="ulink" href="http://fribidi.org/" target="_top">fribidi</a> can do this for you.
  64         </p>
  65 </li>
  66 <li class="listitem">
  67 <p>
  68           HarfBuzz won't help you with text that contains different font
  69           properties. For instance, if you have the string "a
  70           <span class="emphasis"><em>huge</em></span> breakfast", and you expect
  71           "huge" to be italic, then you will need to send three
  72           strings to HarfBuzz: <code class="literal">a</code>, in your Roman font;
  73           <code class="literal">huge</code> using your italic font; and
  74           <code class="literal">breakfast</code> using your Roman font again.
  75         </p>
  76 <p>
  77           Similarly, if you change the font, font size, script,
  78           language, or direction within your string, then you will
  79           need to shape each run independently and output them
  80           independently. HarfBuzz expects to shape a run of characters
  81           that all share the same properties.
  82         </p>
  83 </li>
  84 <li class="listitem">
  85 <p>
  86           HarfBuzz won't help you with line breaking, hyphenation, or
  87           justification. As mentioned above, HarfBuzz lays out the string
  88           along a <span class="emphasis"><em>single line</em></span> of, notionally,
  89           infinite length. If you want to find out where the potential
  90           word, sentence and line break points are in your text, you
  91           could use the ICU library's break iterator functions.
  92         </p>
  93 <p>
  94           HarfBuzz can tell you how wide a shaped piece of text is, which is
  95           useful input to a justification algorithm, but it knows nothing
  96           about paragraphs, lines or line lengths. Nor will it adjust the
  97           space between words to fit them proportionally into a line.
  98         </p>
  99 </li>
 100 </ul></div>
 101 <p>
 102       As a layout-engine implementor, HarfBuzz will help you with the
 103       interface between your text and your font, and that's something
 104       that you'll need—what you then do with the glyphs that your font
 105       returns is up to you.
 106     </p>
 107 </div>
 108 <div class="footer">
 109 <hr>Generated by GTK-Doc V1.25</div>
 110 </body>
 111 </html>