Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / freetype / 8a2503aaefea9de37f06a172e0fcc9559b8248ab / . / docs / glyphs / glyphs-3.html
blob: ee917ca8da3aa34df68e77d7d41fff10193ab600 [file] [log] [blame]
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]1<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
2 "http://www.w3.org/TR/REC-html40/loose.dtd">
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]3<html>
4<head>
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]5 <meta http-equiv="Content-Type"
6 content="text/html; charset=iso-8859-1">
7 <meta name="Author"
8 content="David Turner">
9 <title>FreeType Glyph Conventions</title>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]10</head>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]11
12<body text="#000000"
13 bgcolor="#FFFFFF"
14 link="#0000EF"
15 vlink="#51188E"
16 alink="#FF0000">
17
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]18<h1 align=center>
19 FreeType Glyph Conventions
20</h1>
21
22<h2 align=center>
23 Version&nbsp;2.1
24</h2>
25
26<h3 align=center>
27 Copyright&nbsp;1998-2000 David Turner (<a
28 href="mailto:david@freetype.org">david@freetype.org</a>)<br>
29 Copyright&nbsp;2000 The FreeType Development Team (<a
30 href="mailto:devel@freetype.org">devel@freetype.org</a>)
31</h3>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]32
33<center>
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]34<table width="65%">
35<tr><td>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]36
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]37 <center>
38 <table width="100%"
39 border=0
40 cellpadding=5>
41 <tr bgcolor="#CCFFCC"
42 valign=center>
43 <td align=center
44 width="30%">
45 <a href="glyphs-2.html">Previous</a>
46 </td>
47 <td align=center
48 width="30%">
49 <a href="index.html">Contents</a>
50 </td>
51 <td align=center
52 width="30%">
53 <a href="glyphs-4.html">Next</a>
54 </td>
55 </tr>
56 </table>
57 </center>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]58
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]59 <p><hr></p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]60
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]61 <table width="100%">
62 <tr bgcolor="#CCCCFF"
63 valign=center><td>
64 <h2>
65 III. Glyph metrics
66 </h2>
67 </td></tr>
68 </table>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]69
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]70 <a name="section-1">
71 <h3>
72 1. Baseline, pens and layouts
73 </h3>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]74
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]75 <p>The baseline is an imaginary line that is used to "guide" glyphs when
76 rendering text. It can be horizontal (e.g. Roman, Cyrillic, Arabic,
77 etc.) or vertical (e.g. Chinese, Japanese, Korean, etc). Moreover, to
78 render text, a virtual point, located on the baseline, called the <em>pen
79 position</em> or <em>origin</em>, is used to locate glyphs.</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]80
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]81 <p>Each layout uses a different convention for glyph placement:</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]82
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]83 <ul>
84 <li>
Werner Lemberga8df54a2000-11-10 22:39:21 +0000[diff] [blame]85 <p>With horizontal layout, glyphs simply "rest" on the baseline.
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]86 Text is rendered by incrementing the pen position, either to the
87 right or to the left.</p>
88
89 <p>The distance between two successive pen positions is
90 glyph-specific and is called the <em>advance width</em>. Note that
91 its value is <em>always</em> positive, even for right-to-left
92 oriented alphabets, like Arabic. This introduces some differences
93 in the way text is rendered.</p>
94
95 <p><em>The pen position is always placed on the baseline.</em></p>
96
97 <p><center>
98 <img src="Image1.png"
99 height=179 width=458
100 alt="horizontal layout">
101 </center></p>
102 </li>
103 <li>
104 <p>With a vertical layout, glyphs are centered around the
105 baseline:</p>
106
107 <p><center>
108 <img src="Image2.png"
109 height=275 width=162
110 alt="vertical layout">
111 </center></p>
112 </li>
113 </ul>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]114
115
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]116 <a name="section-2">
117 <h3>
118 2. Typographic metrics and bounding boxes
119 </h3>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]120
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]121 <p>A various number of face metrics are defined for all glyphs in a
122 given font.</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]123
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]124 <ul>
125 <li>
126 <p><em>Ascent</em></p>
127
128 <p>The distance from the baseline to the highest/upper grid
129 coordinate used to place an outline point. It is a positive value,
130 due to the grid's orientation with the <i>Y</i>&nbsp;axis
131 upwards.</p>
132 </li>
133
134 <li>
135 <p><em>Descent</em></p>
136
137 <p>The distance from the baseline to the lowest grid coordinate used
138 to place an outline point. This is a negative value, due to the
139 grid's orientation.</p>
140 </li>
141
142 <li>
143 <p><em>Linegap</em></p>
144
145 <p>The distance that must be placed between two lines of text. The
146 baseline-to-baseline distance should be computed as:
147
148 <center><p>
149 <tt>ascent - descent + linegap</tt>
150 </p></center>
151
152 <p>if you use the typographic values.</p>
153 </li>
154 </ul>
155
156 <p>Other, simpler metrics are:</p>
157
158 <ul>
159 <li>
160 <p><em>The glyph's bounding box</em>, also called <em>bbox</em></p>
161
162 <p>This is an imaginary box that encloses all glyphs from the font,
163 usually as tightly as possible. It is represented by four fields,
164 namely <tt>xMin</tt>, <tt>yMin</tt>, <tt>xMax</tt>, and
165 <tt>yMax</tt>, that can be computed for any outline. Their values
166 can be in font units (if measured in the original outline) or in
167 fractional/integer pixel units (when measured on scaled
168 outlines).</p>
169
170 <p>Note that if it wasn't for grid-fitting, you wouldn't need to
171 know a box's complete values, but only its dimensions to know how
172 big is a glyph outline/bitmap. However, correct rendering of hinted
173 glyphs needs the preservation of important grid alignment on each
174 glyph translation/placement on the baseline.</p>
175 </li>
176
177 <li>
178 <p><em>Internal leading</em></p>
179
180 <p>This concept comes directly from the world of traditional
181 typography. It represents the amount of space within the
182 <em>leading</em> which is reserved for glyph features that lay
183 outside of the EM square (like accentuation). It usually can be
184 computed as:</p>
185
186 <center><p>
187 <tt>internal leading = ascent - descent - EM_size</tt>
188 </p></center>
189 </li>
190
191 <li>
192 <p><em>External leading</em></p>
193
194 <p>This is another name for the line gap.</p>
195 </li>
196 </ul>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]197
198
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]199 <a name="section-3">
200 <h3>
201 3. Bearings and Advances
202 </h3>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]203
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]204 Each glyph has also distances called <em>bearings</em> and
205 <em>advances</em>. Their definition is constant, but their values
206 depend on the layout, as the same glyph can be used to render text
207 either horizontally or vertically:
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]208
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]209 <ul>
210 <li>
211 <p><em>Left side bearing</em> or <em>bearingX</em></p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]212
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]213 <p>The horizontal distance from the current pen position to the
214 glyph's left bbox edge. It is positive for horizontal layouts, and
215 in most cases negative for vertical one.</p>
216 </li>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]217
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]218 <li>
219 <p><em>Top side bearing</em> or <em>bearingY</em></p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]220
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]221 <p>The vertical distance from the baseline to the top of the glyph's
222 bbox. It is usually positive for horizontal layouts, and negative
223 for vertical ones</p>
224 </li>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]225
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]226 <li>
227 <p><em>Advance width</em> or <em>advanceX</em></p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]228
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]229 <p>The horizontal distance the pen position must be incremented (for
230 left-to-right writing) or decremented (for right-to-left writing) by
231 after each glyph is rendered when processing text. It is always
232 positive for horizontal layouts, and null for vertical ones.</p>
233 </li>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]234
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]235 <li>
236 <p><em>Advance height</em> <em>advanceY</em></p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]237
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]238 <p>The vertical distance the pen position must be decremented by
239 after each glyph is rendered. It is always null for horizontal
240 layouts, and positive for vertical layouts.</p>
241 </li>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]242
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]243 <li>
244 <p><em>Glyph width</em></p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]245
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]246 <p>The glyph's horizontal extent. For unscaled font coordinates, it
247 is <tt>bbox.xMax-bbox.xMin</tt>. For scaled glyphs, its computation
248 requests specific care, described in the grid-fitting chapter
249 below.</p>
250 </li>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]251
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]252 <li>
253 <p><em>Glyph height</em>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]254
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]255 <p>The glyph's vertical extent. For unscaled font coordinates, it is
256 <tt>bbox.yMax-bbox.yMin</tt>. For scaled glyphs, its computation
257 requests specific care, described in the grid-fitting chapter
258 below.</p>
259 </li>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]260
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]261 <li>
262 <p><em>Right side bearing</em></p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]263
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]264 <p>Only used for horizontal layouts to describe the distance from
265 the bbox's right edge to the advance width. It is in most cases a
266 non-negative number:</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]267
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]268 <p><center>
269 <tt>advance_width - left_side_bearing - (xMax-xMin)</tt>
270 </center></p>
271 </li>
272 </ul>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]273
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]274 <p>Here is a picture giving all the details for horizontal metrics:
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]275
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]276 <center><p>
277 <img src="Image3.png"
278 height=253 width=388
279 alt="horizontal glyph metrics">
280 </p></center>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]281
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]282 <p>And here is another one for the vertical metrics:</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]283
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]284 <center><p>
285 <img src="Image4.png"
286 height=278 width=294
287 alt="vertical glyph metrics">
288 </p></center>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]289
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]290
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]291 <a name="section-4">
292 <h3>
293 4. The effects of grid-fitting
294 </h3>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]295
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]296 <p>Because hinting aligns the glyph's control points to the pixel grid,
297 this process slightly modifies the dimensions of character images in
298 ways that differ from simple scaling.</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]299
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]300 <p>For example, the image of the lowercase "m" letter sometimes fits a
301 square in the master grid. However, to make it readable at small pixel
302 sizes, hinting tends to enlarge its scaled outline in order to keep its
303 three legs distinctly visible, resulting in a larger character
304 bitmap.</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]305
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]306 <p>The glyph metrics are also influenced by the grid-fitting process:
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]307
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]308 <ul>
309 <li>
310 The image's width and height are altered. Even if this is only by
311 one pixel, it can make a big difference at small pixel sizes.
312 </li>
313 <li>
314 The image's bounding box is modified, thus modifying the bearings.
315 </li>
316 <li>
317 The advances must be updated. For example, the advance width must
318 be incremented if the hinted bitmap is larger than the scaled one,
319 to reflect the augmented glyph width.
320 </li>
321 </ul>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]322
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]323 <p>This has some implications:</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]324
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]325 <ul>
326 <li>
327 Because of hinting, simply scaling the font ascent or descent might
328 not give correct results. A possible solution is to keepthe ceiling
329 of the scaled ascent, and floor of the scaled descent.
330 </li>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]331
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]332 <li>
333 There is no easy way to get the hinted glyph and advance widths of a
334 range of glyphs, as hinting works differently on each outline. The
335 only solution is to hint each glyph separately and record the
336 returned values. Some formats, like TrueType, even include a table
337 of pre-computed values for a small set of common character pixel
338 sizes.
339 </li>
340 <li>
341 Hinting depends on the final character width and height in pixels,
342 which means that it is highly resolution-dependent. This property
343 makes correct WYSIWYG layouts difficult to implement.
344 </li>
345 </ul>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]346
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]347
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]348 <em>
349 <p>Performing 2D transformations on glyph outlines is very easy with
350 FreeType. However, when using translation on a hinted outlines, one
351 should aways take care of <b>exclusively using integer pixel
352 distances</b> (which means that the parameters to the
353 <tt>FT_Translate_Outline()</tt> API should all be multiples
354 of&nbsp;64, as the point coordinates are in 26.6&nbsp;fixed float
355 format).</p>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]356
Werner Lembergfed760b2000-11-09 16:23:23 +0000[diff] [blame]357 <p>Otherwise, the translation will simply <em>ruin the hinter's
358 work</em>, resulting in a very low quality bitmaps!</p>
359 </em>
360
361
362 <a name="section-5">
363 <h3>
364 5. Text widths and bounding box
365 </h3>
366
367 <p>As seen before, the "origin" of a given glyph corresponds to the
368 position of the pen on the baseline. It is not necessarily located on
369 one of the glyph's bounding box corners, unlike many typical bitmapped
370 font formats. In some cases, the origin can be out of the bounding box,
371 in others, it can be within it, depending on the shape of the given
372 glyph.</p>
373
374 <p>Likewise, the glyph's "advance width" is the increment to apply to
375 the pen position during layout, and is not related to the glyph's
376 "width", which really is the glyph's bounding width.
377
378 <p>The same conventions apply to strings of text. This means that:
379
380 <ul>
381 <li>
382 The bounding box of a given string of text doesn't necessarily
383 contain the text cursor, nor is the latter located on one of its
384 corners.
385 </li>
386
387 <li>
388 The string's advance width isn't related to its bounding box
389 dimensions. Especially if it contains beginning and terminal spaces
390 or tabs.
391 </li>
392 <li>
393 Finally, additional processing like kerning creates strings of text
394 whose dimensions are not directly related to the simple
395 juxtaposition of individual glyph metrics. For example, the advance
396 width of "VA" isn't the sum of the advances of "V" and "A" taken
397 separately.
398 </li>
399 </ul>
400
401 <p><hr></p>
402
403 <center>
404 <table width="100%"
405 border=0
406 cellpadding=5>
407 <tr bgcolor="#CCFFCC"
408 valign=center>
409 <td align=center
410 width="30%">
411 <a href="glyphs-2.html">Previous</a>
412 </td>
413 <td align=center
414 width="30%">
415 <a href="index.html">Contents</a>
416 </td>
417 <td align=center
418 width="30%">
419 <a href="glyphs-4.html">Next</a>
420 </td>
421 </tr>
422 </table>
423 </center>
424
425</td></tr>
426</table>
427</center>
David Turner35746432000-11-09 00:01:38 +0000[diff] [blame]428
429</body>
430</html>