<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=utf-8">
<meta http-equiv="Content-Style-Type"
content="text/css">
<meta http-equiv="Content-Script-Type"
content="text/javascript">
<meta name="description"
content="FreeType Documentation">
<meta name="Author"
content="David Turner">
<link rel="icon"
href="../image/favicon_-90.ico">
<link rel="shortcut icon"
href="../image/favicon_-90.ico">
<link rel="stylesheet"
type="text/css"
href="../css/freetype2_-90.css">
<script type="text/javascript"
src="../../../js/jquery-1.11.0.min.js">
</script>
<script type="text/javascript"
src="../../../js/jquery.ba-resize.min.js">
</script>
<script type="text/javascript"
src="../../../js/freetype2.js">
</script>
<title>FreeType Glyph Conventions / V</title>
</head>
<body>
<div id="top"
class="bar">
<h1><a href="http://freetype.org/index.html">FreeType</a> Glyph
Conventions / V</h1>
</div>
<div id="wrapper">
<div class="colmask leftmenu">
<div class="colright">
<div class="col1wrap">
<div class="col1">
<!-- ************************************************** -->
<div id="text-processing">
<h2>V. Text Processing</h2>
<p>This section demonstrate algorithms which use the
concepts previously defined to render text, whatever
layout you use. It assumes <em>simple</em> text handling
suitable for scripts like Latin or Cyrillic, using a
one-to-one relationship between input character codes and
output glyphs indices. Scripts like Arabic or Khmer,
which need a ‘shaping engine’ to do the
character code to glyph index conversion, are beyond the
scope (and should be done by proper layout engines
like <a href="http://www.pango.org/">Pango</a>
anyway).</p>
<h3 id="section-1">1. Writing simple text strings</h3>
<p>In this first example, we will generate a simple string
of text in the Latin script, i.e., with a horizontal
left-to-right layout. Using exclusively pixel metrics,
the process looks like:
<ol class="algorithm">
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Translate the glyph so that its ‘origin’
matches the pen position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Increment the pen position by the glyph's advance
width (in pixels).
</li>
<li>
Start over at step 3 for each of the remaining
glyphs.
</li>
<li>
When all glyphs are done, set the text cursor to the
new pen position.
</li>
</ol>
<p>Note that kerning isn't part of this algorithm.</p>
<h3 id="section-2">2. Subpixel positioning</h3>
<p>This algorithm can be used for hinting modes that don't
apply horizontal hinting. It essentially provides WYSIWYG
text layout. Text rendering is very similar to the
algorithm described in subsection 1, with the
following few differences:</p>
<ul>
<li>
<p>The pen position is expressed in fractional
pixels.</p>
</li>
<li>
<p>The hinted outline must be shifted horizontally to
the proper sub-pixel position.</p>
</li>
<li>
<p>The advance width is expressed in fractional pixels,
and isn't necessarily an integer.</p>
</li>
</ul>
<p>Here an improved version of the algorithm:</p>
<ol class="algorithm">
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position. This can be a
non-integer point.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Translate the glyph by ‘pen_pos -
floor(pen_pos)’.
</li>
<li>
Render the glyph to the target device at
‘floor(pen_pos)’.
</li>
<li>
Increment the pen position by the glyph's advance width
in fractional pixels.
</li>
<li>
Start over at step 3 for each of the remaining
glyphs.
</li>
<li>
When all glyphs are done, set the text cursor to the new
pen position.
</li>
</ol>
<h3 id="section-3">3. Simple kerning</h3>
<p>Adding kerning to the basic text rendering algorithm is
easy: When a kerning pair is found, simply add the scaled
kerning distance to the pen position before step 4.
Of course, the distance should be rounded in the case of
algorithm 1, though it doesn't need to for
algorithm 2. This gives us:</p>
<p>Algorithm 1 with kerning:</p>
<ol class="algorithm">
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Add the rounded scaled kerning distance, if any, to the
pen position.
</li>
<li>
Translate the glyph so that its ‘origin’
matches the pen position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Increment the pen position by the glyph's advance width
in pixels.
</li>
<li>
Start over at step 3 for each of the remaining
glyphs.
</li>
</ol>
<p>Algorithm 2 with kerning:</p>
<ol class="algorithm">
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Add the scaled unrounded kerning distance, if any, to
the pen position.
</li>
<li>
Translate the glyph by ‘pen_pos -
int(pen_pos)’.
</li>
<li>
Render the glyph to the target device at
‘int(pen_pos)’.
</li>
<li>
Increment the pen position by the glyph's advance width
in fractional pixels.
</li>
<li>
Start over at step 3 for each of the remaining
glyphs.
</li>
</ol>
<h3 id="section-4">4. Right-to-left layout</h3>
<p>The process of laying out right-to-left scripts like
(modern) Hebrew text is very similar. The only difference
is that the pen position must be decremented before the
glyph rendering (remember: the advance width is always
positive, even for Hebrew glyphs).</p>
<p>Right-to-left algorithm 1:</p>
<ol class="algorithm">
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Decrement the pen position by the glyph's advance
width in pixels.
</li>
<li>
Translate the glyph so that its ‘origin’
matches the pen position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Start over at step 3 for each of the remaining
glyphs.
</li>
</ol>
<p>The changes to algorithm 2, as well as the inclusion
of kerning are left as an exercise to the reader.</p>
<h3 id="section-5">5. Vertical layouts</h3>
<p>Laying out vertical text uses exactly the same processes,
with the following significant differences:</p>
<ul>
<li>
<p>The baseline is vertical, and the vertical metrics
must be used instead of the horizontal one.</p>
</li>
<li>
<p>The left bearing is usually negative, but this
doesn't change the fact that the glyph origin must be
located on the baseline.</p>
</li>
<li>
<p>The advance height is always positive, so the pen
position must be decremented if one wants to write top
to bottom (assuming the <i>Y</i> axis is oriented
upwards).</p>
</li>
</ul>
<p>Here the algorithm:</p>
<ol class="algorithm">
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Translate the glyph so that its ‘origin’
matches the pen position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Decrement the vertical pen position by the glyph's
advance height in pixels.
</li>
<li>
Start over at step 3 for each of the remaining
glyphs.
</li>
<li>
When all glyphs are done, set the text cursor to the new
pen position.
</li>
</ol>
</div>
<!-- ************************************************** -->
<div class="updated">
<p>Last update: 13-Feb-2018</p>
</div>
</div>
</div>
<!-- ************************************************** -->
<div class="col2">
</div>
</div>
</div>
<!-- ************************************************** -->
<div id="TOC">
<ul>
<li class="funding">
<form action="https://www.paypal.com/cgi-bin/webscr"
method="post"
target="_top">
<input type="hidden"
name="cmd"
value="_s-xclick">
<input type="hidden"
name="hosted_button_id"
value="SK827YKEALMT4">
<input type="image"
src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif"
name="submit"
alt="PayPal - The safer, easier way to pay online!">
<img alt=""
border="0"
src="https://www.paypalobjects.com/de_DE/i/scr/pixel.gif"
width="1"
height="1">
</form>
</li>
<li class="primary">
<a href="http://freetype.org/index.html">Home</a>
</li>
<li class="primary">
<a href="http://freetype.org/index.html#news">News</a>
</li>
<li class="primary">
<a href="../index.html">Overview</a>
</li>
<li class="primary">
<a href="../documentation.html">Documentation</a>
</li>
<li class="primary">
<a href="http://freetype.org/developer.html">Development</a>
</li>
<li class="primary">
<a href="http://freetype.org/contact.html"
class="emphasis">Contact</a>
</li>
<li>
<!-- separate primary from secondary entries -->
</li>
<li class="secondary">
<a href="index.html">FreeType Glyph Conventions</a>
</li>
<li class="tertiary">
<a href="glyphs-1.html">Basic Typographic Concepts</a>
</li>
<li class="tertiary">
<a href="glyphs-2.html">Glyph Outlines</a>
</li>
<li class="tertiary">
<a href="glyphs-3.html">Glyph Metrics</a>
</li>
<li class="tertiary">
<a href="glyphs-4.html">Kerning</a>
</li>
<li class="tertiary">
<a href="glyphs-5.html" class="current">Text Processing</a>
</li>
<li class="tertiary">
<a href="glyphs-6.html">FreeType Outlines</a>
</li>
<li class="tertiary">
<a href="glyphs-7.html">FreeType Bitmaps</a>
</li>
</ul>
</div>
</div> <!-- id="wrapper" -->
<div id="TOC-bottom">
</div>
</body>
</html>