diff options
Diffstat (limited to 'Build/source/libs/freetype/freetype-1.5/docs/glyphs.txt')
-rw-r--r-- | Build/source/libs/freetype/freetype-1.5/docs/glyphs.txt | 999 |
1 files changed, 999 insertions, 0 deletions
diff --git a/Build/source/libs/freetype/freetype-1.5/docs/glyphs.txt b/Build/source/libs/freetype/freetype-1.5/docs/glyphs.txt new file mode 100644 index 00000000000..239686aefea --- /dev/null +++ b/Build/source/libs/freetype/freetype-1.5/docs/glyphs.txt @@ -0,0 +1,999 @@ +http://www.freetype.org + + Glyph Hell + + An introduction to glyphs, as used and defined in the FreeType engine + + ------------------------------------------------------------------------ + +Introduction + +This article discusses in great detail the definition of glyph metrics, per +se the TrueType specification, and the way they are managed and used by the +FreeType engine. This information is crucial when it comes to rendering text +strings, either in a conventional (i.e. Roman) layout, or with vertical or +right-to-left ones. Some aspects like glyph rotation and transformation are +explained too. + +Comments and corrections are highly welcome, and can be sent to the FreeType +developers list. + + ------------------------------------------------------------------------ + +I. An overview of font files + +In TrueType, a single font file is used to contain information related to +classification, modeling and rendering of text using a given typeface. This +data is located in various independent `tables', which can be sorted in four +simple classes, as described below: + + * Face Data + + We call face data the amount of information related to a given + typeface, independently of any particular scaling, transformation, + and/or glyph index. This usually means some typeface-global metrics and + attributes, like family and styles, PANOSE number, typographic + ascenders and descenders, as well as some very TrueType specific items + like the font `programs' found in the fpgm and prep tables, the gasp + table, character mappings, etc. + + In FreeType, a face object is used to model a font file's face data. + + * Instance Data + + We call instance a given pointsize/transformation, at a given device + resolution (e.g. 8pt at 96x96dpi, or 12pt at 300x600dpi, etc). Some + tables found in the font files are used to produce instance-specific + data, like the cvt table, or the prep program. Though they are often + part of the face data, their processing results in information called + instance data. + + In FreeType, it is modeled through an instance object, which is always + created from an existing face object. + + * Glyph Data + + We call glyph data the piece of information related to specific glyphs. + This includes the following things that are described in more details + in the next sections: + + o The glyph's vectorial representation, also called its outline. + + o Various metrics, like the glyph's bounding box, its bearings and + advance values. + + o TrueType specifies a specific instruction bytecode, used to + associate each glyph with a small program, called the glyph code. + Its purpose is to grid-fit the outline to any target instance, in + order to produce excellent output at small pixel sizes. + + The FreeType engine doesn't map each glyph to a single structure, as + this would waste memory for no good reason. Rather, a glyph object is a + container, created from any active face, which can be used to load + and/or process any font glyph at any instance (or even no instance at + all). Of course, the glyph properties (outline, metrics, bitmaps, etc.) + can be extracted independently from an object once it has been loaded + or processed. + + * Text and Layout Data + + Finally, there is a last class of data that doesn't really fit in all + others, and that can be called text data. It comprises information + related to the grouping of glyphs together to form text. Simple + examples are the kerning table, which controls the spacing between + adjacent glyphs, as well as some of the extensions introduced in + TrueType Open, OpenType, and TrueType GX like glyph substitution + (ligatures, vertical representations), baseline management, + justification, etc. + + This article focuses on the basic TrueType tables, and hence, will only + talk about kerning, as FreeType doesn't support OpenType nor GX (yet). + [Support for TrueType Open is already partially available.] + + ------------------------------------------------------------------------ + +II. Glyph Outlines + +TrueType is a scalable font format; it is thus possible to render glyphs at +any scale, and under any affine transform, from a single source +representation. However, simply scaling vectorial shapes exhibits at small +sizes (where `small' refers here to anything smaller than at least +150 pixels) a collection of un-harmonious artifacts, like widths and/or +heights degradations. + +Because of this, the format also provides a complete programming language +used to design small programs associated to each glyph. Its role is to align +the point positions on the pixel grid after the scaling. This operation is +hence called grid-fitting, or even hinting. + + 1. Vectorial representation + + The source format of outlines is a collection of closed paths called + contours. Each contour delimits an outer or inner region of the glyph, + and can be made of either line segments and/or second-order beziers + (also called conic beziers or quadratics). + + It is described internally as a series of successive points, with each + point having an associated flag indicating whether it is `on' or `off' + the curve. These rules are applied to decompose the contour: + + o Two successive `on' points indicate a line segment joining them. + + o One `off' point amidst two `on' points indicates a conic bezier, + the `off' point being the control point, and the `on' ones the + start and end points. + + o Finally, two successive `off' points forces the rasterizer to + create (only during bitmap rendering) a virtual `on' point amidst + them, at their exact middle. This greatly facilitates the + definition of successive Bezier arcs. + + * # on + * off + __---__ + #-__ _-- -_ + --__ _- - + --__ # \ + --__ # + -# + Two `on' points + Two `on' points and one `off' point + between them + + * + # __ Two `on' points with two `off' + \ - - points between them. The point + \ / \ marked `0' is the middle of the + - 0 \ `off' points, and is a `virtual + -_ _- # on' point where the curve passes. + -- It does not appear in the point + list. + * + + Each glyph's original outline points are located on a grid of + indivisible units. The points are stored in the font file as + 16-bit integer grid coordinates, with the grid origin's being at (0,0); + they thus range from -16384 to 16383. + + In creating the glyph outlines, a type designer uses an imaginary + square called the EM square. Typically, the EM square encloses the + capital letter `M' and most other letters of a typical roman alphabet. + The square's size, i.e., the number of grid units on its sides, is very + important for two reasons: + + o It is the reference used to scale the outlines to a given + instance. For example, a size of 12pt at 300x300dpi corresponds to + 12*300/72 = 50 pixels. This is the size the EM square would appear + on the output device if it was rendered directly. In other words, + scaling from grid units to pixels uses the formula + + pixel_size = point_size * resolution / 72 + + pixel_coordinate = grid_coordinate * pixel_size / EM_size + + o The greater the EM size is, the larger resolution the designer can + use when digitizing outlines. For example, in the extreme example + of an EM size of 4 units, there are only 25 point positions + available within the EM square which is clearly not enough. + Typical TrueType fonts use an EM size of 2048 units (note: with + Type 1 PostScript fonts, the EM size is fixed to 1000 grid units. + However, point coordinates can be expressed in floating values). + + Note that glyphs can freely extend beyond the EM square if the font + designer wants this. The EM is used as a convenience, and is a valuable + convenience from traditional typography. + + Grid units are very often called font units or EM units. + + ----------------------------------------------------------------------- + IMPORTANT NOTE: + + Under FreeType, scaled pixel positions are all expressed in the 26.6 + fixed float format (made of a 26-bit integer mantissa, and a 6-bit + fractional part). In other words, all coordinates are multiplied by 64. + The grid lines along the integer pixel positions, are multiples of 64, + like (0,0), (64,0), (0,64), (128,128), etc., while the pixel centers + lie at middle coordinates (32 modulo 64) like (32,32), (96,32), etc. + ----------------------------------------------------------------------- + + 2. Hinting and Bitmap rendering + + As said before, simply scaling outlines to a specific instance always + creates undesirable artifacts, like stems of different widths or + heights in letters like `E' or `H'. Proper glyph rendering needs that + the scaled points are aligned along the pixel grid (hence the name + grid-fitting), and that important widths and heights are respected + throughout the whole font (for example, it is very often desirable that + the letters `I' and `T' have their central vertical line of the same + pixel width). + + Type 1 PostScript font files include with each glyph a small series of + distances called hints, which are later used by the type manager to try + grid-fitting the outlines as cleverly as possible. On one hand, it has + the consequence that upgrading your font engine can enhance the visual + aspects of all fonts of your system; on the other hand, the quality of + even the best version of Adobe's Type Manager isn't always very + pleasing at small sizes (notwithstanding font smoothing). + + TrueType takes a radically different approach: Each glyph has an + associated `program', designed in a specific geometrical language, + which is used to align explicitly each outline point to the pixel grid, + preserving important distances and metrics. A stack-based low-level + bytecode is used to store it in the font file, and is interpreted later + when rendering the scaled glyphs. + + This means that even very complex glyphs can be rendered perfectly at + very small sizes, as long as the corresponding glyph code is designed + correctly. Moreover, a glyph can loose some of its details, like + serifs, at small sizes to become more readable, because the bytecode + provides interesting features. + + However, this also have the sad implication that an ill-designed glyph + code will always render junk, whatever the font engine's version, and + that it's very difficult to produce quality glyph code. There are about + 200 TrueType opcodes, and no known `high-level language' for it. Most + type artists aren't programmers at all and the only tools able to + produce quality code from vectorial representation have been + distributed to only a few font foundries, while tools available to the + public, e.g. Fontographer, are usually expensive though generating + average to mediocre glyph code. + + All this explains why an enormous number of broken or ugly `free' fonts + have appeared on the TrueType scene, and that this format is now + mistakenly thought as `crap' by many people. Funnily, these are often + the same who stare at the `beauty' of the classic `Times New Roman' and + `Arial/Helvetica' at 8 points. + + Once a glyph's code has been executed, the scan-line converter converts + the fitted outline into a bitmap (or a pixmap with font-smoothing). + + ------------------------------------------------------------------------ + +III. Glyph metrics + + 1. Baseline, Pens and Layouts + + The baseline is an imaginary line that is used to `guide' glyphs when + rendering text. It can be horizontal (e.g. Roman, Cyrillic, Arabic, + etc.) or vertical (e.g. Chinese, Japanese, etc). Moreover, to render + text, a virtual point, located on the baseline, called the pen + position, is used to locate glyphs. + + Each layout uses a different convention for glyph placement: + + o With horizontal layout, glyphs simply `rest' on the baseline. Text + is rendered by incrementing the pen position, either to the right + or to the left. + + [Image] + + The distance between two successive pen positions is + glyph-specific and is called the advance width. Note that its + value is always positive, even for right-to-left oriented + alphabets, like Arabic. This introduces some differences in the + way text is rendered. + + ------------------------------------------------------------------ + IMPORTANT NOTE: + + The pen position is always placed on the baseline in TrueType, + unlike the convention used by some graphics systems, like Windows, + to always put the pen above the line, at the ascender's position. + ------------------------------------------------------------------ + + o With vertical layout, glyphs are centered around the baseline: + + [Image] + + 2. Typographic metrics and bounding boxes + + A various number of face metrics are defined for all glyphs in a given + font. Three of them have a rather curious status in the TrueType + specification; they only apply to horizontal layouts: + + o The ascent + + This is the distance from the baseline to the highest/upper grid + coordinate used to place an outline point. It is a positive value, + due to the grid's orientation with the y axis upwards. + + o The descent + + The distance from the baseline to the lowest grid coordinate used + to place an outline point. This is a negative value, due to the + grid's orientation. + + o The linegap + + The distance that must be placed between two lines of text. The + baseline-to-baseline distance should be computed as + + ascent - descent + linegap + + if you use the typographic values. + + The problem with these metrics is that they appear three times in a + single font file, each version having a slightly different meaning: + + 1. The font's horizontal header provides the ascent, descent and + linegap fields, which are used to express the designer's intents, + rather than the real values that may be computed from all glyphs + in the outline. These are used by the Macintosh font engine to + perform font mapping (i.e. font substitution). + + 2. The OS/2 table provides the usWinAscent and usWinDescent fields. + These values are computed for glyphs of the Windows ANSI charset + only, which means that they are wrong for any other glyph. Note + that usWinDescent is always positive (i.e. looks like `-descent'). + + 3. The OS/2 table provides the typoAscender, typoDescender and + typoLinegap values, which hopefully concern the whole font file. + These are the correct system-independent values! + + All metrics are expressed in font units. If you want to use any of the + two first versions of these metrics, the TrueType specification + contains some considerations and computing tips that might help you. + + Other, simpler metrics are: + + o The glyph's bounding box, also called bbox + + This is an imaginary box that encloses any glyph (usually as + tightly as possible). It is represented by four fields, namely + xMin, yMin, xMax, and yMax, that can be computed for any outline. + In FreeType, their values can be in font units (if measured in the + original outline) or in 26.6 pixel units (if measured on scaled + outlines). + + Note that if it wasn't for grid-fitting, you wouldn't need to know + a box's complete values, but only its dimensions to know how big + is a glyph outline/bitmapa. However, correct rendering of hinted + glyphs needs the preservation of important grid alignment on each + glyph translation/placement on the baseline, which is why FreeType + always returns the complete glyph outline. + + Note also that the font's header contains a global font bounding + box in font units which should enclose all glyphs in a font. This + can be used to pre-compute the maximum dimensions of any glyph at + a given instance. + + o The internal leading + + This concept comes directly from the world of traditional + typography. It represents the amount of space within the `leading' + which is reserved for glyph features that lay outside of the EM + square (like accentuation). It usually can be computed as + + internal_leading = ascent - descent - EM_size + + o The external leading + + This is another name for the linegap. + + 3. Bearings and Advances + + Each glyph has also distances called bearings and advances. Their + definition is constant, but their values depend on the layout, as the + same glyph can be used to render text either horizontally or + vertically. + + 1. The left side bearing: a.k.a. bearingX + + This is the horizontal distance from the current pen position to + the glyph's left bounding box edge. It is positive for horizontal + layouts, and most generally negative for vertical one. + + 2. The top side bearing: a.k.a. bearingY + + This is the vertical distance from the baseline to the top of the + glyph's bounding box. It is usually positive for horizontal + layouts, and negative for vertical ones + + 3. The advance width: a.k.a. advanceX + + This is the horizontal distance the pen position must be + incremented (for left-to-right writing) or decremented (for + right-to-left writing) by after each glyph is rendered when + processing text. It is always positive for horizontal layouts, and + null for vertical ones. + + 4. The advance height: a.k.a. advanceY + + This is the vertical distance the pen position must be decremented + by after each glyph is rendered. It is always null for horizontal + layouts, and positive for vertical layouts. + + 5. The glyph width + + The glyph's horizontal extent. More simply, it is (bbox.xMax - + bbox.xMin) for unscaled font coordinates. For scaled glyphs, its + computation requests specific care, described in the grid-fitting + chapter below. + + 6. The glyph height + + The glyph's vertical extent. More simply, it is (bbox.yMax - + bbox.yMin) for unscaled font coordinates. For scaled glyphs, its + computation requests specific care, described in the grid-fitting + chapter below. + + 7. The right side bearing + + Only used for horizontal layouts to describe the distance from the + bbox's right edge to the advance width. It is in most cases a + non-negative number. The FreeType library doesn't provide this + metric directly, as it isn't really part of the TrueType + specification. It can be computed simply as + + advance_width - left_side_bearing - (xMax-xMin) + + [Image] + + [Image] + + Finally, if you use `ABC widths' under Windows and OS/2, the following + relations apply: + + A = left side bearing + B = width + C = right side bearing + + A+B+C = advance width + + 4. The effects of grid-fitting + + All these metrics are stored in font units in the font file. They must + be scaled and grid-fitted properly to be used at a specific instance. + This implies several things: + + o First, a glyph program not only aligns the outline along the grid + pixel, it also processes the left side bearing and the advance + width. Other grid-fitted metrics are usually available in optional + TrueType tables if you need them. + + o A glyph program may decide to extend or stretch any of these two + metrics if it has a need for it. This means that you cannot assume + that the fitted metrics are simply equal to the scaled one plus or + minus a liberal distance < 1 pixel (i.e., less than 64 fractional + pixel units). For example, it is often necessary to stretch the + letter `m' horizontally at small pixel sizes to make all vertical + stems visible, while the same glyph can be perfectly `square' at + larger sizes. + + o Querying the fitted metrics of all glyphs at a given instance is + very slow, as it needs to load and process each glyph + independently. For this reason, some optional TrueType tables are + defined in the specification, containing pre-computed metrics for + specific instances (the most commonly used, like 8, 9, 10, 11, 12, + and 14 points at 96dpi, for example). These tables aren't always + present in a TrueType font. + + If you don't need the exact fitted value, it's much faster to + query the metrics in font units, then scale them to the instance's + dimensions. + + ----------------------------------------------------------------------- + IMPORTANT NOTE: + + Another very important consequence of grid-fitting is the fact that + moving a fitted outline by a non-integer pixel distance will simply + ruin the hinter's work, as alignments won't be preserved. The + translated glyph will then look `ugly' when converted to a bitmap! + + In other words, each time you want to translate a fitted glyph outline, + you must take care of only using integer pixel distances (the x and + y offsets must be multiples of 64, which equals to 1.0 in the 26.6 + fixed float format). If you don't care about grid-fitting (typically + when rendering rotated text), you can use any offset you want and use + sub-pixel glyph placement. + ----------------------------------------------------------------------- + + ------------------------------------------------------------------------ + +IV. Text processing + +This section demonstrates how to use the concepts previously defined to +render text, whatever the layout you use. + + 1. Writing simple text strings + + We will start by generating a simple string with a Roman alphabet. The + layout is thus horizontal, left to right. + + For now, we will assume all glyphs are rendered in a single target + bitmap. The case of generating individual glyph bitmaps, then placing + them on demand on a device is presented in a later chapter of this + section. + + Rendering the string needs to place each glyph on the baseline; this + process looks like the following: + + 1. Place the pen to the cursor position. The pen is always located on + the baseline. Its coordinates must be grid-fitted (i.e. multiples + of 64)! + + pen_x = cursor_x; + pen_y = cursor_y; + + 2. Load the glyph outline and its metrics. Using the flag + TTLOAD_DEFAULT will scale and hint the glyph: + + TT_Load_Glyph( instance, + glyph, + glyph_index, + TTLOAD_DEFAULT ); + + TT_Get_Glyph_Metrics( glyph, &metrics ); + TT_Get_Glyph_Outline( glyph, &outline ); + + 3. The loader always places the glyph outline relative to the + imaginary pen position (0,0). You thus simply need to translate + the outline by the vector: + + ( pen_x, pen_y ) + + To place it on its correct position, you can use the call + + TT_Translate_Outline( outline, pen_x, pen_y ); + + 4. Render the outline in the target bitmap, the glyph will be + surimposed on it with a binary `or' operation (FreeType never + creates glyph bitmaps by itself, it simply renders glyphs in the + arrays you pass to it. See the API reference for a complete + description of bitmaps and pixmaps). + + TT_Get_Outline_Bitmap( outline, &target_bitmap ); + + ------------------------------------------------------------------ + IMPORTANT NOTE: + + If you don't want to access the outline in your code, you can also + use the API function TT_Get_Glyph_Bitmap() which does the same as + the previous lines: + + TT_Get_Glyph_Outline( glyph, &outline ); + TT_Translate_Outline( outline, x_offset, y_offset ); + TT_Get_Outline_Bitmap( outline, &target_bitmap ); + TT_Translate_Outline( outline, -x_offset, -y_offset ); + + is equivalent to: + + TT_Get_Glyph_Bitmap( glyph, + x_offset, + y_offset, + &target_bitmap ); + + ------------------------------------------------------------------ + + 5. Now advance the pen to its next position. The advance is always + grid-fitted when the glyph was hinted: + + pen_x += metrics.advance; + + The advance being grid-fitted, the pen position remains aligned on + the grid. + + 6. Start over on item 2 until string completion. That's it! + + 2. Writing right-to-left and vertical text + + Generating strings for different layouts is very similar. Here are the + most important differences. + + o For right-to-left text (like Arabic) + + The main difference here is that, as the advance width and left + side bearings are oriented against the flow of text, the pen + position must be decremented by the advance width, before placing + and rendering the glyph. Other than that, the rest is strictly + similar. + + o For vertical text (like Chinese or Japanese) + + In this case, the baseline is vertical, which means that the pen + position must be shifted in the vertical direction. You need the + vertical glyph metrics to do that (using the + TT_Get_Big_Glyph_Metrics() function). + + Once you get these, the rest of the process is very similar. The + glyph outline is placed relative to an imaginary origin of (0,0), + and you should translate it to the pen position before rendering + it. + + The big difference is that you must decrement pen_y, rather than + increment pen_x (this is for the TrueType convention of y oriented + upwards). + + pen_y -= metrics.advance; + + 3. Generating individual glyph bitmaps and using them to render text + + Loading each glyph when rendering text is slow, and it's much more + efficient to render each one in a standalone bitmap to place it in a + cache. Text can then be rendered fast by applying simple blit + operations on the target device. + + To be able to render text correctly with the bitmaps, you must record + and associate with them its fitted bearings and advances. Hence the + following process: + + 1. Generate the bitmaps. + + + Load the glyph and get its metrics. + + TT_Load_Glyph( instance, + glyph, + glyph_index, + TTLOAD_DEFAULT ); + + TT_Get_Glyph_Metrics( glyph, &metrics ); + + The bbox is always fitted when calling TT_Get_Glyph_Metrics() + on a hinted glyph. You can then easily compute the glyph's + dimension in pixels as: + + width = (bbox.xMax - bbox.xMin) / 64; + height = (bbox.yMax - bbox.yMin) / 64; + + NOTE 1: + The fitted bounding box always contains all the dropouts that + may be produced by the scan-line converter. This width and + height are thus valid for all kinds of glyphs). + + NOTE 2: + If you want to compute the dimensions of a rotated outline's + bitmap, compute its bounding box with TT_Get_Outline_BBox(), + then grid-fit the bbox manually: + + #define FLOOR(x) ((x) & -64) + #define CEILING(x) (((x)+63) & -64) + + xMin = FLOOR(xMin); + yMin = FLOOR(yMin); + yMin = CEILING(xMax); + yMax = CEILING(yMax); + + then compute width and height as above. + + + Create a bitmap of the given dimension, e.g.: + + bitmap.width = width; + bitmap.cols = (width+7) & -8; + bitmap.rows = height; + bitmap.flow = TT_Flow_Up; + bitmap.size = bitmap.cols * bitmap.rows; + bitmap.buffer = malloc( bitmap.size ); + + + Render the glyph into the bitmap. + + Don't forget to shift it by (-xMin, -yMin) to fit it in the + bitmap: + + /* Note that the offsets must be grid-fitted to */ + /* preserve hinting! */ + TT_Get_Glyph_Bitmap( glyph, + &bitmap, + -bbox.xMin, + -bbox.yMin ); + + 2. Store the bitmap with the following values: + + bearingX / 64 = left side bearing in pixels + advance / 64 = advance width/height in pixels + + When your cache is set up, you can then render text using a scheme + similar to the ones describe in 1. and 2., with the exception that + now pen positions and metrics are expressed in pixel values. We + are done! + + pen_x = cursor_x; + pen_y = cursor_y; + + while ( glyph_to_render ) + { + access_cache( glyph_index, metrics, bitmap ); + + blit_bitmap_to_position + ( pen_x + bearingX, + pen_y (+ bearingY depending on orientation ) ); + + pen_x += advance; + } + + 4. Device-independent text rendering + + The previously described rendering processes all align glyphs on the + baseline according to metrics fitted for the display's distance. In + some cases, the display isn't the final output, and placing the glyphs + in a device-independent way is more important than anything. + + A typical case is a word processor which displays text as it should + appear on paper when printed. As you've probably noticed, the glyphs + aren't always spaced uniformly on the screen as you type them, + sometimes the space between an `m' and a `t' is too small, some other + it is too large, etc. + + These differences are simply due to the fact that the word processor + aligns glyphs in an device-independent way, using original metrics in + font units to do it, then scale them as it can to display text on + screen, usually at a very smaller resolution than your printer's one. + + Device-independence is a crucial part of document portability, and it + is very saddening to see that most professional word processors don't + do it correctly. For example, MS Word uses the fitted metrics of the + printer's resolution, rather than the originals in font units. + + This is great to get sure that your text prints very well on your + printer, but it also implies that someone printing the exact same + document on a device with different output resolutions (e.g. bubble-jet + vs. laser printers) may encounter trouble. + + As the differences in advances accumulate on one line, they can sum to + the width of one or more glyphs in extreme cases, which is enough to + `overflow' the automatic justification algorithm. This may add + additional lines of printed text, or even remove some. Moreover, + supplemental lines can produce unexpected page breaks and `blank' + pages. This can be extremely painful when working with large documents, + as this `feature' may require you to redesign completely your + formatting to re-print it. + + In conclusion, if you want portable document rendering, never hesitate + to use and apply device-independent terms! For example, a simple way to + produce text would be: + + 1. Get a scale to convert from your device-independent units to 26.6 + pixels. + + 2. Get another scale to convert from original font units to + device-independent units. + + 3. Perform pen placement and advances in device-independent units. + + 4. To render each glyph, compute the pen's rounded position, as well + as the rounded glyph left side bearing, both expressed in 26.6 + pixels (don't use the fitted metrics). You will then be able to + place the glyph and/or blit its bitmap. + + 5. Kerning glyphs + + An interesting effect that most people appreciate is kerning. It + consists of modifying the spacing between two successive glyphs + according to their outlines. For example, the letters `T' and a `y' can + be easily moved closer, as the top of the `y' fits nicely under the + `T's upper right bar. + + To perform kerning, the TrueType specification provides a specific + table (its tag being `kern'), with several storage formats. This + section doesn't explain how to access this information; however, you + can have a look at the standard extension called `ttkern.h' which comes + with FreeType. + + The kerning distance between two glyphs is a value expressed in font + units which indicates whether their outline can be moved together or + apart when one follows the other. The distance isn't reflexive, which + means that the kerning for the glyph pair (`T',`y') isn't the same as + the one for (`y',`T'). + + The value is positive when the glyphs must be moved apart, and negative + when they must be moved closer. You can implement kerning simply by + adding its scaled and rounded value to the advance width when moving + the pen position. Here an example for horizontal kerning: + + #define ROUND( x ) ( (x + 32) & -64 ) + + scaled_kerning = kerning * imetrics.x_scale / 0x10000; + + pen_x += metrics.advance + ROUND( scaled_kerning ); + + 6. Rotated and stretched/slanted text + + In order to produce rotated glyphs with FreeType, one must understand a + few things: + + o The engine doesn't apply specific transformations to the glyphs it + loads and processes (other than the simpler resolution-base + scaling and grid-fitting). If you want to rotate glyphs, you will + have to load their outline, then apply the geometric + transformations that please you (a number of APIs are there to + help you to do it easily). + + o Even if the glyph loader hints `straight' glyphs, it is possible + to inform the font and glyph programs that you're going to later + transform the resulting outlines. Two flags can be passed to the + bytecode interpreter: + + + The `rotated' flag indicates that you are going to rotate the + glyphs in a non-trivial direction (i.e., on neither of the + two coordinate axis). You are advised not to set it when + writing 90 degrees-rotated text for example. + + + The `stretched' flag indicates that you are going to apply a + transformation that will distort distances. While rotations + and symmetries keep distances constant, slanting and + stretching do modify them. + + These flags can be interpreted by the glyph code to toggle certain + processings which vary from one font to the other. However, most of the + TrueType fonts that were tested with FreeType, if not all of them, + simply change the dropout-mode when any of these flags is set, and/or + disable hinting when rotation is detected. We advise you to never set + these flags, even when rotating text. For what it's worth, hinted + rotated text is no uglier than un-hinted one. + + You can use the function TT_Set_Instance_Transform_Flags() to set them. + Then, rendering can be done with the following calls: + + /* set the flags */ + TT_Set_Instance_Transforms( instance, + rotated, + stretched ); + + /* load a given glyph */ + TT_Get_Glyph_Outline( instance, + glyph, + index, + TTLOAD_DEFAULT ); + + /* access its outline */ + TT_Get_Glyph_Outline( instance, &outline ); + + /* in order to transform it */ + TT_Transform_Outline( outline, &matrix ); + /* and/or */ + TT_Translate_Outline( outline, + x_offset, y_offset ); + + /* to render it */ + TT_Get_Outline_Bitmap( outline, &bitmap ); + + Here is an example, assuming that the following variables + + TT_Matrix matrix; /* 2x2 matrix */ + TT_Pos x_off, y_off; /* corrective offsets */ + + define a transformation that can be correctly applied to a glyph + outline which have been previously placed relative to the imaginary + point position (0,0) with bearings preserved. Rendering text can now be + done as follows: + + 1. Initialize the pen position; when rotating, it is extremely well + advised to use sub-pixel placement as you don't care about + hinting. + + pen_x = cursor_x; + pen_y = cursor_y; + + 2. Transform the glyph as needed, then translate it to the current + pen position: + + TT_Transform_Outline( outline, &matrix ); + TT_Translate_Outline( outline, + pen_x + x_off, + pen_y + y_off ); + + (Note that the transformation offsets have been included in the + translation.) + + 3. Render the bitmap, as it has now been placed correctly. + + 4. To change the pen position, transform the vector (0,advance) with + your matrix, and add it: + + vec_x = metrics.advance; + vec_y = 0; + TT_Transform_Vector( &vec_x, &vec_y, &matrix ); + pen_x += vec_x; + pen_y += vec_y; + + 5. Start over at 2. until completion. + + ----------------------------------------------------------------------- + IMPORTANT NOTE: + + Do not grid-fit the pen position before rendering your glyph when + rendering rotated text. If you do, your transformed baseline won't be + preserved on each glyph, and the text will look like it's `hopping' + randomly. This is particularly visible at small sizes. + + Sub-pixel precision placement is very important for clean rotated text. + ----------------------------------------------------------------------- + + 7. Font-smoothing, a.k.a. gray-levels rendering + + The FreeType engine's scan-line converter (the component also called + the rasterizer) is able to convert a vectorial glyph outline into + either a normal bitmap, or an 8-bit pixmap (a.k.a. colored bitmaps on + some systems). This last feature is called gray-level rendering or + font-smoothing, because it uses a user-supplied palette to produce + anti-aliased versions of the glyphs. + + Its principle is to render a bitmap which is twice as large than the + target pixmap, then simply filtering it using a 2x2 summation. + + ----------------------------------------------------------------------- + NOTE: + + FreeType's scan-line converter doesn't use or need an intermediate + second bitmap. Rather, filtering is performed in a single pass during + the sweep (see the file `raster.txt' for more information about it). + ----------------------------------------------------------------------- + + You'll notice that, as with Windows 95, FreeType's rasterizer only + grays those parts of the glyph which need it, i.e., diagonals and + curves, while keeping horizontal and vertical stems straight `black'. + This greatly improves the legibility of text, while avoiding the + `blurry' look anti-aliased fonts typically found with Adobe's Type + Manager or Acrobat. + + There are thus five available gray-levels, ranging from 0 to 4, where + level 0 and level 4 are the background and foreground colors, + respectively, and where levels 1, 2, 3 are intermediate. For example, + to render black text on a white background, one can use a palette like: + + palette[0] = white (background) + palette[1] = light gray + palette[2] = medium gray + palette[3] = dark gray + palette[4] = black (foreground) + + To set the engine's gray-level palette, simply use the API function + TT_Set_Raster_Palette() after initialization. It expects an array of + 5 chars which will be used to render the pixmaps. + + Note that the rasterizer doesn't create bitmaps or pixmaps. Rather, it + simply renders glyphs in the arrays you pass to it. The generated glyph + bitmaps are simply `or'-ed to the target (with 0 being the background + as a convention); in the case of pixmaps, pixels are simply written to + the buffer, in spans of four aligned bytes. + + ----------------------------------------------------------------------- + NOTE: + + The raster isn't able to superpose `transparent' glyphs on the target + pixmap. This means that you should always call the API functions + TT_Get_Glyph_Pixmap() and TT_Get_Outline_Pixmap() with an empty map, + and perform the superposition yourself. + + This can be more or less tricky, depending on the palette you are using + and your target graphics resolution. One of the components found in the + test directory, called `display.c', has large comments on the way it + implements it for the test programs. You are encouraged to read the + test program sources to understand how one can take advantage of font + smoothing. + + Pixmap surimposition is too system-specific a feature to be part of the + FreeType engine. Moreover, not everybody needs it! + ----------------------------------------------------------------------- + + Finally, the question of sur-imposing anti-aliased colored text on any + texture, since being even more tricky, is left as an exercise to the + reader ;-) If this topic really interests you, the FreeType mailing + list may host some helpful enthusiasts ready to answer your questions. + Who knows :-) + + 8. Other interesting text processes + + o Glyph substitution + + Substitution is used to replace one glyph by another when some + specific condition is met in the text string. Its most common + examples are ligatures (like replacing the `f' followed by `i' by + the single glyph `fi' if available in the font), as well as + positional selection as performed in the Arabic script (for those + not aware of this, each letter of the Arabic alphabet can be + written differently according to its position on words: starting, + ending, intermediate, or isolated). + + The base TrueType format doesn't define any table for glyph + substitution. However, GX, TrueType Open, and OpenType provide + (incompatible) extensions to perform it. Of course, it isn't + supported by the engine, but an extension could be easily written + to access the required tables. + + [Support for TrueType Open is already partially available.] + + o Justification + + ... + +To be continued... |