2000-11-10 18:10:14 +01:00
|
|
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
|
|
|
|
|
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
2000-11-09 01:01:38 +01:00
|
|
|
<html>
|
|
|
|
|
<head>
|
2000-11-10 18:10:14 +01:00
|
|
|
<meta http-equiv="Content-Type"
|
|
|
|
|
content="text/html; charset=iso-8859-1">
|
|
|
|
|
<meta name="Author"
|
|
|
|
|
content="David Turner">
|
|
|
|
|
<title>FreeType Glyph Conventions</title>
|
2000-11-09 01:01:38 +01:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body text="#000000"
|
|
|
|
|
bgcolor="#FFFFFF"
|
|
|
|
|
link="#0000EF"
|
|
|
|
|
vlink="#51188E"
|
|
|
|
|
alink="#FF0000">
|
|
|
|
|
|
2000-11-10 18:10:14 +01:00
|
|
|
<h1 align=center>
|
|
|
|
|
FreeType Glyph Conventions
|
|
|
|
|
</h1>
|
2000-11-09 01:01:38 +01:00
|
|
|
|
2000-11-10 18:10:14 +01:00
|
|
|
<h2 align=center>
|
|
|
|
|
Version 2.1
|
|
|
|
|
</h2>
|
2000-11-09 01:01:38 +01:00
|
|
|
|
2000-11-10 18:10:14 +01:00
|
|
|
<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>
|
2000-11-09 01:01:38 +01:00
|
|
|
|
2000-11-10 18:10:14 +01:00
|
|
|
<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
|
2000-11-10 23:39:21 +01:00
|
|
|
example, the <em>length</em> in pixels of the line [0,0]-[10,0] is 11.
|
2000-11-10 18:10:14 +01:00
|
|
|
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>
|
2001-01-19 04:33:30 +01:00
|
|
|
this is only used for "gray" pixel modes; it gives the number of
|
2000-11-10 18:10:14 +01:00
|
|
|
gray levels used to describe the anti-aliased gray levels --
|
2001-01-19 04:33:30 +01:00
|
|
|
FreeType 2 defaults to 256 grays.
|
2000-11-10 18:10:14 +01:00
|
|
|
</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>
|
2000-11-09 01:01:38 +01:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
