diff options
Diffstat (limited to 'docs/html/hello-harfbuzz.html')
-rw-r--r-- | docs/html/hello-harfbuzz.html | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/docs/html/hello-harfbuzz.html b/docs/html/hello-harfbuzz.html new file mode 100644 index 0000000..c665efc --- /dev/null +++ b/docs/html/hello-harfbuzz.html @@ -0,0 +1,181 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>Hello, Harfbuzz: HarfBuzz Manual</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="HarfBuzz Manual"> +<link rel="up" href="pt01.html" title="Part I. User's manual"> +<link rel="prev" href="building.html" title="Building"> +<link rel="next" href="buffers-language-script-and-direction.html" title="Buffers, language, script and direction"> +<meta name="generator" content="GTK-Doc V1.24.1 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="building.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<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> +</tr></table> +<div class="chapter"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="hello-harfbuzz"></a>Hello, Harfbuzz</h2></div></div></div> +<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> +<p> + Here's the simplest Harfbuzz that can possibly work. We will improve + it later. + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + Create a buffer and put your text in it. + </p></li></ol></div> +<pre class="programlisting"> + #include <hb.h> + hb_buffer_t *buf; + buf = hb_buffer_create(); + hb_buffer_add_utf8(buf, text, strlen(text), 0, strlen(text)); +</pre> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="2"><p> + Guess the script, language and direction of the buffer. + </p></li></ol></div> +<pre class="programlisting"> + hb_buffer_guess_segment_properties(buf); +</pre> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="3"><p> + Create a face and a font, using FreeType for now. + </p></li></ol></div> +<pre class="programlisting"> + #include <hb-ft.h> + FT_New_Face(ft_library, font_path, index, &face) + hb_font_t *font = hb_ft_font_create(face); +</pre> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="4"><p> + Shape! + </p></li></ol></div> +<pre class="programlisting"> + hb_shape(font, buf, NULL, 0); +</pre> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="5"><p> + Get the glyph and position information. + </p></li></ol></div> +<pre class="programlisting"> + hb_glyph_info_t *glyph_info = hb_buffer_get_glyph_infos(buf, &glyph_count); + hb_glyph_position_t *glyph_pos = hb_buffer_get_glyph_positions(buf, &glyph_count); +</pre> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="6"><p> + Iterate over each glyph. + </p></li></ol></div> +<pre class="programlisting"> + for (i = 0; i < glyph_count; ++i) { + glyphid = glyph_info[i].codepoint; + x_offset = glyph_pos[i].x_offset / 64.0; + y_offset = glyph_pos[i].y_offset / 64.0; + x_advance = glyph_pos[i].x_advance / 64.0; + y_advance = glyph_pos[i].y_advance / 64.0; + draw_glyph(glyphid, cursor_x + x_offset, cursor_y + y_offset); + cursor_x += x_advance; + cursor_y += y_advance; + } +</pre> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem" value="7"><p> + Tidy up. + </p></li></ol></div> +<pre class="programlisting"> + hb_buffer_destroy(buf); + hb_font_destroy(hb_ft_font); +</pre> +<div class="section"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="what-harfbuzz-doesnt-do"></a>What Harfbuzz doesn't do</h2></div></div></div> +<p> + The code above will take a UTF8 string, shape it, and give you the + information required to lay it out correctly on a single + horizontal (or vertical) line using the font provided. That is the + extent of Harfbuzz's responsibility. + </p> +<p> + If you are implementing a text layout engine you may have other + responsibilities, that Harfbuzz will not help you with: + </p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> +<li class="listitem"> +<p> + Harfbuzz won't help you with bidirectionality. If you want to + lay out text with mixed Hebrew and English, you will need to + ensure that the buffer provided to Harfbuzz has those + characters in the correct layout order. This will be different + from the logical order in which the Unicode text is stored. In + other words, the user will hit the keys in the following + sequence: + </p> +<pre class="programlisting"> +A B C [space] ג ב א [space] D E F + </pre> +<p> + but will expect to see in the output: + </p> +<pre class="programlisting"> +ABC אבג DEF + </pre> +<p> + This reordering is called <span class="emphasis"><em>bidi processing</em></span> + ("bidi" is short for bidirectional), and there's an + algorithm as an annex to the Unicode Standard which tells you how + to reorder a string from logical order into presentation order. + Before sending your string to Harfbuzz, you may need to apply the + bidi algorithm to it. Libraries such as ICU and fribidi can do + this for you. + </p> +</li> +<li class="listitem"><p> + Harfbuzz won't help you with text that contains different font + properties. For instance, if you have the string "a + <span class="emphasis"><em>huge</em></span> breakfast", and you expect + "huge" to be italic, you will need to send three + strings to Harfbuzz: <code class="literal">a</code>, in your Roman font; + <code class="literal">huge</code> using your italic font; and + <code class="literal">breakfast</code> using your Roman font again. + Similarly if you change font, font size, script, language or + direction within your string, you will need to shape each run + independently and then output them independently. Harfbuzz + expects to shape a run of characters sharing the same + properties. + </p></li> +<li class="listitem"> +<p> + Harfbuzz won't help you with line breaking, hyphenation or + justification. As mentioned above, it lays out the string + along a <span class="emphasis"><em>single line</em></span> of, notionally, + infinite length. If you want to find out where the potential + word, sentence and line break points are in your text, you + could use the ICU library's break iterator functions. + </p> +<p> + Harfbuzz can tell you how wide a shaped piece of text is, which is + useful input to a justification algorithm, but it knows nothing + about paragraphs, lines or line lengths. Nor will it adjust the + space between words to fit them proportionally into a line. If you + want to layout text in paragraphs, you will probably want to send + each word of your text to Harfbuzz to determine its shaped width + after glyph substitutions, then work out how many words will fit + on a line, and then finally output each word of the line separated + by a space of the correct size to fully justify the paragraph. + </p> +</li> +</ul></div> +<p> + As a layout engine implementor, Harfbuzz will help you with the + interface between your text and your font, and that's something + that you'll need - what you then do with the glyphs that your font + returns is up to you. The example we saw above enough to get us + started using Harfbuzz. Now we are going to use the remainder of + Harfbuzz's API to refine that example and improve our text shaping + capabilities. + </p> +</div> +</div> +<div class="footer"> +<hr>Generated by GTK-Doc V1.24.1</div> +</body> +</html>
\ No newline at end of file |