diff --git a/docs/glyphs/glyphs-6.html b/docs/glyphs/glyphs-6.html index 30701652f..9a63e88bd 100644 --- a/docs/glyphs/glyphs-6.html +++ b/docs/glyphs/glyphs-6.html @@ -1,12 +1,13 @@ - + - - - - FreeType Glyph Conventions + + + FreeType Glyph Conventions - -

-FreeType Glyph Conventions -

- -

-version 2.1 -

- -

-Copyright 1998-2000 David Turner (david@freetype.org)
-Copyright 2000 The FreeType Development Team (devel@freetype.org) -

- -
- -
- - - -
-Previous - -Contents - -Next -
- - -

-VI. FreeType Outlines -

- -

The purpose of this section is to present the way FreeType -manages vectorial outlines, as well as the most common operations that -can be applied on them. -

- -

-1. FreeType outline description and structure : -

- -

-a. Outline curve decomposition : -

- -

An outline is described as a series of closed contours in the -2D plane. Each contour is made of a series of line segments and bezier -arcs. Depending on the file format, these can be second-order or third-order -polynomials. The former are also called quadratic or conic arcs, and they -come from the TrueType format. The latter are called cubic arcs and mostly -come from the Type1 format. -

- -

Each arc is described through a series of start, end and control points. -Each point of the outline has a specific tag which indicates wether it -is used to describe a line segment or an arc. The tags can take the -following values : -

- -
- - - - - - - - - - - - - - - - -
-

FT_Curve_Tag_On 

-		 -

Used when the point is "on" the curve. This corresponds to -start and end points of segments and arcs. The other tags specify what -is called an "off" point, i.e. one which isn't located on the contour itself, -but serves as a control point for a bezier arc.

-
-

FT_Curve_Tag_Conic

-		 -

Used for an "off" point used to control a conic bezier arc.

-
-

FT_Curve_Tag_Cubic

-		 -

Used for an "off" point used to control a cubic bezier arc.

-
- - -

The following rules are applied to decompose the contour's points into -segments and arcs : -

- -
    -
  • two successive "on" points indicate a line segment joining them.
    • - -
  • one conic "off" point amidst two "on" points indicates a conic bezier -arc, the "off" point being the control point, and the "on" ones the -start and end points.
    • - -
  • -Two successive cubic "off" points amidst two "on" points indicate a cubic -bezier arc. There must be exactly two cubic control points and two on -points for each cubic arc (using a single cubic "off" point between two -"on" points is forbidden, for example). -
    • - -
  • -finally, two successive conic "off" points forces the rasterizer to create -(during the scan-line conversion process exclusively) a virtual "on" point -amidst them, at their exact middle. This greatly facilitates the definition -of successive conic bezier arcs. Moreover, it's the way outlines are -described in the TrueType specification. -
    • -
- -


Note that it is possible to mix conic and cubic arcs in a single -contour, even though no current font driver produces such outlines. -
  - -

- - - - - - - - - - - -
-
-		 -
-
-
-		 -
-
- -

-b. Outline descriptor :

- -

A FreeType outline is described through a simple structure, -called FT_Outline, which fields are :

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

n_points

-		 -

the number of points in the outline

-
-

n_contours

-		 -

the number of contours in the outline

-
-

points

-		 -

array of point coordinates

-
-

contours

-		 -

array of contour end indices

-
-

tags

-		 -

array of point flags

-
- -

Here, points is a pointer to an array of -FT_Vector records, used to store the vectorial coordinates of each -outline point. These are expressed in 1/64th of a pixel, which is also -known as the 26.6 fixed float format. -

- -

contours is an array of point indices used to delimit -contours in the outline. For example, the first contour always starts at -point 0, and ends a point contours[0]. The second contour -starts at point "contours[0]+1" and ends at -contours[1], etc.. -

- -

Note that each contour is closed, and that n_points -should be equal to "contours[n_contours-1]+1" for a valid -outline. -

- -

Finally, tags is an array of bytes, used to store each -outline point's tag. -

- - -

-2. Bounding and control box computations : -

- -

A bounding box (also called "bbox") is simply -the smallest possible rectangle that encloses the shape of a given outline. -Because of the way arcs are defined, bezier control points are not -necessarily contained within an outline's bounding box. -

- -

This situation happens when one bezier arc is, for example, the upper -edge of an outline and an off point happens to be above the bbox. However, -it is very rare in the case of character outlines because most font designers -and creation tools always place on points at the extrema of each curved -edges, as it makes hinting much easier. -

- -

We thus define the control box (a.k.a. the "cbox") as -the smallest possible rectangle that encloses all points of a given outline -(including its off points). Clearly, it always includes the bbox, and equates -it in most cases. -

- -

Unlike the bbox, the cbox is also much faster to compute.

- -
- - - - - -
- -

Control and bounding boxes can be computed automatically through the -functions FT_Get_Outline_CBox and FT_Get_Outline_BBox. -The former function is always very fast, while the latter may be -slow in the case of "outside" control points (as it needs to find the extreme -of conic and cubic arcs for "perfect" computations). If this isn't the -case, it's as fast as computing the control box. -

