<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Setting buffer properties: HarfBuzz Manual</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="HarfBuzz Manual">
<link rel="up" href="buffers-language-script-and-direction.html" title="Buffers, language, script and direction">
<link rel="prev" href="adding-text-to-the-buffer.html" title="Adding text to the buffer">
-<link rel="next" href="what-about-the-other-scripts.html" title="What about the other scripts?">
-<meta name="generator" content="GTK-Doc V1.24.1 (XML mode)">
+<link rel="next" href="customizing-unicode-functions.html" title="Customizing Unicode functions">
+<meta name="generator" content="GTK-Doc V1.32.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<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="buffers-language-script-and-direction.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="adding-text-to-the-buffer.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
-<td><a accesskey="n" href="
what-about-the-other-scripts.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
+<td><a accesskey="n" href="
customizing-unicode-functions.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="setting-buffer-properties"></a>Setting buffer properties</h2></div></div></div>
<p>
+ Buffers containing input characters still need several
+ properties set before HarfBuzz can shape their text correctly.
+ </p>
+<p>
+ Initially, all buffers are set to the
+ <code class="literal">HB_BUFFER_CONTENT_TYPE_INVALID</code> content
+ type. After adding text, the buffer should be set to
+ <code class="literal">HB_BUFFER_CONTENT_TYPE_UNICODE</code> instead, which
+ indicates that it contains un-shaped input
+ characters. After shaping, the buffer will have the
+ <code class="literal">HB_BUFFER_CONTENT_TYPE_GLYPHS</code> content type.
+ </p>
+<p>
+ <code class="function">hb_buffer_add_utf8()</code> and the
+ other UTF functions set the content type of their buffer
+ automatically. But if you are reusing a buffer you may want to
+ check its state with
+ <code class="function">hb_buffer_get_content_type(buffer)</code>. If
+ necessary you can set the content type with
+ </p>
+<pre class="programlisting">
+ hb_buffer_set_content_type(buf, HB_BUFFER_CONTENT_TYPE_UNICODE);
+ </pre>
+<p>
+ to prepare for shaping.
+ </p>
+<p>
+ Buffers also need to carry information about the script,
+ language, and text direction of their contents. You can set
+ these properties individually:
+ </p>
+<pre class="programlisting">
+ hb_buffer_set_direction(buf, HB_DIRECTION_LTR);
+ hb_buffer_set_script(buf, HB_SCRIPT_LATIN);
+ hb_buffer_set_language(buf, hb_language_from_string("en", -1));
+ </pre>
+<p>
+ However, since these properties are often repeated for
+ multiple text runs, you can also save them in a
+ <code class="literal">hb_segment_properties_t</code> for reuse:
+ </p>
+<pre class="programlisting">
+ hb_segment_properties_t *savedprops;
+ hb_buffer_get_segment_properties (buf, savedprops);
+ ...
+ hb_buffer_set_segment_properties (buf2, savedprops);
+ </pre>
+<p>
+ HarfBuzz also provides getter functions to retrieve a buffer's
+ direction, script, and language properties individually.
+ </p>
+<p>
+ HarfBuzz recognizes four text directions in
+ <span class="type">hb_direction_t</span>: left-to-right
+ (<code class="literal">HB_DIRECTION_LTR</code>), right-to-left (<code class="literal">HB_DIRECTION_RTL</code>),
+ top-to-bottom (<code class="literal">HB_DIRECTION_TTB</code>), and
+ bottom-to-top (<code class="literal">HB_DIRECTION_BTT</code>). For the
+ script property, HarfBuzz uses identifiers based on the
+ <a class="ulink" href="https://unicode.org/iso15924/" target="_top">ISO 15924
+ standard</a>. For languages, HarfBuzz uses tags based on the
+ <a class="ulink" href="https://tools.ietf.org/html/bcp47" target="_top">IETF BCP 47</a> standard.
+ </p>
+<p>
+ Helper functions are provided to convert character strings into
+ the necessary script and language tag types.
+ </p>
+<p>
+ Two additional buffer properties to be aware of are the
+ "invisible glyph" and the replacement code point. The
+ replacement code point is inserted into buffer output in place of
+ any invalid code points encountered in the input. By default, it
+ is the Unicode <code class="literal">REPLACEMENT CHARACTER</code> code
+ point, <code class="literal">U+FFFD</code> "�". You can change this with
+ </p>
+<pre class="programlisting">
+ hb_buffer_set_replacement_codepoint(buf, replacement);
+ </pre>
+<p>
+ passing in the replacement Unicode code point as the
+ <em class="parameter"><code>replacement</code></em> parameter.
+ </p>
+<p>
+ The invisible glyph is used to replace all output glyphs that
+ are invisible. By default, the standard space character
+ <code class="literal">U+0020</code> is used; you can replace this (for
+ example, when using a font that provides script-specific
+ spaces) with
+ </p>
+<pre class="programlisting">
+ hb_buffer_set_invisible_glyph(buf, replacement_glyph);
+ </pre>
+<p>
+ Do note that in the <em class="parameter"><code>replacement_glyph</code></em>
+ parameter, you must provide the glyph ID of the replacement you
+ wish to use, not the Unicode code point.
+ </p>
+<p>
+ HarfBuzz supports a few additional flags you might want to set
+ on your buffer under certain circumstances. The
+ <code class="literal">HB_BUFFER_FLAG_BOT</code> and
+ <code class="literal">HB_BUFFER_FLAG_EOT</code> flags tell HarfBuzz
+ that the buffer represents the beginning or end (respectively)
+ of a text element (such as a paragraph or other block). Knowing
+ this allows HarfBuzz to apply certain contextual font features
+ when shaping, such as initial or final variants in connected
+ scripts.
+ </p>
+<p>
+ <code class="literal">HB_BUFFER_FLAG_PRESERVE_DEFAULT_IGNORABLES</code>
+ tells HarfBuzz not to hide glyphs with the
+ <code class="literal">Default_Ignorable</code> property in Unicode. This
+ property designates control characters and other non-printing
+ code points, such as joiners and variation selectors. Normally
+ HarfBuzz replaces them in the output buffer with zero-width
+ space glyphs (using the "invisible glyph" property discussed
+ above); setting this flag causes them to be printed, which can
+ be helpful for troubleshooting.
+ </p>
+<p>
+ Conversely, setting the
+ <code class="literal">HB_BUFFER_FLAG_REMOVE_DEFAULT_IGNORABLES</code> flag
+ tells HarfBuzz to remove <code class="literal">Default_Ignorable</code>
+ glyphs from the output buffer entirely. Finally, setting the
+ <code class="literal">HB_BUFFER_FLAG_DO_NOT_INSERT_DOTTED_CIRCLE</code>
+ flag tells HarfBuzz not to insert the dotted-circle glyph
+ (<code class="literal">U+25CC</code>, "◌"), which is normally
+ inserted into buffer output when broken character sequences are
+ encountered (such as combining marks that are not attached to a
+ base character).
</p>
</div>
<div class="footer">
-<hr>Generated by GTK-Doc V1.24.1</div>
+<hr>Generated by GTK-Doc V1.32.1</div>
</body>
</html>
\ No newline at end of file
projects / platform / upstream / harfbuzz.git / blobdiff