Debian Codegraph @

ft2docs/docs/glyphs/glyphs-6.html

raw ◀ ▶
1 Debian patch touch this file
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
3
4 <html lang="en">
5
6 <head>
7 <meta http-equiv="Content-Type"
8 content="text/html; charset=utf-8">
9 <meta http-equiv="Content-Style-Type"
10 content="text/css">
11 <meta http-equiv="Content-Script-Type"
12 content="text/javascript">
13 <meta name="description"
14 content="FreeType Glyph Conventions - FreeType Outlines">
15 <meta name="Author"
16 content="David Turner">
17
18 <link rel="icon"
19 href="../image/favicon_-90.ico">
20 <link rel="shortcut icon"
21 href="../image/favicon_-90.ico">
22 <link rel="stylesheet"
23 type="text/css"
24 href="../css/freetype2_-90.css">
25
26 <script type="text/javascript"
27 src="../../../js/freetype2.js">
28 </script>
29
30 <title>FreeType Glyph Conventions | FreeType Outlines</title>
31 </head>
32
33
34 <body>
35
36 <div id="top"
37 class="bar">
38 <h1><a href="http://freetype.org/index.html">FreeType</a> Glyph
39 Conventions&nbsp;/&nbsp;VI</h1>
40 </div>
41
42
43 <div id="wrapper">
44
45 <div class="colmask leftmenu">
46 <div class="colright">
47 <div class="col1wrap">
48 <div class="col1">
49
50
51 <!-- ************************************************** -->
52
53 <div id="freetype-outlines">
54 <h2>VI. FreeType Outlines</h2>
55
56 <p>The purpose of this section is to present the way
57 FreeType manages vectorial outlines, as well as the most
58 common operations that can be applied on them.</p>
59
60 <h3 id="section-1">1. FreeType outline description and
61 structure</h3>
62
63 <h4>a. Outline curve decomposition</h4>
64
65 <p>An outline is described as a series of closed contours in
66 the 2D plane. Each contour is made of a series of line
67 segments and B&eacute;zier arcs. Depending on the file
68 format, these can be second-order or third-order
69 polynomials. The former are also called quadratic or
70 conic arcs, and they are used in the TrueType format. The
71 latter are called cubic arcs and are mostly used in the
72 PostScript Type&nbsp;1, CFF, and CFF2 formats.</p>
73
74 <p>Each arc is described through a series of start, end, and
75 control points. Each point of the outline has a specific
76 tag which indicates whether it describes a line segment
77 or an arc. The tags can take the following values:</p>
78
79 <table>
80 <tr>
81 <td valign="top">
82 <p><code>FT_CURVE_TAG_ON</code></p>
83 </td>
84 <td valign="top">
85 <p>Used when the point is &lsquo;on&rsquo; the curve.
86 This corresponds to start and end points of segments
87 and arcs. The other tags specify what is called an
88 &lsquo;off&rsquo; point, i.e., a point which isn't
89 located on the contour itself, but serves as a
90 control point for a B&eacute;zier arc.</p>
91 </td>
92 </tr>
93 <tr>
94 <td valign="top">
95 <p><code>FT_CURVE_TAG_CONIC</code></p>
96 </td>
97 <td valign="top">
98 <p>Used for an &lsquo;off&rsquo; point used to control
99 a conic B&eacute;zier arc.</p>
100 </td>
101 </tr>
102 <tr>
103 <td valign="top">
104 <p><code>FT_CURVE_TAG_CUBIC</code></p>
105 </td>
106 <td valign="top">
107 <p>Used for an &lsquo;off&rsquo; point used to control
108 a cubic B&eacute;zier arc.</p>
109 </td>
110 </tr>
111 </table>
112
113 <p>Use the <code>FT_CURVE_TAG(tag)</code> macro to filter out
114 other, internally used flags.
115
116 <p>The following rules are applied to decompose the
117 contour's points into segments and arcs:</p>
118
119 <ul>
120 <li>
121 <p>Two successive &lsquo;on&rsquo; points indicate a
122 line segment joining them.</p>
123
124 <p align="center">
125 <img src="outlines-1.svg"
126 height="40%"
127 width="40%"
128 alt="segment example">
129 </p>
130 </li>
131 <li>
132 <p>One conic &lsquo;off&rsquo; point between two
133 &lsquo;on&rsquo; points indicates a conic
134 B&eacute;zier arc, the &lsquo;off&rsquo; point being
135 the control point, and the &lsquo;on&rsquo; ones the
136 start and end points.</p>
137
138 <p align="center">
139 <img src="outlines-2.svg"
140 height="40%"
141 width="40%"
142 alt="conic arc example">
143 </p>
144 </li>
145 <li>
146 <p>Two successive cubic &lsquo;off&rsquo; points between
147 two &lsquo;on&rsquo; points indicate a cubic
148 B&eacute;zier arc. There must be exactly two cubic
149 control points and two &lsquo;on&rsquo; points for
150 each cubic arc (using a single cubic &lsquo;off&rsquo;
151 point between two &lsquo;on&rsquo; points is
152 forbidden, for example).</p>
153
154 <p align="center">
155 <img src="outlines-3.svg"
156 height="40%"
157 width="40%"
158 alt="cubic arc example">
159 </p>
160 </li>
161 <li>
162 <p>Two successive conic &lsquo;off&rsquo; points force
163 the rasterizer to create (during the scan-line
164 conversion process exclusively) a virtual
165 &lsquo;on&rsquo; point inbetween, at their exact
166 middle. This greatly facilitates the definition of
167 successive conic B&eacute;zier arcs. Moreover, it is
168 the way outlines are described in the TrueType
169 specification.</p>
170
171 <p align="center">
172 <img src="outlines-4.svg"
173 height="40%"
174 width="40%"
175 alt="cubic arc with virtual 'on' point">
176 </p>
177 </li>
178 <li>
179 <p>The last point in a contour uses the first as an end
180 point to create a closed contour. For example, if the
181 last two points of a contour were an &lsquo;on&rsquo;
182 point followed by a conic &lsquo;off&rsquo; point, the
183 first point in the contour would be used as final
184 point to create an &lsquo;on&rsquo; &ndash;
185 &lsquo;off&rsquo; &ndash; &lsquo;on&rsquo; sequence as
186 described above.
187 </li>
188 <li>
189 <p>The first point in a contour can be a conic
190 &lsquo;off&rsquo; point itself; in that case, use the
191 last point of the contour as the contour's starting
192 point. If the last point is a conic &lsquo;off&rsquo;
193 point itself, start the contour with the virtual
194 &lsquo;on&rsquo; point between the last and first
195 point of the contour.
196 </li>
197 </ul>
198
199 <p>Note that it is possible to mix conic and cubic arcs in a
200 single contour, however, no font driver of FreeType
201 produces such outlines currently.</p>
202
203
204 <h4>b. The <code>FT_Outline</code> descriptor</h4>
205
206 <p>A FreeType outline is described through a simple
207 structure
208 called <a href="../reference/ft2-outline_processing.html#ft_outline"><code>FT_Outline</code></a>.
209 Right now, the following fields are of interest:</p>
210
211 <table class="vertical-space">
212 <caption>
213 <b><code>FT_Outline</code></b>
214 </caption>
215 <tbody>
216 <tr>
217 <td>
218 <code>n_points</code>
219 </td>
220 <td>
221 the number of points in the outline
222 </td>
223 </tr>
224 <tr>
225 <td>
226 <code>n_contours</code>
227 </td>
228 <td>
229 the number of contours in the outline
230 </td>
231 </tr>
232 <tr>
233 <td>
234 <code>points</code>
235 </td>
236 <td>
237 array of point coordinates
238 </td>
239 </tr>
240 <tr>
241 <td>
242 <code>contours</code>
243 </td>
244 <td>
245 array of contour end indices
246 </td>
247 </tr>
248 <tr>
249 <td>
250 <code>tags</code>
251 </td>
252 <td>
253 array of point flags
254 </td>
255 </tr>
256 </tbody>
257 </table>
258
259 <p>Here, <code>points</code> is a pointer to an array of
260 <a href="../reference/ft2-basic_types.html#ft_vector"><code>FT_Vector</code></a>
261 records, used to store the vectorial coordinates of each
262 outline point. These are expressed in 1/64 of a pixel,
263 which is also known as the <em>26.6&nbsp;fixed-point
264 format</em>.</p>
265
266 <p><code>contours</code> is an array of point indices to
267 delimit contours in the outline. For example, the first
268 contour always starts at point&nbsp;0, and ends at
269 point <code>contours[0]</code>. The second contour starts
270 at point <code>contours[0]+1</code> and ends at
271 <code>contours[1]</code>, etc. To traverse these points in a
272 callback based manner,
273 use <a href="../reference/ft2-outline_processing.html#ft_outline_decompose"><code>FT_Outline_Decompose</code></a>.</p>
274
275 <p>Note that each contour is closed, and that the value
276 of <code>n_points</code> should be equal
277 to <code>contours[n_contours-1]+1</code> for a valid
278 outline.</p>
279
280 <p>Finally, <code>tags</code> is an array of bytes, used to
281 store each outline point's tag.</p>
282
283
284 <h3 id="section-2">2. Bounding and control box
285 computations</h3>
286
287 <p>As described earlier, a <em>bounding box</em> (also
288 called <em>bbox</em>) is simply a rectangle that
289 completely encloses the shape of a given outline. The
290 interesting case is the smallest bounding box possible,
291 and in the following we subsume this under the term
292 &lsquo;bounding box&rsquo;. Because of the way arcs are
293 defined, B&eacute;zier control points are not necessarily
294 contained within an outline's (smallest) bounding box.</p>
295
296 <p>Such a situation happens if one B&eacute;zier arc is, for
297 example, the upper edge of an outline and an
298 &lsquo;off&rsquo; point happens to be above the bbox.
299 However, it is very rare in the case of character outlines
300 because most font designers and creation tools always
301 place &lsquo;on&rsquo; points at the extrema of each
302 curved edges (as both the TrueType and PostScript
303 specifications recommend), making hinting much easier.</p>
304
305 <p>We thus define the <em>control box</em> (also
306 called <em>cbox</em>) as the smallest possible rectangle
307 that encloses all points of a given outline (including its
308 &lsquo;off&rsquo; points). Clearly, it always includes
309 the bbox, and the two boxes are identical in most
310 cases.</p>
311
312 <p>Unlike the bbox, the cbox can be computed very
313 quickly.</p>
314
315 <p>The following image shows B&eacute;zier curves where the
316 bbox and the cbox differ.</p>
317
318 <p align="center">
319 <img src="outlines-5.svg"
320 height="40%"
321 width="40%"
322 alt="a glyph with different bbox and cbox">
323 </p>
324
325 <p>Adding points at the curve extrema avoids that.</p>
326
327 <p align="center">
328 <img src="outlines-6.svg"
329 height="40%"
330 width="40%"
331 alt="a glyph with identical bbox and cbox">
332 </p>
333
334 <p>Control and bounding boxes can be computed automatically
335 using the
336 functions <a href="../reference/ft2-outline_processing.html#ft_outline_get_cbox"><code>FT_Outline_Get_CBox</code></a>
337 and
338 <a href="../reference/ft2-outline_processing.html#ft_outline_get_bbox"><code>FT_Outline_Get_BBox</code></a>.
339 The former function is always very fast, while the
340 latter <em>may</em> be slow in the case of
341 &lsquo;outside&rsquo; control points (as it needs to find
342 the extreme of conic and cubic arcs for
343 &lsquo;perfect&rsquo; computations). If this isn't the
344 case, it is as fast as computing the control box.
345
346 <p>Note also that even though most glyph outlines have equal
347 cbox and bbox values to ease hinting, this is not
348 necessarily the case if a transformation like rotation is
349 applied to them.</p>
350
351
352 <h3 id="section-3">3. Coordinates, scaling and
353 grid-fitting</h3>
354
355 <p>An outline point's vectorial coordinates are expressed in
356 the 26.6&nbsp;format, i.e., in 1/64 of a pixel, hence the
357 coordinates &lsquo;(1.0,-2.5)&rsquo; is stored as the
358 integer pair &lsquo;(64,-160)&rsquo;, to name an
359 example.</p>
360
361 <p>After a glyph outline is scaled from the EM grid (in font
362 units) to the current character dimensions, the hinter or
363 grid-fitter is in charge of aligning important outline
364 points (mainly edge delimiters) to the pixel grid. Even
365 though this process is much too complex to be described in
366 a few lines, its purpose is mainly to round point
367 positions while trying to preserve important properties
368 like widths, stems, etc.</p>
369
370 <p>The following operations can be used to round vectorial
371 distances in the 26.6&nbsp;format to the grid:</p>
372
373 <pre>
374 round( x ) == ( x + 32 ) &amp; -64
375 floor( x ) == x &amp; -64
376 ceiling( x ) == ( x + 63 ) &amp; -64</pre>
377
378 <p>Once a glyph outline is grid-fitted or transformed, it
379 often is interesting to compute the glyph image's pixel
380 dimensions before rendering it. To do so, one has to
381 consider the following:</p>
382
383 <p>The scan-line converter draws all the pixels
384 whose <em>centers</em> fall inside the glyph shape. In
385 B/W rendering mode, it can also detect <em>drop-outs</em>,
386 i.e., discontinuities coming from extremely thin shape
387 fragments, in order to draw the &lsquo;missing&rsquo;
388 pixels. These new pixels are always located at a distance
389 less than half of a pixel but it is not easy to predict
390 where they will appear before rendering.</p>
391
392 <p>This leads to the following computations:</p>
393
394 <ul>
395 <li>
396 <p>compute the bbox</p>
397 </li>
398 <li>
399 <p>grid-fit the bounding box with the following:</p>
400
401 <pre>
402 xmin = floor( bbox.xMin )
403 xmax = ceiling( bbox.xMax )
404 ymin = floor( bbox.yMin )
405 ymax = ceiling( bbox.yMax )</pre>
406 </li>
407 <li>
408 <p>return pixel dimensions, i.e.,</p>
409
410 <pre>
411 width = (xmax - xmin)/64</pre>
412
413 <p>and</p>
414
415 <pre>
416 height = (ymax - ymin)/64</pre>
417 </li>
418 </ul>
419
420 <p>By grid-fitting the bounding box, it is guaranteed that
421 all the pixel centers that are to be drawn, <em>including
422 those coming from drop-out control</em>, will
423 be <em>within</em> the adjusted box. Then the box's
424 dimensions in pixels can be computed.</p>
425
426 <p>Note also that, when translating a grid-fitted outline, one should
427 <em>always use integer distances</em> to move an outline
428 in the 2D plane. Otherwise, glyph edges won't be aligned
429 on the pixel grid anymore, and the hinter's work will be
430 lost, producing <em>very low quality</em> bitmaps and
431 pixmaps.</p>
432 </div>
433
434 <!-- ************************************************** -->
435
436 <div class="updated">
437 <p>Last update: 23-Oct-2022</p>
438 </div>
439 </div>
440 </div>
441
442
443 <!-- ************************************************** -->
444
445 <div class="col2">
446 </div>
447 </div>
448 </div>
449
450
451 <!-- ************************************************** -->
452
453 <div id="TOC">
454 <ul>
455 <li class="funding">
456 <form action="https://www.paypal.com/cgi-bin/webscr"
457 method="post"
458 target="_top">
459 <input type="hidden"
460 name="cmd"
461 value="_s-xclick">
462 <input type="hidden"
463 name="hosted_button_id"
464 value="SK827YKEALMT4">
•465 <input type="submit"
466 value="Donate"
467 name="submit"
468 alt="PayPal - The safer, easier way to pay online!">
469 </form>
470 </li>
471 <li class="primary">
472 <a href="http://freetype.org/index.html">Home</a>
473 </li>
474 <li class="primary">
475 <a href="http://freetype.org/index.html#news">News</a>
476 </li>
477 <li class="primary">
478 <a href="../index.html">Overview</a>
479 </li>
480 <li class="primary">
481 <a href="../documentation.html">Documentation</a>
482 </li>
483 <li class="primary">
484 <a href="http://freetype.org/developer.html">Development</a>
485 </li>
486 <li class="primary">
487 <a href="http://freetype.org/contact.html"
488 class="emphasis">Contact</a>
489 </li>
490
491 <li>
492 &nbsp; <!-- separate primary from secondary entries -->
493 </li>
494
495 <li class="secondary">
496 <a href="index.html">FreeType Glyph Conventions</a>
497 </li>
498 <li class="tertiary">
499 <a href="glyphs-1.html">Basic Typographic Concepts</a>
500 </li>
501 <li class="tertiary">
502 <a href="glyphs-2.html">Glyph Outlines</a>
503 </li>
504 <li class="tertiary">
505 <a href="glyphs-3.html">Glyph Metrics</a>
506 </li>
507 <li class="tertiary">
508 <a href="glyphs-4.html">Kerning</a>
509 </li>
510 <li class="tertiary">
511 <a href="glyphs-5.html">Text Processing</a>
512 </li>
513 <li class="tertiary">
514 <a href="glyphs-6.html" class="current">FreeType Outlines</a>
515 </li>
516 <li class="tertiary">
517 <a href="glyphs-7.html">FreeType Bitmaps</a>
518 </li>
519 </ul>
520 </div>
521
522 </div> <!-- id="wrapper" -->
523
524 <div id="TOC-bottom">
525 </div>
526
527 </body>
528 </html>