Note also that even though most glyph outlines have equal cbox and bbox -to ease hinting, this is not necessary the case anymore when a -transform like rotation is applied to them. -

- -

- 3. Coordinates, scaling and grid-fitting : -

- -

An outline point's vectorial coordinates are expressed in the -26.6 format, i.e. in 1/64th of a pixel, hence coordinates (1.0, -2.5) is -stored as the integer pair ( x:64, y: -192 ). -

- -

After a master glyph outline is scaled from the EM grid to the current -character dimensions, the hinter or grid-fitter is in charge of aligning -important outline points (mainly edge delimiters) to the pixel grid. Even -though this process is much too complex to be described in a few lines, -its purpose is mainly to round point positions, while trying to preserve -important properties like widths, stems, etc.. -

- -

The following operations can be used to round vectorial distances in -the 26.6 format to the grid : -

+

+ FreeType Glyph Conventions +

+ +

+ Version 2.1 +

+ +

+ Copyright 1998-2000 David Turner (david@freetype.org)
+ Copyright 2000 The FreeType Development Team (devel@freetype.org) +

-

round(x)   ==  (x+32) & -64 -
floor(x)   ==       x & --64 -
ceiling(x) ==  (x+63) & -64

- -

Once a glyph outline is grid-fitted or transformed, it often is interesting -to compute the glyph image's pixel dimensions before rendering it. To do -so, one has to consider the following : -

The scan-line converter draws all the pixels whose centers fall -inside the glyph shape. It can also detect "drop-outs", i.e. -discontinuities coming from extremely thin shape fragments, in order to -draw the "missing" pixels. These new pixels are always located at a distance -less than half of a pixel but one cannot predict easily where they'll appear -before rendering. -

This leads to the following computations : -
  -

    -
  • -compute the bbox
    • -
- -
    -
  • -grid-fit the bounding box with the following :
    • -
- -

    -

      xmin = floor( bbox.xMin ) -
      xmax = ceiling( bbox.xMax ) -
      ymin = floor( bbox.yMin ) -
      ymax = ceiling( bbox.yMax ) -

    - -
  • -return pixel dimensions, i.e. -width = (xmax - xmin)/64 and height = (ymax - ymin)/64 -
    • -
- -


By grid-fitting the bounding box, one guarantees that all the pixel -centers that are to be drawn, including those coming from drop-out -control, will be within the adjusted box. Then the -box's dimensions in pixels can be computed. -

Note also that, when translating a grid-fitted outline, -one should always use integer distances to -move an outline in the 2D plane. Otherwise, glyph edges won't be aligned -on the pixel grid anymore, and the hinter's work will be lost, producing -very -low quality bitmaps and pixmaps..

- - -
- - - -
-Previous - -Contents - -Next -
- -
+ + +
+ +
+ + + + + + +
+ Previous + + Contents + + Next +
+
+ +

+ + + +
+

+ VI. FreeType outlines +

+
+ +

The purpose of this section is to present the way FreeType manages + vectorial outlines, as well as the most common operations that can be + applied on them.

+ + +

+ 1. FreeType outline description and structure +

+ +

+ a. Outline curve decomposition +

+ +

An outline is described as a series of closed contours in the 2D + plane. Each contour is made of a series of line segments and + Bézier arcs. Depending on the file format, these can be + second-order or third-order polynomials. The former are also called + quadratic or conic arcs, and they are used in the TrueType format. + The latter are called cubic arcs and are mostly used in the + Type 1 format.

+ +

Each arc is described through a series of start, end, and control + points. Each point of the outline has a specific tag which indicates + whether it is used to describe a line segment or an arc. The tags can + take the following values:

+ +
+ + + + + + + + + + + + + + + +
+ FT_Curve_Tag_On + +

Used when the point is "on" the curve. This corresponds to + start and end points of segments and arcs. The other tags specify + what is called an "off" point, i.e. a point which isn't located on + the contour itself, but serves as a control point for a + Bézier arc.

+
+ FT_Curve_Tag_Conic + +

Used for an "off" point used to control a conic Bézier + arc.

+
+ FT_Curve_Tag_Cubic + +

Used for an "off" point used to control a cubic Bézier + arc.

+
+
+ +

The following rules are applied to decompose the contour's points + into segments and arcs:

+ +
    +
  • + Two successive "on" points indicate a line segment joining them. +
    • +
  • + One conic "off" point amidst two "on" points indicates a conic + Bézier arc, the "off" point being the control point, and + the "on" ones the start and end points. +
    • +
  • + Two successive cubic "off" points amidst two "on" points indicate + a cubic Bézier arc. There must be exactly two cubic + control points and two "on" points for each cubic arc (using a + single cubic "off" point between two "on" points is forbidden, for + example). +
    • +
  • + Finally, two successive conic "off" points forces the rasterizer + to create (during the scan-line conversion process exclusively) a + virtual "on" point amidst them, at their exact middle. This + greatly facilitates the definition of successive conic + Bézier arcs. Moreover, it is the way outlines are + described in the TrueType specification. +
    • +
+ +

Note that it is possible to mix conic and cubic arcs in a single + contour, even though no current font driver produces such + outlines.

