summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype/freetype-1.5/docs/glyphs.txt
diff options
context:
space:
mode:
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.txt999
1 files changed, 0 insertions, 999 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
deleted file mode 100644
index 239686aefea..00000000000
--- a/Build/source/libs/freetype/freetype-1.5/docs/glyphs.txt
+++ /dev/null
@@ -1,999 +0,0 @@
-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...