3 <title>An introduction to glyphs
</title>
5 <META name=
"description"
6 content=
"Glyphs in the FreeType engine">
8 content=
"FreeType TrueType library engine glyphs baseline bearing
19 <font size=
1>http://www.freetype.org
</font><p>
22 <font size=
"+2">Glyph Hell
<p>
24 <font size=
"+1">An introduction to glyphs, as used and defined in
25 the FreeType engine
<p>
30 <font size=
"+2">Introduction
<p>
32 <font size=
"+0">This article discusses in great detail the definition
33 of glyph metrics, per se the TrueType specification, and the way they
34 are managed and used by the FreeType engine. This information is
35 crucial when it comes to rendering text strings, either in a
36 conventional (i.e. Roman) layout, or with vertical or right-to-left
37 ones. Some aspects like glyph rotation and transformation are
40 Comments and corrections are highly welcome, and can be sent to the
41 <a href=
"mailto:devel@freetype.org">FreeType developers list
</a>.
<p>
46 <font size=
"+2">I. An overview of font files
<p>
48 <font size=
"+0">In TrueType, a single font file is used to contain
49 information related to classification, modeling and rendering of text
50 using a given typeface. This data is located in various independent
51 `tables', which can be sorted in four simple classes, as described
56 <b><font size=
"+1"><li>Face Data
</font></b><p>
58 We call
<i>face data
</i> the amount of information related to a
59 given typeface, independently of any particular scaling,
60 transformation, and/or glyph index. This usually means some
61 typeface-global metrics and attributes, like family and styles,
62 PANOSE number, typographic ascenders and descenders, as well as
63 some very TrueType specific items like the font `programs' found
64 in the
<i>fpgm
</i> and
<i>prep
</i> tables, the
<i>gasp
</i> table,
65 character mappings, etc.
<p>
67 In FreeType, a
<i>face object
</i> is used to model a font file's
70 <b><font size=
"+1"><li>Instance Data
</font></b><p>
72 We call
<i>instance
</i> a given pointsize/transformation, at a
73 given device resolution (e.g.
8pt at
96x96dpi, or
12pt at
74 300x600dpi, etc). Some tables found in the font files are used to
75 produce instance-specific data, like the
<i>cvt
</i> table, or the
76 <i>prep
</i> program. Though they are often part of the face data,
77 their processing results in information called
<i>instance
80 In FreeType, it is modeled through an
<i>instance object
</i>,
81 which is always created from an existing face object.
<p>
83 <b><font size=
"+1"><li>Glyph Data
</font></b><p>
85 We call
<i>glyph data
</i> the piece of information related to
86 specific glyphs. This includes the following things that are
87 described in more details in the next sections:
<p>
91 <li>The glyph's vectorial representation, also called its
94 <li>Various metrics, like the glyph's
<i>bounding box
</i>, its
95 <i>bearings
</i> and
<i>advance
</i> values.
<p>
97 <li>TrueType specifies a specific instruction
<i>bytecode
</i>,
98 used to associate each glyph with a small
<i>program
</i>,
99 called the
<i>glyph code
</i>. Its purpose is to grid-fit the
100 outline to any target instance, in order to produce excellent
101 output at small pixel sizes.
105 The FreeType engine doesn't map each glyph to a single structure,
106 as this would waste memory for no good reason. Rather, a
<i>glyph
107 object
</i> is a
<i>container
</i>, created from any active face,
108 which can be used to load and/or process any font glyph at any
109 instance (or even no instance at all). Of course, the glyph
110 properties (outline, metrics, bitmaps, etc.) can be extracted
111 independently from an object once it has been loaded or
114 <b><font size=
"+1"><li>Text and Layout Data
</font></b><p>
116 Finally, there is a last class of data that doesn't really fit in
117 all others, and that can be called
<i>text
</i> data. It comprises
118 information related to the grouping of glyphs together to form
119 text. Simple examples are the
<i>kerning
</i> table, which
120 controls the spacing between adjacent glyphs, as well as some of
121 the extensions introduced in
<i>TrueType Open
</i>,
122 <i>OpenType
</i>, and
<i>TrueType GX
</i> like glyph substitution
123 (ligatures, vertical representations), baseline management,
124 justification, etc.
<p>
126 This article focuses on the basic TrueType tables, and hence, will
127 only talk about kerning, as FreeType doesn't support OpenType nor
128 GX (yet). [Support for TrueType Open is already partially
136 <font size=
"+2">II. Glyph Outlines
<p>
138 <font size=
"+0">TrueType is a scalable font format; it is thus
139 possible to render glyphs at any scale, and under any affine
140 transform, from a single source representation. However, simply
141 scaling vectorial shapes exhibits at small sizes (where `small' refers
142 here to anything smaller than at least
150 pixels) a collection
143 of un-harmonious artifacts, like widths and/or heights
146 Because of this, the format also provides a complete programming
147 language used to design small programs associated to each glyph. Its
148 role is to align the point positions on the pixel grid after the
149 scaling. This operation is hence called
<i>grid-fitting
</i>, or even
154 <font size=
"+1"><li>Vectorial representation
</font><p>
156 The source format of outlines is a collection of closed paths
157 called
<i>contours
</i>. Each contour delimits an outer or inner
158 region of the glyph, and can be made of either line segments
159 and/or second-order beziers (also called
<i>conic beziers
</i> or
160 <i>quadratics
</i>).
<p>
162 It is described internally as a series of successive points, with
163 each point having an associated flag indicating whether it is `on'
164 or `off' the curve. These rules are applied to decompose the
169 <li>Two successive `on' points indicate a line segment joining
172 <li>One `off' point amidst two `on' points indicates a conic
173 bezier, the `off' point being the control point, and the `on'
174 ones the start and end points.
<p>
176 <li>Finally, two successive `off' points forces the rasterizer
177 to create (only during bitmap rendering) a virtual `on' point
178 amidst them, at their exact middle. This greatly facilitates
179 the definition of successive Bezier arcs.
193 Two `on' points and one `off' point
199 # __ Two `on' points with two `off'
200 \ - - points between them. The point
201 \ / \ marked `
0' is the middle of the
202 -
0 \ `off' points, and is a `virtual
203 -_ _- # on' point where the curve passes.
204 -- It does not appear in the point
209 <img src=
"image/emsquare.gif" align=
"right" width=
333 height=
274>
211 Each glyph's original outline points are located on a grid of
212 indivisible units. The points are stored in the font file as
213 16-bit integer grid coordinates, with the grid origin's being at
214 (
0,
0); they thus range from -
16384 to
16383.
<p>
216 In creating the glyph outlines, a type designer uses an imaginary
217 square called the
<i>EM square
</i>. Typically, the EM square
218 encloses the capital letter `M' and most other letters of a
219 typical roman alphabet. The square's size, i.e., the number of
220 grid units on its sides, is very important for two reasons:
<p>
224 <li>It is the reference used to scale the outlines to a given
225 instance. For example, a size of
12pt at
300x300dpi
226 corresponds to
12*
300/
72 =
50 pixels. This is the
227 size the EM square would appear on the output device if it was
228 rendered directly. In other words, scaling from grid units to
229 pixels uses the formula
<p>
232 pixel_size
= point_size
*
233 resolution
/
72
237 pixel_coordinate
= grid_coordinate
*
238 pixel_size
/
EM_size
241 <li>The greater the EM size is, the larger resolution the
242 designer can use when digitizing outlines. For example, in
243 the extreme example of an EM size of
4 units, there are
244 only
25 point positions available within the EM square
245 which is clearly not enough. Typical TrueType fonts use an EM
246 size of
2048 units (note: with Type
1 PostScript
247 fonts, the EM size is fixed to
1000 grid units. However,
248 point coordinates can be expressed in floating values).
252 Note that glyphs can freely extend beyond the EM square if the
253 font designer wants this. The EM is used as a convenience, and is
254 a valuable convenience from traditional typography.
<p>
258 Grid units are very often called
<i>font units
</i> or
<i>EM
264 <i>IMPORTANT NOTE:
</i><p>
266 Under FreeType, scaled pixel positions are all expressed in the
267 26.6 fixed float format (made of a
26-bit integer mantissa, and a
268 6-bit fractional part). In other words, all coordinates are
269 multiplied by
64. The grid lines along the integer pixel
270 positions, are multiples of
64, like (
0,
0), (
64,
0), (
0,
64),
271 (
128,
128), etc., while the pixel centers lie at middle coordinates
272 (
32 modulo
64) like (
32,
32), (
96,
32), etc.
275 <font size=
"+1"><li>Hinting and Bitmap rendering
</font><p>
277 As said before, simply scaling outlines to a specific instance
278 always creates undesirable artifacts, like stems of different
279 widths or heights in letters like `E' or `H'. Proper glyph
280 rendering needs that the scaled points are aligned along the pixel
281 grid (hence the name
<i>grid-fitting
</i>), and that important
282 widths and heights are respected throughout the whole font (for
283 example, it is very often desirable that the letters `I' and `T'
284 have their central vertical line of the same pixel width).
<p>
286 Type
1 PostScript font files include with each glyph a small
287 series of distances called
<i>hints
</i>, which are later used by
288 the type manager to try grid-fitting the outlines as cleverly as
289 possible. On one hand, it has the consequence that upgrading your
290 font engine can enhance the visual aspects of all fonts of your
291 system; on the other hand, the quality of even the best version of
292 Adobe's Type Manager isn't always very pleasing at small sizes
293 (notwithstanding font smoothing).
<p>
295 TrueType takes a radically different approach: Each glyph has an
296 associated `program', designed in a specific geometrical language,
297 which is used to align explicitly each outline point to the pixel
298 grid, preserving important distances and metrics. A stack-based
299 low-level bytecode is used to store it in the font file, and is
300 interpreted later when rendering the scaled glyphs.
<p>
302 This means that even very complex glyphs can be rendered perfectly
303 at very small sizes, as long as the corresponding glyph code is
304 designed correctly. Moreover, a glyph can loose some of its
305 details, like serifs, at small sizes to become more readable,
306 because the bytecode provides interesting features.
<p>
308 However, this also have the sad implication that an ill-designed
309 glyph code will always render junk, whatever the font engine's
310 version, and that it's very difficult to produce quality glyph
311 code. There are about
200 TrueType opcodes, and no known
312 `high-level language' for it. Most type artists aren't
313 programmers at all and the only tools able to produce quality code
314 from vectorial representation have been distributed to only a few
315 font foundries, while tools available to the public, e.g.
316 Fontographer, are usually expensive though generating average to
317 mediocre glyph code.
<p>
319 All this explains why an enormous number of broken or ugly `free'
320 fonts have appeared on the TrueType scene, and that this format is
321 now mistakenly thought as `crap' by many people. Funnily, these
322 are often the same who stare at the `beauty' of the classic `Times
323 New Roman' and `Arial/Helvetica' at
8 points.
<p>
325 Once a glyph's code has been executed, the scan-line converter
326 converts the fitted outline into a bitmap (or a pixmap with
334 <font size=
"+2">III. Glyph metrics
</font><p>
338 <font size=
"+1"><li>Baseline, Pens and Layouts
</font><p>
340 The baseline is an imaginary line that is used to `guide' glyphs
341 when rendering text. It can be horizontal (e.g. Roman, Cyrillic,
342 Arabic, etc.) or vertical (e.g. Chinese, Japanese, etc).
343 Moreover, to render text, a virtual point, located on the
344 baseline, called the
<i>pen position
</i>, is used to locate
347 Each layout uses a different convention for glyph placement:
<p>
351 <li>With horizontal layout, glyphs simply `rest' on the
352 baseline. Text is rendered by incrementing the pen position,
353 either to the right or to the left.
<p>
356 <img src=
"image/baseline.gif" width=
458 height=
179><p>
359 The distance between two successive pen positions is
360 glyph-specific and is called the
<i>advance width
</i>. Note
361 that its value is
<b>always
</b> positive, even for
362 right-to-left oriented alphabets, like Arabic. This
363 introduces some differences in the way text is rendered.
<p>
366 <i>IMPORTANT NOTE:
</i><p>
368 The pen position is always placed on the baseline in
369 TrueType, unlike the convention used by some graphics
370 systems, like Windows, to always put the pen above the line,
371 at the ascender's position.
374 <li>With vertical layout, glyphs are centered around the
378 <img src=
"image/baselin2.gif" width=
162 height=
275>
383 <font size=
"+1"><li>Typographic metrics and bounding
386 A various number of face metrics are defined for all glyphs in
387 a given font. Three of them have a rather curious status in
388 the TrueType specification; they only apply to horizontal
393 <li>The
<i>ascent
</i><p>
395 This is the distance from the baseline to the highest/upper
396 grid coordinate used to place an outline point. It is a
397 positive value, due to the grid's orientation with the
398 y
axis upwards.
<p>
400 <li>The
<i>descent
</i><p>
402 The distance from the baseline to the lowest grid coordinate
403 used to place an outline point. This is a negative value,
404 due to the grid's orientation.
<p>
406 <li>The
<i>linegap
</i><p>
408 The distance that must be placed between two lines of text.
409 The baseline-to-baseline distance should be computed as
<p>
412 ascent
- descent
+ linegap
415 if you use the typographic values.
419 The problem with these metrics is that they appear three times
420 in a single font file, each version having a slightly different
425 <li>The font's horizontal header provides the ascent, descent
426 and linegap fields, which are used to express the designer's
427 intents, rather than the real values that may be computed
428 from all glyphs in the outline. These are used by the
429 Macintosh font engine to perform font mapping (i.e. font
432 <li>The OS/
2 table provides the
<i>usWinAscent
</i> and
433 <i>usWinDescent
</i> fields. These values are computed for
434 glyphs of the Windows ANSI charset only, which means that
435 they are wrong for any other glyph. Note that
436 <i>usWinDescent
</i> is always positive (i.e. looks like
439 <li>The OS/
2 table provides the
<i>typoAscender
</i>,
440 <i>typoDescender
</i> and
<i>typoLinegap
</i> values, which
441 hopefully concern the whole font file. These are the
442 correct system-independent values!
446 All metrics are expressed in font units. If you want to use any
447 of the two first versions of these metrics, the TrueType
448 specification contains some considerations and computing tips
449 that might help you.
<p>
451 Other, simpler metrics are:
<p>
455 <li>The glyph's bounding box, also called
<i>bbox
</i><p>
457 This is an imaginary box that encloses any glyph (usually as
458 tightly as possible). It is represented by four fields,
459 namely
<i>xMin
</i>,
<i>yMin
</i>,
<i>xMax
</i>, and
460 <i>yMax
</i>, that can be computed for any outline. In
461 FreeType, their values can be in font units (if measured in
462 the original outline) or in
26.6 pixel units (if
463 measured on scaled outlines).
<p>
465 Note that if it wasn't for grid-fitting, you wouldn't need
466 to know a box's complete values, but only its dimensions to
467 know how big is a glyph outline/bitmapa. However, correct
468 rendering of hinted glyphs needs the preservation of
469 important grid alignment on each glyph translation/placement
470 on the baseline, which is why FreeType always returns the
471 complete glyph outline.
<p>
473 Note also that the font's header contains a global font
474 bounding box in font units which should enclose all glyphs
475 in a font. This can be used to pre-compute the maximum
476 dimensions of any glyph at a given instance.
<p>
478 <li>The
<i>internal leading
</i><p>
480 This concept comes directly from the world of traditional
481 typography. It represents the amount of space within the
482 `leading' which is reserved for glyph features that lay
483 outside of the EM square (like accentuation). It usually
484 can be computed as
<p>
487 internal_leading
= ascent
- descent
-
491 <li>The
<i>external leading
</i><p>
493 This is another name for the linegap.
497 <font size=
"+1"><li><i>Bearings
</i> and
<i>Advances
</i></font><p>
499 Each glyph has also distances called
<i>bearings
</i> and
500 <i>advances
</i>. Their definition is constant, but their values
501 depend on the layout, as the same glyph can be used to render
502 text either horizontally or vertically.
<p>
505 <li>The
<i>left side bearing
</i>: a.k.a.
<i>bearingX
</i><p>
507 This is the horizontal distance from the current pen
508 position to the glyph's left bounding box edge. It is
509 positive for horizontal layouts, and most generally negative
512 <li>The
<i>top side bearing
</i>: a.k.a.
<i>bearingY
</i><p>
514 This is the vertical distance from the baseline to the top
515 of the glyph's bounding box. It is usually positive for
516 horizontal layouts, and negative for vertical ones
<p>
518 <li>The
<i>advance width
</i>: a.k.a.
<i>advanceX
</i><p>
520 This is the horizontal distance the pen position must be
521 incremented (for left-to-right writing) or decremented (for
522 right-to-left writing) by after each glyph is rendered when
523 processing text. It is always positive for horizontal
524 layouts, and null for vertical ones.
<p>
526 <li>The
<i>advance height
</i>: a.k.a.
<i>advanceY
</i><p>
528 This is the vertical distance the pen position must be
529 decremented by after each glyph is rendered. It is always
530 null for horizontal layouts, and positive for vertical
533 <li>The
<i>glyph width
</i><p>
535 The glyph's horizontal extent. More simply, it is
536 (bbox.xMax
- bbox.xMin) for unscaled font coordinates.
537 For scaled glyphs, its computation requests specific care,
538 described in the grid-fitting chapter below.
<p>
540 <li>The
<i>glyph height
</i><p>
542 The glyph's vertical extent. More simply, it is
543 (bbox.yMax
- bbox.yMin) for unscaled font coordinates.
544 For scaled glyphs, its computation requests specific care,
545 described in the grid-fitting chapter below.
<p>
547 <li>The
<i>right side bearing
</i><p>
549 Only used for horizontal layouts to describe the distance
550 from the bbox's right edge to the advance width. It is in
551 most cases a non-negative number. The FreeType library
552 doesn't provide this metric directly, as it isn't really
553 part of the TrueType specification. It can be computed
557 advance_width
- left_side_bearing
- (xMax-xMin)
563 <img src=
"image/metrics.gif" width=
388 height=
253><p>
565 <img src=
"image/metrics2.gif" width=
294 height=
278>
568 Finally, if you use `ABC widths' under Windows and OS/
2, the
569 following relations apply:
572 A = left side bearing
574 C = right side bearing
576 A+B+C = advance width
579 <font size=
"+1"><li>The effects of grid-fitting
</font><p>
581 All these metrics are stored in font units in the font file.
582 They must be scaled and grid-fitted properly to be used at a
583 specific instance. This implies several things:
<p>
587 <li>First, a glyph program not only aligns the outline along
588 the grid pixel, it also processes the left side bearing and
589 the advance width. Other grid-fitted metrics are usually
590 available in optional TrueType tables if you need them.
<p>
592 <li>A glyph program may decide to extend or stretch any of
593 these two metrics if it has a need for it. This means that
594 you cannot assume that the fitted metrics are simply equal
595 to the scaled one plus or minus a liberal distance
596 <
1 pixel (i.e., less than
64 fractional
597 pixel units). For example, it is often necessary to stretch
598 the letter `m' horizontally at small pixel sizes to make all
599 vertical stems visible, while the same glyph can be
600 perfectly `square' at larger sizes.
<p>
602 <li>Querying the fitted metrics of all glyphs at a given
603 instance is very slow, as it needs to load and process each
604 glyph independently. For this reason, some optional
605 TrueType tables are defined in the specification, containing
606 pre-computed metrics for specific instances (the most
607 commonly used, like
8,
9,
10,
11,
12, and
14 points at
608 96dpi, for example). These tables aren't always present in
611 If you don't need the exact fitted value, it's much faster
612 to query the metrics in font units, then scale them to the
613 instance's dimensions.
618 <i>IMPORTANT NOTE:
</i><p>
620 Another very important consequence of grid-fitting is the fact
621 that moving a fitted outline by a non-integer pixel distance
622 will simply ruin the hinter's work, as alignments won't be
623 preserved. The translated glyph will then look `ugly' when
624 converted to a bitmap!
<p>
626 In other words, each time you want to translate a fitted glyph
627 outline, you must take care of only using integer pixel
628 distances (the x and y
offsets must be multiples
629 of
64, which equals to
1.0 in the
26.6 fixed float
632 If you don't care about grid-fitting (typically when rendering
633 rotated text), you can use any offset you want and use sub-pixel
642 <font size=
"+2">IV. Text processing
</font><p>
644 This section demonstrates how to use the concepts previously defined
645 to render text, whatever the layout you use.
<p>
649 <font size=
"+1"><li>Writing simple text strings
</font><p>
651 We will start by generating a simple string with a Roman alphabet.
652 The layout is thus horizontal, left to right.
<p>
654 For now, we will assume all glyphs are rendered in a single target
655 bitmap. The case of generating individual glyph bitmaps, then
656 placing them on demand on a device is presented in a later chapter
659 Rendering the string needs to place each glyph on the baseline;
660 this process looks like the following:
<p>
664 <li>Place the pen to the cursor position. The pen is always
665 located on the baseline. Its coordinates must be grid-fitted
666 (i.e. multiples of
64)!
<p>
673 <li>Load the glyph outline and its metrics. Using the flag
674 TTLOAD_DEFAULT will scale and hint the glyph:
677 TT_Load_Glyph( instance,
682 TT_Get_Glyph_Metrics( glyph, &metrics );
683 TT_Get_Glyph_Outline( glyph, &outline );
686 <li>The loader always places the glyph outline relative to the
687 imaginary pen position (
0,
0). You thus simply need to
688 translate the outline by the vector:
694 To place it on its correct position, you can use the call
697 TT_Translate_Outline( outline, pen_x, pen_y );
700 <li>Render the outline in the target bitmap, the glyph will be
701 surimposed on it with a binary `or' operation (FreeType never
702 creates glyph bitmaps by itself, it simply renders glyphs in
703 the arrays you pass to it. See the API reference for a
704 complete description of bitmaps and pixmaps).
707 TT_Get_Outline_Bitmap( outline, &target_bitmap );
711 <i>IMPORTANT NOTE:
</i><p>
713 If you don't want to access the outline in your code, you can
714 also use the API function TT_Get_Glyph_Bitmap() which does the
715 same as the previous lines:
718 TT_Get_Glyph_Outline( glyph, &outline );
719 TT_Translate_Outline( outline, x_offset, y_offset );
720 TT_Get_Outline_Bitmap( outline, &target_bitmap );
721 TT_Translate_Outline( outline, -x_offset, -y_offset );
727 TT_Get_Glyph_Bitmap( glyph,
734 <li>Now advance the pen to its next position. The advance is
735 always grid-fitted when the glyph was hinted:
<p>
738 pen_x += metrics.advance;
741 The advance being grid-fitted, the pen position remains
742 aligned on the grid.
<p>
744 <li>Start over on item
2 until string completion. That's
749 <font size=
"+1"><li>Writing right-to-left and vertical text
</font><p>
751 Generating strings for different layouts is very similar. Here
752 are the most important differences.
<p>
756 <li>For right-to-left text (like Arabic)
<p>
758 The main difference here is that, as the advance width and
759 left side bearings are oriented against the flow of text, the
760 pen position must be
<i>decremented
</i> by the advance width,
761 <i>before
</i> placing and rendering the glyph. Other than
762 that, the rest is strictly similar.
<p>
764 <li>For vertical text (like Chinese or Japanese)
<p>
766 In this case, the baseline is vertical, which means that the
767 pen position must be shifted in the vertical direction. You
768 need the vertical glyph metrics to do that (using the
769 TT_Get_Big_Glyph_Metrics() function).
<p>
771 Once you get these, the rest of the process is very similar.
772 The glyph outline is placed relative to an imaginary origin of
773 (
0,
0), and you should translate it to the pen position before
776 The big difference is that you must decrement pen_y, rather
777 than increment pen_x (this is for the TrueType convention of y
781 pen_y -= metrics.advance;
786 <font size=
"+1"><li>Generating individual glyph bitmaps and using
787 them to render text
</font><p>
789 Loading each glyph when rendering text is slow, and it's much
790 more efficient to render each one in a standalone bitmap to place
791 it in a cache. Text can then be rendered fast by applying simple
792 blit operations on the target device.
<p>
794 To be able to render text correctly with the bitmaps, you must
795 record and associate with them its fitted bearings and advances.
796 Hence the following process:
<p>
800 <li>Generate the bitmaps.
<p>
804 <li>Load the glyph and get its metrics.
807 TT_Load_Glyph( instance,
812 TT_Get_Glyph_Metrics( glyph, &metrics );
815 The bbox is always fitted when calling
816 TT_Get_Glyph_Metrics() on a hinted glyph. You can then
817 easily compute the glyph's dimension in pixels as:
820 width = (bbox.xMax - bbox.xMin) /
64;
821 height = (bbox.yMax - bbox.yMin) /
64;
825 The fitted bounding box always contains all the dropouts
826 that may be produced by the scan-line converter. This
827 width and height are thus valid for all kinds of
831 If you want to compute the dimensions of a rotated
832 outline's bitmap, compute its bounding box with
833 TT_Get_Outline_BBox(), then grid-fit the bbox manually:
836 #define FLOOR(x) ((x) & -
64)
837 #define CEILING(x) (((x)+
63) & -
64)
841 yMin = CEILING(xMax);
842 yMax = CEILING(yMax);
845 then compute width and height as above.
<p>
847 <li>Create a bitmap of the given dimension, e.g.:
850 bitmap.width = width;
851 bitmap.cols = (width+
7) & -
8;
852 bitmap.rows = height;
853 bitmap.flow = TT_Flow_Up;
854 bitmap.size = bitmap.cols * bitmap.rows;
855 bitmap.buffer = malloc( bitmap.size );
858 <li>Render the glyph into the bitmap.
<p>
860 Don't forget to shift it by (-xMin, -yMin) to fit it in
864 /* Note that the offsets must be grid-fitted to */
865 /* preserve hinting! */
866 TT_Get_Glyph_Bitmap( glyph,
874 <li>Store the bitmap with the following values:
877 bearingX /
64 = left side bearing in pixels
878 advance /
64 = advance width/height in pixels
881 When your cache is set up, you can then render text using a
882 scheme similar to the ones describe in
1. and
2.,
883 with the exception that now pen positions and metrics are
884 expressed in pixel values. We are done!
890 while ( glyph_to_render )
892 access_cache( glyph_index, metrics, bitmap );
894 blit_bitmap_to_position
896 pen_y (+ bearingY depending on orientation ) );
904 <font size=
"+1"><li>Device-independent text rendering
</font><p>
906 The previously described rendering processes all align glyphs on
907 the baseline according to metrics fitted for the display's
908 distance. In some cases, the display isn't the final output, and
909 placing the glyphs in a device-independent way is more important
912 A typical case is a word processor which displays text as it
913 should appear on paper when printed. As you've probably noticed,
914 the glyphs aren't always spaced uniformly on the screen as you
915 type them, sometimes the space between an `m' and a `t' is too
916 small, some other it is too large, etc.
<p>
918 These differences are simply due to the fact that the word
919 processor aligns glyphs in an device-independent way, using
920 original metrics in font units to do it, then scale them as it
921 can to display text on screen, usually at a very smaller
922 resolution than your printer's one.
<p>
924 Device-independence is a crucial part of document portability,
925 and it is very saddening to see that most professional word
926 processors don't do it correctly. For example, MS
Word uses
927 the fitted metrics of the printer's resolution, rather than the
928 originals in font units.
<p>
930 This is great to get sure that your text prints very well on your
931 printer, but it also implies that someone printing the exact same
932 document on a device with different output resolutions (e.g.
933 bubble-jet vs. laser printers) may encounter trouble.
<p>
935 As the differences in advances accumulate on one line, they can
936 sum to the width of one or more glyphs in extreme cases, which is
937 enough to `overflow' the automatic justification algorithm. This
938 may add additional lines of printed text, or even remove some.
939 Moreover, supplemental lines can produce unexpected page breaks
940 and `blank' pages. This can be extremely painful when working
941 with large documents, as this `feature' may require you to
942 redesign completely your formatting to re-print it.
<p>
944 In conclusion, if you want portable document rendering, never
945 hesitate to use and apply device-independent terms! For example,
946 a simple way to produce text would be:
<p>
950 <li>Get a scale to convert from your device-independent units
953 <li>Get another scale to convert from original font units to
954 device-independent units.
<p>
956 <li>Perform pen placement and advances in device-independent
959 <li>To render each glyph, compute the pen's rounded position,
960 as well as the rounded glyph left side bearing, both
961 expressed in
26.6 pixels (don't use the fitted metrics). You
962 will then be able to place the glyph and/or blit its bitmap.
966 <font size=
"+1"><li>Kerning glyphs
</font><p>
968 An interesting effect that most people appreciate is
969 <i>kerning
</i>. It consists of modifying the spacing between two
970 successive glyphs according to their outlines. For example, the
971 letters `T' and a `y' can be easily moved closer, as the top of
972 the `y' fits nicely under the `T's upper right bar.
<p>
974 To perform kerning, the TrueType specification provides a
975 specific table (its tag being `kern'), with several storage
976 formats. This section doesn't explain how to access this
977 information; however, you can have a look at the standard
978 extension called `ttkern.h' which comes with FreeType.
<p>
980 The
<i>kerning distance
</i> between two glyphs is a value
981 expressed in font units which indicates whether their outline can
982 be moved together or apart when one follows the other. The
983 distance isn't reflexive, which means that the kerning for the
984 glyph pair (`T',`y') isn't the same as the one for (`y',`T').
<p>
986 The value is positive when the glyphs must be moved apart, and
987 negative when they must be moved closer. You can implement
988 kerning simply by adding its scaled and rounded value to the
989 advance width when moving the pen position. Here an example for
993 #define ROUND( x ) ( (x +
32) & -
64 )
995 scaled_kerning = kerning * imetrics.x_scale /
0x10000;
997 pen_x += metrics.advance + ROUND( scaled_kerning );
1000 <font size=
"+1"><li>Rotated and stretched/slanted text
</font><p>
1002 In order to produce rotated glyphs with FreeType, one must
1003 understand a few things:
<p>
1007 <li>The engine doesn't apply specific transformations to the
1008 glyphs it loads and processes (other than the simpler
1009 resolution-base scaling and grid-fitting). If you want to
1010 rotate glyphs, you will have to load their outline, then apply
1011 the geometric transformations that please you (a number of
1012 APIs are there to help you to do it easily).
<p>
1014 <li>Even if the glyph loader hints `straight' glyphs, it is
1015 possible to inform the font and glyph programs that you're
1016 going to later transform the resulting outlines. Two flags
1017 can be passed to the bytecode interpreter:
<p>
1021 <li>The `rotated' flag indicates that you are going to
1022 rotate the glyphs in a non-trivial direction (i.e., on
1023 neither of the two coordinate axis). You are advised not
1024 to set it when writing
90 degrees-rotated text for
1027 <li>The `stretched' flag indicates that you are going to
1028 apply a transformation that will distort distances. While
1029 rotations and symmetries keep distances constant, slanting
1030 and stretching do modify them.
1036 These flags can be interpreted by the glyph code to toggle certain
1037 processings which vary from one font to the other. However, most
1038 of the TrueType fonts that were tested with FreeType, if not all
1039 of them, simply change the dropout-mode when any of these flags is
1040 set, and/or disable hinting when rotation is detected. We advise
1041 you to never set these flags, even when rotating text. For what
1042 it's worth, hinted rotated text is no uglier than un-hinted
1045 You can use the function TT_Set_Instance_Transform_Flags() to set
1046 them. Then, rendering can be done with the following calls:
1050 TT_Set_Instance_Transforms( instance,
1054 /* load a given glyph */
1055 TT_Get_Glyph_Outline( instance,
1060 /* access its outline */
1061 TT_Get_Glyph_Outline( instance, &outline );
1063 /* in order to transform it */
1064 TT_Transform_Outline( outline, &matrix );
1066 TT_Translate_Outline( outline,
1067 x_offset, y_offset );
1070 TT_Get_Outline_Bitmap( outline, &bitmap );
1073 Here is an example, assuming that the following variables
1076 TT_Matrix matrix; /*
2x2 matrix */
1077 TT_Pos x_off, y_off; /* corrective offsets */
1080 define a transformation that can be correctly applied to a glyph
1081 outline which have been previously placed relative to the
1082 imaginary point position (
0,
0) with bearings preserved. Rendering
1083 text can now be done as follows:
<p>
1087 <li>Initialize the pen position; when rotating, it is extremely
1088 well advised to use sub-pixel placement as you don't care
1096 <li>Transform the glyph as needed, then translate it to the
1097 current pen position:
1100 TT_Transform_Outline( outline, &matrix );
1101 TT_Translate_Outline( outline,
1106 (Note that the transformation offsets have been included in
1107 the translation.)
<p>
1109 <li>Render the bitmap, as it has now been placed correctly.
<p>
1111 <li>To change the pen position, transform the vector (
0,advance)
1112 with your matrix, and add it:
1115 vec_x = metrics.advance;
1117 TT_Transform_Vector( &vec_x, &vec_y, &matrix );
1122 <li>Start over at
2. until completion.
1127 <i>IMPORTANT NOTE:
</i><p>
1129 Do not grid-fit the pen position before rendering your glyph when
1130 rendering rotated text. If you do, your transformed baseline
1131 won't be preserved on each glyph, and the text will look like it's
1132 `hopping' randomly. This is particularly visible at small
1135 Sub-pixel precision placement is
<i>very
</i> important for clean
1139 <font size=
"+1"><li>Font-smoothing, a.k.a. gray-levels
1142 The FreeType engine's scan-line converter (the component also
1143 called the
<i>rasterizer
</i>) is able to convert a vectorial glyph
1144 outline into either a normal bitmap, or an
8-bit pixmap (a.k.a.
1145 <i>colored bitmaps
</i> on some systems). This last feature is
1146 called
<i>gray-level rendering
</i> or
<i>font-smoothing
</i>,
1147 because it uses a user-supplied palette to produce anti-aliased
1148 versions of the glyphs.
<p>
1150 Its principle is to render a bitmap which is twice as large than
1151 the target pixmap, then simply filtering it using a
2x2
1157 FreeType's scan-line converter doesn't use or need an intermediate
1158 second bitmap. Rather, filtering is performed in a single pass
1159 during the sweep (see the file `raster.txt' for more information
1163 You'll notice that, as with Windows
95, FreeType's rasterizer
1164 only grays those parts of the glyph which need it, i.e., diagonals
1165 and curves, while keeping horizontal and vertical stems straight
1166 `black'. This greatly improves the legibility of text, while
1167 avoiding the `blurry' look anti-aliased fonts typically found with
1168 Adobe's Type Manager or Acrobat.
<p>
1170 There are thus five available gray-levels, ranging from
0
1171 to
4, where level
0 and level
4 are the background
1172 and foreground colors, respectively, and where levels
1,
1173 2,
3 are intermediate. For example, to render black text on
1174 a white background, one can use a palette like:
<p>
1178 palette[
0]
= white (background)
<br>
1179 palette[
1]
= light gray
<br>
1180 palette[
2]
= medium gray
<br>
1181 palette[
3]
= dark gray
<br>
1182 palette[
4]
= black (foreground)
<br>
1186 To set the engine's gray-level palette, simply use the API
1187 function TT_Set_Raster_Palette() after initialization. It expects
1188 an array of
5 chars which will be used to render the
1191 Note that the rasterizer doesn't create bitmaps or pixmaps.
1192 Rather, it simply renders glyphs in the arrays you pass to it.
1193 The generated glyph bitmaps are simply `or'-ed to the target (with
1194 0 being the background as a convention); in the case of pixmaps,
1195 pixels are simply written to the buffer, in spans of four aligned
1201 The raster isn't able to superpose `transparent' glyphs on the
1202 target pixmap. This means that you should always call the API
1203 functions TT_Get_Glyph_Pixmap() and TT_Get_Outline_Pixmap() with
1204 an empty map, and perform the superposition yourself.
<p>
1206 This can be more or less tricky, depending on the palette you are
1207 using and your target graphics resolution. One of the components
1208 found in the test directory, called `display.c', has large
1209 comments on the way it implements it for the test programs. You
1210 are encouraged to read the test program sources to understand how
1211 one can take advantage of font smoothing.
<p>
1213 Pixmap surimposition is too system-specific a feature to be part
1214 of the FreeType engine. Moreover, not everybody needs it!
1217 Finally, the question of sur-imposing anti-aliased colored text on
1218 any texture, since being even more tricky, is left as an exercise
1219 to the reader
;-) If this topic really interests you, the
1220 FreeType mailing list may host some helpful enthusiasts ready to
1221 answer your questions. Who knows
:-)
<p>
1223 <font size=
"+1"><li>Other interesting text processes
</font><p>
1227 <li>Glyph substitution
<p>
1229 Substitution is used to replace one glyph by another when some
1230 specific condition is met in the text string. Its most common
1231 examples are ligatures (like replacing the `f' followed by `i'
1232 by the single glyph `fi' if available in the font), as well as
1233 positional selection as performed in the Arabic script (for
1234 those not aware of this, each letter of the Arabic alphabet
1235 can be written differently according to its position on words:
1236 starting, ending, intermediate, or isolated).
<p>
1238 The base TrueType format doesn't define any table for glyph
1239 substitution. However, GX, TrueType Open, and OpenType
1240 provide (incompatible) extensions to perform it. Of course,
1241 it isn't supported by the engine, but an extension could be
1242 easily written to access the required tables.
<p>
1244 [Support for TrueType Open is already partially available.]
<p>
1246 <li>Justification
<p>