+ +
+ + + + + + + + + +
+ segment example + + conic arc example +
+ cubic arc example + + cubic arc with virtual 'on' point +
+
+ + +

+ b. Outline descriptor +

+ +

A FreeType outline is described through a simple structure, called + FT_Outline, which fields are:

+ +
+ + + + + + + + + + + + + + + + + + + + + +
+ n_points + + the number of points in the outline +
+ n_contours + + the number of contours in the outline +
+ points + + array of point coordinates +
+ contours + + array of contour end indices +
+ tags + + array of point flags +
+
+ +

Here, points is a pointer to an array of + FT_Vector records, used to store the vectorial coordinates of + each outline point. These are expressed in 1/64th of a pixel, which + is also known as the 26.6 fixed float format.

+ +

contours is an array of point indices used to delimit + contours in the outline. For example, the first contour always starts + at point 0, and ends at point contours[0]. The second + contour starts at point contours[0]+1 and ends at + contours[1], etc.

+ +

Note that each contour is closed, and that n_points should + be equal to contours[n_contours-1]+1 for a valid outline.

+ +

Finally, tags is an array of bytes, used to store each + outline point's tag.

+ + + + + 2. Bounding and control box computations + + +

A bounding box (also called bbox) is simply a + rectangle that completely encloses the shape of a given outline. The + interesting case is the smallest bounding box possible, and in the + following we subsume this under the term "bounding box". Because of the + way arcs are defined, Bézier control points are not necessarily + contained within an outline's (smallest) bounding box.

+ +

This situation happens when one Bézier arc is, for example, + the upper edge of an outline and an "off" point happens to be above the + bbox. However, it is very rare in the case of character outlines + because most font designers and creation tools always place "on" points + at the extrema of each curved edges, as it makes hinting much + easier.

+ +

We thus define the control box (also called cbox) + as the smallest possible rectangle that encloses all points of a given + outline (including its "off" points). Clearly, it always includes the + bbox, and equates it in most cases.

+ +

Unlike the bbox, the cbox is much faster to compute.

+ +
+ + + + + +
+ a glyph with different bbox and cbox + + a glyph with identical bbox and cbox +
+
+ +

Control and bounding boxes can be computed automatically through the + functions FT_Get_Outline_CBox() and + FT_Get_Outline_BBox(). The former function is always very + fast, while the latter may be slow in the case of "outside" + control points (as it needs to find the extreme of conic and cubic arcs + for "perfect" computations). If this isn't the case, it is as fast as + computing the control box. + +

Note also that even though most glyph outlines have equal cbox and + bbox to ease hinting, this is not necessary the case anymore when a + transformation like rotation is applied to them.

+ + + +

+ 3. Coordinates, scaling and grid-fitting +

+ +

An outline point's vectorial coordinates are expressed in the + 26.6 format, i.e. in 1/64th of a pixel, hence coordinates + (1.0,-2.5) is stored as the integer pair (x:64,y:-192).

+ +

After a master glyph outline is scaled from the EM grid to the + current character dimensions, the hinter or grid-fitter is in charge of + aligning important outline points (mainly edge delimiters) to the pixel + grid. Even though this process is much too complex to be described in a + few lines, its purpose is mainly to round point positions, while trying + to preserve important properties like widths, stems, etc.

+ +

The following operations can be used to round vectorial distances in + the 26.6 format to the grid:

+ + 
+    round( x )   == ( x + 32 ) & -64
+    floor( x )   ==          x & -64
+    ceiling( x ) == ( x + 63 ) & -64
+ +

Once a glyph outline is grid-fitted or transformed, it often is + interesting to compute the glyph image's pixel dimensions before + rendering it. To do so, one has to consider the following:

+ +

The scan-line converter draws all the pixels whose centers + fall inside the glyph shape. It can also detect drop-outs, + i.e. discontinuities coming from extremely thin shape fragments, in + order to draw the "missing" pixels. These new pixels are always located + at a distance less than half of a pixel but it is not easy to predict + where they will appear before rendering.

+ +

This leads to the following computations:

+ +
    +
  • +

    compute the bbox

    +
    • +
  • +

    grid-fit the bounding box with the following:

    + + 
    +    xmin = floor( bbox.xMin )
+    xmax = ceiling( bbox.xMax )
+    ymin = floor( bbox.yMin )
+    ymax = ceiling( bbox.yMax )
    +
    • +
  • + return pixel dimensions, i.e. + + 
    +    width = (xmax - xmin)/64
    + + and + + 
    +    height = (ymax - ymin)/64
    +
    • +
+ +

By grid-fitting the bounding box, it is guaranteed that all the pixel + centers that are to be drawn, including those coming from drop-out + control, will be within the adjusted box. Then the box's + dimensions in pixels can be computed.

+ +

Note also that, when translating a grid-fitted outline, one should + always use integer distances to move an outline in the 2D + plane. Otherwise, glyph edges won't be aligned on the pixel grid + anymore, and the hinter's work will be lost, producing very low + quality bitmaps and pixmaps.

+ + +

+ +
+ + + + + + +
+ Previous + + Contents + + Next +
+
+ +
+