docs/html/hello-harfbuzz.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>Hello, Harfbuzz: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="pt01.html" title="Part I. User's manual">
   9 <link rel="prev" href="building.html" title="Building">
  10 <link rel="next" href="buffers-language-script-and-direction.html" title="Buffers, language, script and direction">
  11 <meta name="generator" content="GTK-Doc V1.25.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="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="building.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="buffers-language-script-and-direction.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="chapter">
  23 <div class="titlepage"><div><div><h2 class="title">
  24 <a name="hello-harfbuzz"></a>Hello, Harfbuzz</h2></div></div></div>
  25 <div class="toc"><dl class="toc"><dt><span class="section"><a href="hello-harfbuzz.html#what-harfbuzz-doesnt-do">What Harfbuzz doesn't do</a></span></dt></dl></div>
  26 <p>
  27     Here's the simplest Harfbuzz that can possibly work. We will improve
  28     it later.
  29   </p>
  30 <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
  31         Create a buffer and put your text in it.
  32       </p></li></ol></div>
  33 <pre class="programlisting">
  34   #include &lt;hb.h&gt;
  35   hb_buffer_t *buf;
  36   buf = hb_buffer_create();
  37   hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text));
  38 </pre>
  39 <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="2"><p>
  40         Guess the script, language and direction of the buffer.
  41       </p></li></ol></div>
  42 <pre class="programlisting">
  43   hb_buffer_guess_segment_properties(buf);
  44 </pre>
  45 <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="3"><p>
  46         Create a face and a font, using FreeType for now.
  47       </p></li></ol></div>
  48 <pre class="programlisting">
  49   #include &lt;hb-ft.h&gt;
  50   FT_New_Face(ft_library, font_path, index, &amp;face)
  51   hb_font_t *font = hb_ft_font_create(face);
  52 </pre>
  53 <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="4"><p>
  54         Shape!
  55       </p></li></ol></div>
  56 <pre class="programlisting">
  57   hb_shape(font, buf, NULL, 0);
  58 </pre>
  59 <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="5"><p>
  60         Get the glyph and position information.
  61       </p></li></ol></div>
  62 <pre class="programlisting">
  63   hb_glyph_info_t *glyph_info    = hb_buffer_get_glyph_infos(buf, &amp;glyph_count);
  64   hb_glyph_position_t *glyph_pos = hb_buffer_get_glyph_positions(buf, &amp;glyph_count);
  65 </pre>
  66 <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="6"><p>
  67         Iterate over each glyph.
  68       </p></li></ol></div>
  69 <pre class="programlisting">
  70   for (i = 0; i &lt; glyph_count; ++i) {
  71     glyphid = glyph_info[i].codepoint;
  72     x_offset = glyph_pos[i].x_offset / 64.0;
  73     y_offset = glyph_pos[i].y_offset / 64.0;
  74     x_advance = glyph_pos[i].x_advance / 64.0;
  75     y_advance = glyph_pos[i].y_advance / 64.0;
  76     draw_glyph(glyphid, cursor_x + x_offset, cursor_y + y_offset);
  77     cursor_x += x_advance;
  78     cursor_y += y_advance;
  79   }
  80 </pre>
  81 <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="7"><p>
  82         Tidy up.
  83       </p></li></ol></div>
  84 <pre class="programlisting">
  85   hb_buffer_destroy(buf);
  86   hb_font_destroy(hb_ft_font);
  87 </pre>
  88 <div class="section">
  89 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  90 <a name="what-harfbuzz-doesnt-do"></a>What Harfbuzz doesn't do</h2></div></div></div>
  91 <p>
  92       The code above will take a UTF8 string, shape it, and give you the
  93       information required to lay it out correctly on a single
  94       horizontal (or vertical) line using the font provided. That is the
  95       extent of Harfbuzz's responsibility.
  96     </p>
  97 <p>
  98       If you are implementing a text layout engine you may have other
  99       responsibilities, that Harfbuzz will not help you with:
 100     </p>
 101 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 102 <li class="listitem">
 103 <p>
 104           Harfbuzz won't help you with bidirectionality. If you want to
 105           lay out text with mixed Hebrew and English, you will need to
 106           ensure that the buffer provided to Harfbuzz has those
 107           characters in the correct layout order. This will be different
 108           from the logical order in which the Unicode text is stored. In
 109           other words, the user will hit the keys in the following
 110           sequence:
 111         </p>
 112 <pre class="programlisting">
 113 A B C [space] ג ב א [space] D E F
 114         </pre>
 115 <p>
 116           but will expect to see in the output:
 117         </p>
 118 <pre class="programlisting">
 119 ABC אבג DEF
 120         </pre>
 121 <p>
 122           This reordering is called <span class="emphasis"><em>bidi processing</em></span>
 123           ("bidi" is short for bidirectional), and there's an
 124           algorithm as an annex to the Unicode Standard which tells you how
 125           to reorder a string from logical order into presentation order.
 126           Before sending your string to Harfbuzz, you may need to apply the
 127           bidi algorithm to it. Libraries such as ICU and fribidi can do
 128           this for you.
 129         </p>
 130 </li>
 131 <li class="listitem"><p>
 132           Harfbuzz won't help you with text that contains different font
 133           properties. For instance, if you have the string "a
 134           <span class="emphasis"><em>huge</em></span> breakfast", and you expect
 135           "huge" to be italic, you will need to send three
 136           strings to Harfbuzz: <code class="literal">a</code>, in your Roman font;
 137           <code class="literal">huge</code> using your italic font; and
 138           <code class="literal">breakfast</code> using your Roman font again.
 139           Similarly if you change font, font size, script, language or
 140           direction within your string, you will need to shape each run
 141           independently and then output them independently. Harfbuzz
 142           expects to shape a run of characters sharing the same
 143           properties.
 144         </p></li>
 145 <li class="listitem">
 146 <p>
 147           Harfbuzz won't help you with line breaking, hyphenation or
 148           justification. As mentioned above, it lays out the string
 149           along a <span class="emphasis"><em>single line</em></span> of, notionally,
 150           infinite length. If you want to find out where the potential
 151           word, sentence and line break points are in your text, you
 152           could use the ICU library's break iterator functions.
 153         </p>
 154 <p>
 155           Harfbuzz can tell you how wide a shaped piece of text is, which is
 156           useful input to a justification algorithm, but it knows nothing
 157           about paragraphs, lines or line lengths. Nor will it adjust the
 158           space between words to fit them proportionally into a line. If you
 159           want to layout text in paragraphs, you will probably want to send
 160           each word of your text to Harfbuzz to determine its shaped width
 161           after glyph substitutions, then work out how many words will fit
 162           on a line, and then finally output each word of the line separated
 163           by a space of the correct size to fully justify the paragraph.
 164         </p>
 165 </li>
 166 </ul></div>
 167 <p>
 168       As a layout engine implementor, Harfbuzz will help you with the
 169       interface between your text and your font, and that's something
 170       that you'll need - what you then do with the glyphs that your font
 171       returns is up to you. The example we saw above enough to get us
 172       started using Harfbuzz. Now we are going to use the remainder of
 173       Harfbuzz's API to refine that example and improve our text shaping
 174       capabilities.
 175     </p>
 176 </div>
 177 </div>
 178 <div class="footer">
 179 <hr>Generated by GTK-Doc V1.25.1</div>
 180 </body>
 181 </html>