Bitmap and Pixmap generation with FreeType
------------------------------------------
Table of Contents
Introduction
I. The rasterizer component
II. Bitmap & pixmap descriptors
III. Rendering an outline
IV. Anti-aliasing palette and other concerns
Conclusion
Introduction
------------
This document describes the steps that are needed to render a
glyph outline into a bitmap or a pixmap with the FreeType library.
It contains several important details needed to generate bitmaps
correctly in all situations, including if an outline has been
transformed or translated.
--------------------------------------------------------------------
I. The rasterizer component
---------------------------
In FreeType, the component in charge of performing bitmap and
pixmap rendering is called the `rasterizer'. Generation is
performed through a traditional process called `scan-line
conversion', but exhibits certain properties:
- The rasterizer doesn't allocate bitmaps:
In fact, it is only able to render an outline into an existing
bitmap or pixmap, which is passed to one of its rendering
functions. This means that the target bitmap/pixmap must be set
up correctly by the caller to achieve desired results. Setting
up bitmap and pixmap descriptors is explained in section II.
- It is able to render anti-aliased pixmaps directly:
This is unlike other graphics packages, which render to a
`large' bitmap which is then filtered down. Putting the
anti-aliasing logic within the rasterizer improves performance
and reduces memory usage, as well as lets us use better
algorithms which couldn't work in a `two-phase' process.
The rasterizer is located in the files `ttraster.h' and
`ttraster.c' (or `ttraster.pas' for the Pascal version --
unfortunately, this is severely out of date).
The format of outlines isn't important for most developers and
won't be discussed here. However, a few conventions must be
explained regarding the vector outlines:
1. Units
All point coordinates within an outline are stored in 32-bit
fractional pixel values, using the 26.6 fixed float format
(which uses 26 bits for the integer part, and 6 bits for the
fractional part). The following table gives some examples of
real versus 26.6 coordinates:
-----------------------------------------
real real coord 26.6 coord
coord. * 2^6
-----------------------------------------
0 0*64 = 0.0 0
2.4 2.4*64 = 153.6 154
3 3*64 = 192.0 192
-1.7 -1.7*64 = -108.8 -109
As you can see, conversion is relatively simple -- basically a
multiplication by 64.
In order to differentiate coordinates expressed in real or 26.6
systems, we'll use in the following lines brackets (`[' and `]')
for real coordinates, and simple parentheses (`(' and `)') for
fractional coordinates so that
[1.0,2.5] equals (64,160)
[0,0] equals (0,0)
[-2,3] equals (-128,192)
2. Orientation
The rasterizer uses the traditional convention of an X axis
oriented from left to right, and of a Y axis oriented from
bottom to top.
^ Y
|
|
|
-*-----> X
|
You've probably already used it at school when doing math :-)
Though the orientation of bitmap lines has the opposite
direction on nearly all graphics systems, the former convention
is the _right_ one when it comes to vector graphics. The reason
is simply that for managing angles and vector cross-products
resp. orientations in complex algorithms, a single convention,
used in math as well as computing alike solves many headaches.
And due to education, most people expect a 45 degrees angle to
be in the top right quadrant, at coordinate (1,1).
3. Pixels and the grid
In a vector outline, a point is immaterial and has no size or
width, just like in usual geometry. A `pixel' is an element of
a computer image called a `map' (like a bitmap or a pixmap).
The FreeType rasterizer follows the convention defined by the
TrueType specification regarding pixel placement:
- The map can be seen as a `grid' placed in the vector plane.
The grid lines are set on integer real coordinates (i.e., on
multiples of 64 in 26.6 fractional notation).
Each pixel is one `cell' of the grid, and can be `lit' with
any color. Hence, each pixel has a width and a height of
[1.0] units, (i.e., 64 fixed float units).
^ Y
|
| The pixel grid with two
| points (not pixels!)
+-----+-----+-----+-----+-----+ at coordinates [0,0]
| | | | | | and [2,2].
| | | | | |
| | | | |[2,2]|
+-----+-----+-----+-----@-----+ The pixels are the
| | |11111|22222| | grid's cells, and this
| | |11111|22222| | example show the four
| | |11111|22222| | pixels enclosed within
+-----+-----+-----+-----+-----+ the rectangle delimited
| | |33333|44444| | by these two points.
| | |33333|44444| |
| | |33333|44444| |
--+-----+-----@-----+-----+-----+----> X
| | |[0,0]| | |
| | | | | | Note that the numbering
| | | | | | of pixels isn't
+-----+-----+-----+-----+-----+ meaningful here, it's
| | | | | | only used to distinguish
| | | | | | them.
| | | | | |
+-----+-----+-----+-----+-----+
|
|
- The `center' of each pixel is always located on a
`half-integer' coordinate, i.e., at -1.5, -0.5, 0.5, 1.5, etc.
- When drawing a shape, the rasterizer only `lits' a pixel when
its center is placed _within_ the shape. This is important
because an outline point may not be necessarily be on a grid
line.
- When a pixel center falls on the shape, the pixel is lit too.
For example, the following graphics show the `lit' pixels
corresponding to the rectangle enclosed by the points:
[-0.2, 0] and [2.4, 2.7]
^ Y As one can see, the
| newest pixels `1'
| and `2' are now lit,
| because its centers
+-----+-----+-----+-----+--[2.4,2.7] are located at
| | |11111|22222| @ | coordinates
| . | . |11.11|22.22| . | [0.5,2.5] and
| | |11111|22222| | [1.5,2.5],
+-----+-----+-----+-----+-----+ respectively.
| | |33333|44444| |
| . | . |33.33|44.44| . | Note that pixel
| | |33333|44444| | centers are
+-----+-----+-----+-----+-----+ represented with a
| | |55555|66666| | dot in the graphics.
| . | . |55.55|66.66| . |
| | |55555|66666| |
--+-----+----@+-----+-----+-----+----> X
| | [-0.2,0] | | |
| . | . | . | . | . |
| | | | | | Note also that pixel
+-----+-----+-----+-----+-----+ numbering is still
| | | | | | meaningless there.
| . | . | . | . | . |
| | | | | |
+-----+-----+-----+-----+-----+
|
|
4. Drop-out control
Sometimes, a stroke is too thin to even contain a single pixel
center. This results in `lost continuity' in the resulting
bitmap, i.e., some unpleasant `holes' or `breaks' in the
rendered shape, which are called a `drop-out'.
Because a glyph representation uses curves (Bezier arcs), this
case is not easily controllable during the `hinting' of glyph
outlines by the font driver, which means that the rasterizer
must be able to correct these `artefacts'.
This processing is called `drop-out control', and can be
performed in several modes, defined by the TrueType
specification, and which details do not belong to this document.
However, the important idea is that, in _some_ cases, a pixel
may be lit even if its center isn't part of the shape.
This case is relatively rare, but is mentioned because it has
consequences of the rendering of maps. More precisely, in the
way an outline's extent is computed (see below).
--------------------------------------------------------------------
II. Bitmap and pixmap descriptors
---------------------------------
The Freetype rasterizer only supports bitmaps and 8-bit pixmaps.
In order to render an outline, a map descriptor must be sent to
its rendering functions, along with a vectorial outline.
1. Bitmap properties
This section explains how to set up a bitmap descriptor, and how
vector coordinates in the outline plane relate to pixel
positions within the bitmap buffer.
A bitmap's `raw data' is made of a simple bit buffer where each
bit corresponds to a monochrome pixel. For the sake of
simplicity, the FreeType rasterizer uses the following
conventions to store bitmaps in a buffer:
- The value 0 is used for `unlit' pixels, usually the
`background' when rendering text. Hence 1 is used for `lit'.
- Lines are padded to 8 bits, i.e. bytes. A bitmap row thus
takes an integral number of bytes in its buffer. No further
alignment is required.
(Some systems compress bitmaps by _not_ padding bit rows to
byte boundaries. It is not possible to render into such a
bitmap buffer with FreeType.)
- In a bitmap buffer byte, the left-most pixel is represented by
the most significant bit (i.e., 0x80).
The opposite convention is not supported by the FreeType
rasterizer, though it may possibly be implemented too if this
ever comes useful (ask the developers -- for now, nobody did).
- Increasing offsets within a row correspond to right-most
positions in the bitmap (i.e., byte 1 contains the
8 bits/pixels that are located on the right of the
8 bits/pixels of byte 0).
- A bitmap can be oriented in two ways:
o If increasing row addresses within the buffer correspond to
lower vertical lines, the bitmap is said to go `down'. This
is, for example, the case of nearly all video RAMs.
o If increasing row addresses within the buffer correspond to
higher vertical lines, the bitmap is said to go `up'. This
is the case, for example, for OS/2 bitmaps.
The `direction' of a bitmap is called `flow' to avoid any
confusion. In both cases, the rasterizer ALWAYS matches the
vector coordinate (0,0) with the lower-left corner of the
*lower-left* pixel in the bitmap.
The following graphics illustrate these ideas:
Y ^
| A `down-flow' bitmap.
+--+--+--+--+--+--+--+--+ On the left is each
| | | | | | | | | row's number and its
0: 0 | | | | | | | | | offset in the bitmap
+--+--+--+--+--+--+--+--+ buffer (where `w' is
| | | | | | | | | the width, in bytes,
1: w | | | | | | | | | of a single bitmap
+--+--+--+--+--+--+--+--+ row). Note that the
| | | | | | | | | origin is located at
2: 2*w | | | | | | | | | the lower left, i.e.,
+--+--+--+--+--+--+--+--+ near the leftmost bit
| | | | | | | | | of the last bitmap
3: 3*w | | | | | | | | | row.
-@--+--+--+--+--+--+--+-----> X
|[0,0]
Y ^
| An `up-flow' bitmap.
+--+--+--+--+--+--+--+--+ On the left is each
| | | | | | | | | row's number and its
3: 3*w | | | | | | | | | offset in the bitmap
+--+--+--+--+--+--+--+--+ buffer (where `w' is
| | | | | | | | | the width, in bytes,
2: 2*w | | | | | | | | | of a single bitmap
+--+--+--+--+--+--+--+--+ row). Note that the
| | | | | | | | | origin is located at
1: w | | | | | | | | | the lower left, i.e.,
+--+--+--+--+--+--+--+--+ near the first bit in
| | | | | | | | | the buffer.
0: 0 | | | | | | | | | The first buffer bit
-@--+--+--+--+--+--+--+-----> X corresponds to the
|[0,0] rectangle [0,0]-[1,1]
in the vector plane.
2. Bitmap descriptors
Now that you understand all these details, a bitmap can be
described to the rasterizer engine through a map, which
structure must be set up by client application:
struct TT_Raster_Map_
{
int rows; /* number of rows */
int cols; /* number of columns (bytes) per row */
int width; /* number of pixels per line */
int flow; /* bitmap orientation */
void* bitmap; /* bit/pixmap buffer */
long size; /* bit/pixmap size in bytes */
};
typedef struct TT_Raster_Map_ TT_Raster_Map;
where the fields stand for:
rows:
The number of rows within the bitmap buffer.
cols:
The number of columns, i.e. bytes per row within the
buffer. It corresponds to the `w' value used in the above
graphics.
width:
The number of pixels (i.e. bits) per row in the buffer. The
rasterizer always clips its rendering to the bit width
specified in this field, even if the `cols' fields
corresponds to a larger width.
flow:
The bitmap flow. Use the constants TT_Flow_Up and
TT_Flow_Down exclusively for this field.
bitmap:
A typeless pointer to the bit buffer.
size:
The total size of the bit buffer in bytes. This is not used
directly by the rasterizer, so applications can use it.
Note that the `cols' field should always be bigger than the
value of `width' multiplied by 8. The rasterizer clips the
generated bitmap to the `width' first bits in a row.
Note also that it is of course allowed to create, for example, a
Windows or X11 bitmap through a normal system-specific API call,
using a TT_Raster_Map that describes it to the rasterizer. It
is thus possible to draw directly into such OS specific
structures.
IMPORTANT: *****************************************************
When rendering a bitmap, the rasterizer always OR-es the shape
on the target bitmap. It is thus possible to draw several
shapes into a single surface which successive calls to the
render functions.
****************************************************************
3. Pixmap properties
The rasterizer only supports 8-bit pixmaps, where one pixel is
represented by a single byte. They must conform to the
following rules:
- A 5-entries palette is used to generate an outline's pixmap in
the buffer. They correspond to:
palette[0] -> background
palette[1] -> `light'
palette[2] -> `medium'
palette[3] -> `dark'
palette[4] -> foreground
where the terms `light', `medium', and `dark' correspond to
intermediate values between the first (background) and last
(foreground) entry.
The upcoming FreeType 2.0 will feature an additional
anti-aliasing logic with a 17-entries palette.
- Lines are padded to 32 bits, i.e. 4 bytes. A pixmap row thus
takes a multiple of 4 bytes in its buffer.
- Increasing offsets within a row correspond to right-most
positions in the bitmap (i.e., byte/pixel 1 is to the right of
byte/pixel 0).
- A pixmap can be oriented in two ways, following the same rules
as a bitmap regarding its flow.
IMPORTANT: *****************************************************
In order to improve performance when rendering large outlines
with anti-aliasing, the rasterizer draws pixels in runs of
4-bytes ONLY when at least one of their `colour' isn't 0
(background).
This means that you should ALWAYS CLEAR the pixmap buffer before
calling the rendering function, you may otherwise experience
ugly artefacts, which are possibly left from a previous
rendering!
In general, it is not possible to do colour compositing with the
FreeType rasterizer (compositing is if you want to superpose a
transparent coloured layer on top of an image). This is mainly
due to the fact that:
- There are too many pixel formats to support.
- There is not a single portable way to do it anyway.
- It really is a graphics processing question, not one that
should be solved by a text rendering engine.
****************************************************************
4. Pixmap descriptors
Pixmaps use the same descriptor structure as bitmaps, with a few
differences in interpretation:
- The `cols' field is used to indicate the number of _bytes_ in
a pixmap row. It must thus be a multiple of 4!
- The rasterizer clips the outline to the first `width'
pixels/width within each buffer row.
As usual, it should be possible to use a system-specific pixmap
and render directly into it, as long as you set up a descriptor
for it.
-------------------------------------------------------------------------
III. Rendering an outline
-------------------------
Now that you understand how the rasterizer sees the target bitmaps
and pixmaps it renders to, this section will explain how the
rendering eventually happen.
1. Outline coordinates and extents
Let's first consider the case where we're rendering text
directly into a huge single bitmap. To do that, we simply
translate each glyph outline before calling the rasterizer.
Here the roadmap:
- Vectorial coordinates [0,0] are mapped to the lower left
`corner' (in the grid) of the lower left pixel in the bitmap
(whatever its flow is).
- When the glyph loader returns an outline, the latter is placed
so that the coordinate [0,0] corresponds to the current cursor
position.
This means that:
- If we use our own cursor (cx,cy) within the bitmap during text
rendering, we must translate the outline to its position
before rendering it, e.g. with
TT_Translate_Outline( outline, cx, cy )
(and the cursor position must be incremented after rendering
each glyph).
- Before translation (i.e., when it is returned by the glyph
loader), the glyph outline doesn't necessarily lie on any of
the coordinate axes, nor is it limited to the first quadrant
(i.e., x>0 and y>0 is not true in general).
Its extent can be computed with the function
TT_Get_Outline_BBox(), which returns the minimum and maximum
values of its X and Y point coordinates (in 26.6 format, of
course).
2. Computing an outline's dimensions in pixels
In many cases, however, it is much better to render individual
glyph bitmaps, then cache them with appropriate metrics in order
to render text much more quickly at a given point size.
To be able to render the smallest possible bitmap, the exact
outline's extent dimensions in pixel are required. Again a
roadmap:
- Get the outline's bounding box in vector coordinates:
Simply call the TT_Get_Outline_BBox() function which will
return the values of xMin, yMin, xMax, and yMax in vector
(i.e. fractional) coordinates.
- Grid-fit the bounding box:
Because of the way pixels are lit in the bitmaps relative to
the position of their `centers' within the shape (see
section I), it is necessary to align the values of xMin, xMax,
yMin, and yMax to the pixel grid in order to compute the width
and height of the resulting bitmap. This can be done with:
xMin = FLOOR ( xMin ); with FLOOR(x) == (x & -64)
xMax = CEILING( xMax ); CEILING(x) == ((x+63) & -64)
yMin = FLOOR ( yMin );
yMax = CEILING( yMax );
The extents in pixels can then be simply computed as:
pixel_width = (xMax - xMin) / 64;
pixel_height = (yMax - yMin) / 64;
Note that because of drop-out control, and because the
bounding box computed currently includes all Bezier control
points from the outline, the bitmap may be slightly larger
than necessary in some cases.
Some improvements are planned for FreeType 2.0; for now, you
should consider that finding the `exact' bitmap bounding box
requires to scan all `borders' to detect null columns or rows.
However, the values are right in most cases.
NOTE: It seems that in some *rare* cases, which relate to
weird drop-out control situations, the above dimensions
are not enough to store all bits from the outline (there
are one or more bits `cut' on the edge).
This being hard to study (it only appears in very poorly
hinted fonts), we leave this problem to FreeType 2.0.
- Create/setup a bitmap with the computed dimensions. DON'T
FORGET TO CLEAR ITS BUFFER TOO!
- Translate the outline to stick within the bitmap space. This
is done easily by translating it by (-xMin,-yMin), where you
should ALWAYS USE THE GRID-FITTED VALUES computed above for
xMin and yMin:
TT_Translate_Outline( outline, -xMin, -yMin );
IMPORTANT: ***************************************************
For technical reasons, you should never translate a HINTED
outline by a non-integer vector (i.e., a vector which
coordinates aren't multiples of 64)! This would CERTAINLY
completely RUIN the delicate HINTING of the glyph, and will
result probably in pure GARBAGE at small point sizes.
Of course, if you're not interested in hinting, like when
displaying rotated text, you can ignore this rule and
translate to any position freely.
**************************************************************
- Render the bitmap (or pixmap).
DON'T FORGET TO STORE THE GRID-FITTED xMin and yMin WITH THE
BITMAP! This will allow you later to place it correctly
relative to your cursor position.
Here's some example pseudo code:
{
... load the glyph ...
TT_Outline outline;
TT_BBox bbox;
TT_Raster_Map bitmap;
/* get the outline */
TT_Get_Glyph_Outline( glyph, &outline );
/* compute its extent */
TT_Get_Outline_BBox( &outline, &bbox );
/* Grid-fit it */
bbox.xMin &= -64;
bbox.xMax = ( bbox.xMax + 63 ) & -64;
bbox.yMin &= -64;
bbox.yMax = ( bbox.yMax + 63 ) & -64;
/* compute pixel dimensions */
width = (bbox.xMax - bbox.xMin) / 64;
height = (bbox.yMax - bbox.yMin) / 64;
/* set up bitmap */
bitmap.rows = height;
bitmap.width = width;
bitmap.cols = (width + 7) / 8;
bitmap.size = bitmap.rows * bitmap.cols;
bitmap.bitmap = malloc( bitmap.size );
if ( !bitmap.bitmap )
return error_memory...
/* clear the bitmap buffer! */
memset( bitmap.bitmap, 0, bitmap.size );
/* translate outline */
TT_Translate_Outline( &outline, -bbox.xMin, -bbox.yMin );
/* render it within the bitmap */
TT_Get_Outline_Bitmap( engine, &outline, &bitmap );
/* We're done; don't forget to save bbox.xMin and */
/* bbox.yMin to adjust the bitmap position when */
/* rendering text with it */
...
}
3. The case of transformed/rotated glyphs:
You may want to apply a transformation other than a translation
to your glyph outlines before rendering them. For example, a
simple slant to synthesize italics, or a slight rotation.
In all cases, it is possible to render individual glyph bitmaps.
Just make sure to follow the same process AFTER you have
transformed you outline!
DON'T FORGET THAT YOU NEED TO RE-COMPUTE THE BBOX TO GET THE
CORRECT PIXEL DIMENSIONS AFTER A TRANSFORMATION.
--------------------------------------------------------------------
IV. Anti-aliasing palette and other concerns
When rendering pixmaps, using the TT_Get_Outline_Pixmap() or
TT_Get_Glyph_Pixmap() functions, the rasterizer uses a 5-entries
palette of 8-bit deep `colors'.
By default, this palette is set to ( 0, 1, 2, 3, 4 ), but one can
change it to suit your needs with TT_Set_Raster_Palette().
While in bitmap mode, it simply OR-es the pixel values to the
target bitmap that has been passed to TT_Get_Outline_Bitmap().
For pixmaps it simply writes directly the palette entries
corresponding to the `color' of the `lit' pixels it has computed.
This means that it is NOT POSSIBLE to render text in a single
pixmap with multiple calls to TT_Get_Outline_Pixmaps() within the
same target!
The reason is that `gray' pixels of two distinct outlines are not
`added' when they overlap (the operation called 'compositing'), as
it could be expected by applications.
The following graphic shows this effect when rendering two
overlapping anti-aliased shapes:
*** ***
.** .**
** **. **. **
.*. .*.. .*..*.
.*. + .*. = ---> ..*.
.*. ** | .*. **
** | **
**. | **.
*** | ***
|
missing black pixel after second
rendering...
There is no simple way to perform a composition within the
rasterizer. This would not be portable; moreover, it would be
extremely slow if it is too general. This operation is thus left
to client applications which can use their own system-specific API
for transparently blitting the glyph pixmaps into a surface to
form text.
NOTE:
If your system doesn't support transparent/alpha blits, you can
still have a look at the source file `freetype/test/display.c'.
It uses a large pixmap, with a special palette trick to render all
text quickly, then convert everything to `real' colors for
display.
--------------------------------------------------------------------
Conclusion
----------
We've seen how the FreeType rasterizer sees bitmaps through
descriptors, as well as the mapping which exists between the
vector coordinate space and the pixel position space.
You should now be able to render outlines into bitmaps and pixmaps
while applying transformations like translation, slanting, or
rotation. Don't forget a few rules, however:
- Always clear the bitmap/pixmap buffer before rendering (unless
you want to render several glyphs in a single _bitmap_; it won't
work on a pixmap).
- A pixmap `cols' field, i.e. the size in bytes of each rows, must
be a multiple of 4.
- Never translate a hinted outline by a non-integer vector if you
want to preserve the hints (i.e., the vector's coordinates must
be multiples of 64).
- Finally, don't expect the rasterizer to composite transparent
`grays' for you in a single target pixmap through multiple
calls.
--- end of bitmaps.txt ---