| <!doctype html public "-//w3c//dtd html 4.0 transitional//en" |
| "http://www.w3.org/TR/REC-html40/loose.dtd"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" |
| content="text/html; charset=iso-8859-1"> |
| <meta name="Author" |
| content="David Turner"> |
| <title>FreeType Glyph Conventions</title> |
| </head> |
| |
| <body text="#000000" |
| bgcolor="#FFFFFF" |
| link="#0000EF" |
| vlink="#51188E" |
| alink="#FF0000"> |
| |
| <h1 align=center> |
| FreeType Glyph Conventions |
| </h1> |
| |
| <h2 align=center> |
| Version 2.1 |
| </h2> |
| |
| <h3 align=center> |
| Copyright 1998-2000 David Turner (<a |
| href="mailto:david@freetype.org">david@freetype.org</a>)<br> |
| Copyright 2000 The FreeType Development Team (<a |
| href="mailto:devel@freetype.org">devel@freetype.org</a>) |
| </h3> |
| |
| <center> |
| <table width="65%"> |
| <tr><td> |
| |
| <center> |
| <table width="100%" |
| border=0 |
| cellpadding=5> |
| <tr bgcolor="#CCFFCC" |
| valign=center> |
| <td align=center |
| width="30%"> |
| <a href="glyphs-6.html">Previous</a> |
| </td> |
| <td align=center |
| width="30%"> |
| <a href="index.html">Contents</a> |
| </td> |
| <td align=center |
| width="30%"> |
| |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| <p><hr></p> |
| |
| <table width="100%"> |
| <tr bgcolor="#CCCCFF" |
| valign=center><td> |
| <h2> |
| VII. FreeType bitmaps |
| </h2> |
| </td></tr> |
| </table> |
| |
| <p>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.</p> |
| |
| |
| <a name="section-1"> |
| <h3> |
| 1. Vectorial versus pixel coordinates |
| </h3> |
| |
| <p>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).</p> |
| |
| <p>In the pixel case, as we use the <em>Y upwards</em> convention; |
| the coordinate [0,0] always refers to the <em>lower left pixel</em> of a |
| bitmap, while coordinate [width-1, rows-1] to its <em>upper right |
| pixel</em>.</p> |
| |
| <p>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.</p> |
| |
| <p>The pixels themselves are indeed <em>square boxes</em> 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).</p> |
| |
| <p>This introduces some differences when computing distances. For |
| example, the <em>length</em> 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.</p> |
| |
| <center> |
| <img src="grid_1.png" |
| height=390 width=402 |
| alt="bitmap and vector grid"> |
| </center> |
| |
| |
| <a name="section-2"> |
| <h3> |
| 2. FreeType bitmap and pixmap descriptor |
| </h3> |
| |
| <p>A bitmap or pixmap is described through a single structure, called |
| <tt>FT_Bitmap</tt>, defined in the file |
| <tt><freetype/ftimage.h></tt>. It is a simple descriptor whose |
| fields are:</p> |
| |
| <center> |
| <table cellspacing=3 |
| cellpadding=5 |
| width="80%"> |
| <caption> |
| <b><tt>FT_Bitmap</tt></b> |
| </caption> |
| |
| <tr> |
| <td valign=top> |
| <tt>rows</tt> |
| </td> |
| <td valign=top> |
| the number of rows, i.e. lines, in the bitmap |
| </td> |
| </tr> |
| |
| <tr> |
| <td valign=top> |
| <tt>width</tt> |
| </td> |
| <td valign=top> |
| the number of horizontal pixels in the bitmap |
| </td> |
| </tr> |
| |
| <tr> |
| <td valign=top> |
| <tt>pitch</tt> |
| </td> |
| <td valign=top> |
| its absolute value is the number of bytes per bitmap line; it can |
| be either positive or negative depending on the bitmap's vertical |
| orientation |
| </td> |
| </tr> |
| |
| <tr> |
| <td valign=top> |
| <tt>buffer</tt> |
| </td> |
| <td valign=top> |
| a typeless pointer to the bitmap pixel bufer |
| </td> |
| </tr> |
| |
| <tr> |
| <td valign=top> |
| <tt>pixel_mode</tt> |
| </td> |
| <td valign=top> |
| an enumeration used to describe the pixel format of the bitmap; |
| examples are <tt>ft_pixel_mode_mono</tt> for 1-bit monochrome |
| bitmaps and <tt>ft_pixel_mode_grays</tt> for 8-bit anti-aliased |
| "gray" values |
| </td> |
| </tr> |
| |
| <tr> |
| <td valign=top> |
| <tt>num_grays</tt> |
| </td> |
| <td valign=top> |
| this is only used for "gray" pixel modes, it gives the number of |
| gray levels used to describe the anti-aliased gray levels -- |
| 256 by default with FreeType 2 |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| |
| <p>Note that the sign of the <tt>pitch</tt> fields determines whether |
| the rows in the pixel buffer are stored in ascending or descending |
| order.</p> |
| |
| <p>Remember that FreeType uses the <em>Y upwards</em> convention in |
| the 2D plane, which means that a coordinate of (0,0) always refer to the |
| <em>lower-left corner</em> of a bitmap.</p> |
| |
| <p>If the pitch is positive, the rows are stored in decreasing vertical |
| position; the first bytes of the pixel buffer are part of the |
| <em>upper</em> bitmap row.</p> |
| |
| <p>On the opposite, if the pitch is negative, the first bytes of the |
| pixel buffer are part of the <em>lower</em> bitmap row.</p> |
| |
| <p>In all cases, one can see the pitch as the byte increment needed to |
| skip to the <em>next lower scanline</em> in a given bitmap buffer.</p> |
| |
| <center> |
| <table> |
| <tr> |
| <td> |
| <img src="up_flow.png" |
| height=261 width=275 |
| alt="negative 'pitch'"> |
| </td> |
| <td> |
| <img src="down_flow.png" |
| height=263 width=273 |
| alt="positive 'pitch'"> |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| <p>The "positive pitch" convention is very often used, though |
| some systems might need the other.</p> |
| |
| |
| <a name="section-3"> |
| <h3> |
| 3. Converting outlines into bitmaps and pixmaps |
| </h3> |
| |
| <p>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:</p> |
| |
| <ul> |
| <li> |
| <p>The glyph loader and hinter always places the outline in the 2D |
| plane so that (0,0) matches its character origin. This means that |
| the glyph's outline, and corresponding bounding box, can be placed |
| anywhere in the 2D plane (see the graphics in section III).</p> |
| </li> |
| <li> |
| <p>The target bitmap's area is mapped to the 2D plane, with its |
| lower left corner at (0,0). This means that a bitmap or pixmap of |
| dimensions [<tt>w,h</tt>] will be mapped to a 2D rectangle window |
| delimited by (0,0)-(<tt>w,h</tt>).</p> |
| </li> |
| <li> |
| <p>When scan-converting the outline, everything that falls within |
| the bitmap window is rendered, the rest is ignored.</p> |
| </li> |
| |
| <p>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.</p> |
| |
| <ul> |
| <li> |
| The first image shows a loaded outline in the 2D plane. |
| </li> |
| <li> |
| The second one shows the target window for a bitmap of arbitrary |
| dimensions [w,h]. |
| </li> |
| <li> |
| The third one shows the juxtaposition of the outline and window in |
| the 2D plane. |
| </li> |
| <li> |
| The last image shows what will really be rendered in the bitmap. |
| </li> |
| </ul> |
| |
| <center> |
| <img src="clipping.png" |
| height=151 width=539 |
| alt="clipping algorithm"> |
| </center> |
| </ul> |
| |
| <p>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.</p> |
| |
| <p>For example, the correct way of creating a <em>standalone</em> glyph |
| bitmap is as follows</p> |
| |
| <ul> |
| <li> |
| <p>Compute the size of the glyph bitmap. It can be computed |
| directly from the glyph metrics, or by computing its bounding box |
| (this is useful when a transformation has been applied to the |
| outline after the load, as the glyph metrics are not valid |
| anymore).</p> |
| </li> |
| <li> |
| <p>Create the bitmap with the computed dimensions. Don't forget to |
| fill the pixel buffer with the background color.</p> |
| </li> |
| <li> |
| <p>Translate the outline so that its lower left corner matches |
| (0,0). Don't forget that in order to preserve hinting, one should |
| use integer, i.e. rounded distances (of course, this isn't required |
| if preserving hinting information doesn't matter, like with rotated |
| text). Usually, this means translating with a vector |
| <tt>(-ROUND(xMin), -ROUND(yMin))</tt>.</p> |
| </li> |
| <li> |
| <p>Call the rendering function (it can be |
| <tt>FT_Outline_Render()</tt> for example).</p> |
| </li> |
| </ul> |
| |
| <p>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.</p> |
| |
| <p><hr></p> |
| |
| <center> |
| <table width="100%" |
| border=0 |
| cellpadding=5> |
| <tr bgcolor="#CCFFCC" |
| valign=center> |
| <td align=center |
| width="30%"> |
| <a href="glyphs-6.html">Previous</a> |
| </td> |
| <td align=center |
| width="30%"> |
| <a href="index.html">Contents</a> |
| </td> |
| <td align=center |
| width="30%"> |
| |
| </td> |
| </tr> |
| </table> |
| </center> |
| |
| </td></tr> |
| </table> |
| </center> |
| |
| </body> |
| </html> |
