The purpose of this section is to present the way FreeType manages bitmaps and pixmaps, and how they relate to the concepts previously defined. The relationships between vectorial and pixel coordinates is explained.
1. Vectorial versus pixel coordinates
This sub-section explains the differences between vectorial and pixel coordinates. To make things clear, brackets will be used to describe pixel coordinates, e.g. [3,5], while parentheses will be used for vectorial ones, e.g. (-2,3.5).
In the pixel case, as we use the Y upwards convention; the coordinate [0,0] always refers to the lower left pixel of a bitmap, while coordinate [width-1, rows-1] to its upper right pixel.
In the vectorial case, point coordinates are expressed in floating units, like (1.25, -2.3). Such a position doesn't refer to a given pixel, but simply to an immaterial point in the 2D plane.
The pixels themselves are indeed square boxes of the 2D plane, whose centers lie in half pixel coordinates. For example, the lower left pixel of a bitmap is delimited by the square (0,0)-(1,1), its center being at location (0.5,0.5).
This introduces some differences when computing distances. For example, the length in pixels of the line [0,0]-[10,0] is 11. However, the vectorial distance between (0,0)-(10,0) covers exactly 10 pixel centers, hence its length is 10.
2. FreeType bitmap and pixmap descriptor
A bitmap or pixmap is described through a single structure, called FT_Bitmap, defined in the file <freetype/ftimage.h>. It is a simple descriptor whose fields are:
Note that the sign of the pitch fields determines whether the rows in the pixel buffer are stored in ascending or descending order.
Remember that FreeType uses the Y upwards convention in the 2D plane, which means that a coordinate of (0,0) always refer to the lower-left corner of a bitmap.
If the pitch is positive, the rows are stored in decreasing vertical position; the first bytes of the pixel buffer are part of the upper bitmap row.
On the opposite, if the pitch is negative, the first bytes of the pixel buffer are part of the lower bitmap row.
In all cases, one can see the pitch as the byte increment needed to skip to the next lower scanline in a given bitmap buffer.
The "positive pitch" convention is very often used, though some systems might need the other.
3. Converting outlines into bitmaps and pixmaps
Generating a bitmap or pixmap image from a vectorial image is easy with FreeType. However, one must understand a few points regarding the positioning of the outline in the 2D plane before converting it to a bitmap:
A common mistake made by many developers when they begin using FreeType is believing that a loaded outline can be directly rendered in a bitmap of adequate dimensions. The following images illustrate why this is a problem.
Indeed, in nearly all cases, the loaded or transformed outline must be translated before it is rendered into a target bitmap, in order to adjust its position relative to the target window.
For example, the correct way of creating a standalone glyph bitmap is as follows
In the case where one wants to write glyph images directly into a large bitmap, the outlines must be translated so that their vectorial position correspond to the current text cursor/character origin.