Commit 63e3c3b529558d159b05ce3019a55897a575e8a3
2000-06-29T00:39:30
some real updates to the tutorial, more to come soon
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299
diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html
index b09b696..fb8a5b3 100644
--- a/docs/tutorial/index.html
+++ b/docs/tutorial/index.html
@@ -321,20 +321,32 @@
5. Setting the current pixel size
</h3>
- <p>A face object also holds a handle to a <em>size object</em> in its
- <tt>face->size</tt> field. The <em>size</em> object is used to model
- all information for the face that is relative to a given character
- size.</p>
-
+ <p>FreeType 2 uses "<em>size objects</em>" to model all
+ information related to a given character size for a given face.
+ For example, a size object will hold the value of certain metrics
+ like the ascender or text height, expressed in 1/64th of a pixel,
+ for a character size of 12 points.</p>
+
+ <p>When the <tt>FT_New_Face</tt> function is called (or one of its
+ cousins), it <b>automatically</b> creates a new size object for
+ the returned face. This size object is directly accessible as
+ <b><tt>face->size</tt></b>.</p>
+
+ <p><em>NOTA BENE: a single face object can deal with one or more size
+ objects at a time, however, this is something that few programmers
+ really need to do. We have thus have decided to simplify the API for
+ the most common use (i.e. one size per face), while keeping this
+ feature available through additional fuctions.</em></p>
+
<p>When a new face object is created, its size object defaults to the
- character size of 10 pixels (both horizontall and vertically) for
- scalable formats. For fixed-sizes formats, the size is more or less
- undefined, which is why you must set it before trying to load a
- glyph.</p>
+ character size of 10 pixels (both horizontally and vertically) for
+ scalable formats. For fixed-sizes formats, the size is more or less
+ undefined, which is why you must set it before trying to load a
+ glyph.</p>
<p>To do that, simply call <tt>FT_Set_Char_Size()</tt>. Here is an
- example where the character size is set to 16pt for a 300x300 dpi
- device:</p>
+ example where the character size is set to 16pt for a 300x300 dpi
+ device:</p>
<font color="blue">
<pre>
@@ -351,12 +363,15 @@
<ul>
<li>
<p>The character width and heights are specified in 1/64th of
- points.<p>
+ points. A point is a <em>physical</em> distance, equaling 1/72th
+ of an inch, it's not a pixel..<p>
</li>
<li>
<p>The horizontal and vertical device resolutions are expressed in
<em>dots-per-inch</em>, or <em>dpi</em>. You can use 72 or
- 96 dpi for display devices like the screen.</p>
+ 96 dpi for display devices like the screen. The resolution
+ is used to compute the character pixel size from the character
+ point size.</p>
</li>
<li>
<p>A value of 0 for the character width means "<em>same as
@@ -368,6 +383,10 @@
<p>Using a value of 0 for the horizontal or vertical resolution means
72 dpi, which is the default.</p>
</li>
+ <li>
+ <p>The first argument is a handle to a face object, not a size
+ object. That's normal, and must be seen as a convenience.</p>
+ </li>
</ul>
<p>This function computes the character pixel size that corresponds to
@@ -475,45 +494,62 @@
<p>The <tt>load_flags</tt> value is a set of bit flags used to
indicate some special operations. The default value
- <tt>FT_LOAD_DEFAULT</tt> is 0. The function performs the
- following:</p>
-
+ <tt>FT_LOAD_DEFAULT</tt> is 0.</p>
+
+ <p>This function will try to load the corresponding glyph image
+ from the face. Basically, this means that:</p>
+
<ul>
<li>
- <p>If there is a bitmap for the corresponding glyph and size, load
- it in the glyph slot, unless the <tt>FT_LOAD_NO_BITMAP</tt> flag
- is set. This is even <em>true</em> for scalable formats (embedded
- bitmaps are favored over outlines as they usually correspond to
- higher-quality images of the same glyph).</p>
- </li>
- <li>
- <p>If there is a glyph image in another format (e.g. a vectorial
- outline), load it in the glyph slot. Then, scale it to the
- current size, unless the <tt>FT_LOAD_NO_SCALE</tt> flag is
- set.</p>
- </li>
- <li>
- <p>If the glyph image was loaded and scaled, try to grid-fit it
- (which dramatically improves its quality) unless the flag
- <tt>FT_LOAD_NO_HINTING</tt> is set.</p>
- </li>
- <li>
- <p>If the glyph image is scalable, transform it through the
- current transform (which can be set with
- <tt>FT_Set_Transform()</tt>).</p>
- </li>
- <li>
- <p>Finally, if the <tt>FT_LOAD_RENDER</tt> flag is set, convert
- the glyph image into a bitmap. By default, this means a 1-bit
- monochrome bitmap, unless <tt>FT_LOAD_ANTI_ALIAS</tt> is set,
- in which case an 8-bit 256-gray-levels anti-aliased bitmap is
- generated.</p>
+ <p>If a bitmap is found for the corresponding glyph and pixel
+ size, it will in the slot (embedded bitmaps are always
+ favored over native image formats, because we assume that
+ they are higher-quality versions of the same image. This
+ can be ignored by using the FT_LOAD_NO_BITMAP flag)</p>
+ </li>
+
+ <li>
+ <p>Otherwise, a native image for the glyph will be loaded.
+ It will also be scaled to the current pixel size, as
+ well as hinted for certain formats like TrueType and
+ Type1.</p>
</li>
</ul>
+
+ <p>The field <tt><b>glyph->format</b></tt> describe the format
+ used to store the glyph image in the slot. If it is not
+ <tt>ft_glyph_format_bitmap</tt>, one can immediately
+ convert it to a bitmap through <tt>FT_Render_Glyph</tt>,
+ as in:</p>
- <p>There are a few others <tt>FT_LOAD_xxx</tt> flags defined. For
- more details see the <a href="#">FreeType 2 API
- Reference</a>.</p>
+ <font color="blue">
+ <pre>
+ error = FT_Render_Glyph(
+ face->glyph, /* glyph slot */
+ render_mode ); /* render mode */
+ </pre>
+ </font>
+
+ <p>The parameter <tt>render_mode</tt> is a set of bit flags used
+ to specify how to render the glyph image. Set it to 0 to render
+ a monochrome bitmap, or to <tt>ft_render_mode_antialias</tt> to
+ generate a high-quality (256 gray levels) anti-aliased bitmap
+ from the glyph image.</p>
+
+ <p>Once you have a bitmap glyph image, you can access it directly
+ through <tt><b>glyph->bitmap</b></tt> (a simple bitmap descriptor),
+ and position it through <tt><b>glyph->bitmap_left</b></tt> and
+ <tt><b>glyph->bitmap_top</b></tt>.</p>
+
+ <p>Note that <tt>bitmap_left</tt> is the horizontal distance from the
+ current pen position to the left-most border of the glyph bitmap,
+ while <tt>bitmap_top</tt> is the vertical distance from the
+ pen position (on the baseline) to the top-most border of the
+ glyph bitmap. <em>It is positive to indicate an upwards
+ distance</em>.</p>
+
+ <p>The next section will detail the content of a glyph slot and
+ how to access specific glyph information (including metrics).</p>
<h4>
c. Using other charmaps
@@ -526,25 +562,46 @@
when you create a new <tt>FT_Face</tt> object from a font file that
doesn't contain an ASCII, Latin-1, or Unicode charmap (rare
stuff).</p>
-
- <p>The fields <b><tt>face->num_charmaps</tt></b> and
- <b><tt>face->charmaps</tt></b> (notice the `s') can be used by client
- applications to check which charmaps are available in a given
- face.</p>
-
- <p><b><tt>face->charmaps</tt></b> is an array of <em>pointers</em> to
- the <tt><b>face->num_charmaps</b></tt> charmaps contained in the font
- face.</p>
-
- <p>Each charmap has a few visible fields used to describe it in more
- detail. For example, <tt><b>charmap->encoding</b></tt> is an
- enumeration type that describes the charmap with FreeType codes. One
- can also look at <tt><b>charmap->platform_id</b></tt> and
- <tt><b>charmap->encoding_id</b></tt> for more exotic needs.</p>
-
- <p>Here's an example code that looks for a Chinese Big 5 charmap,
- then selects it via <tt>FT_Set_CharMap()</tt>:</p>
+ <p>There are two ways to select a different charmap with FreeType 2.
+ The easiest is when the encoding you need already has a corresponding
+ enumeration defined in <tt><freetype/freetype.h></tt>, as
+ <tt>ft_encoding_big5</tt>. In this case, you can simply call
+ <tt>FT_Select_CharMap</tt> as in:</p>
+
+ <font color="blue"><pre>
+ error = FT_Select_CharMap(
+ face, /* target face object */
+ ft_encoding_big5 ); /* encoding.. */
+ </pre></font>
+
+ <p>Another way is to manually parse the list of charmaps for the
+ face, this is accessible through the fields
+ <tt><b>num_charmaps</b></tt> and <tt><b>charmaps</b></tt>
+ (notice the 's') of the face object. As you could expect,
+ the first is the number of charmaps in the face, while the
+ second is <em>a table of pointers to the charmaps</em>
+ embedded in the face.</p>
+
+ <p>Each charmap has a few visible fields used to describe it more
+ precisely. Mainly, one will look at
+ <tt><b>charmap->platform_id</b></tt> and
+ <tt><b>charmap->encoding_id</b></tt> that define a pair of
+ values that can be used to describe the charmap in a rather
+ generic way.</p>
+
+ <p>Each value pair corresponds to a given encoding. For example,
+ the pair (3,1) corresponds to Unicode. Their list is
+ defined in the TrueType specification but you can also use the
+ file <tt><freetype/ftnameid.h></tt> which defines several
+ helpful constants to deal with them..</p>
+
+ <p>To look for a specific encoding, you need to find a corresponding
+ value pair in the specification, then look for it in the charmaps
+ list. Don't forget that some encoding correspond to several
+ values pair (yes it's a real mess, but blame Apple and Microsoft
+ on such stupidity..). Here's some code to do it:</p>
+
<font color="blue">
<pre>
FT_CharMap found = 0;
@@ -554,7 +611,8 @@
for ( n = 0; n < face->num_charmaps; n++ )
{
charmap = face->charmaps[n];
- if ( charmap->encoding == ft_encoding_big5 )
+ if ( charmap->platform_id == my_platform_id &&
+ charmap->encoding_id == my_encoding_id )
{
found = charmap;
break;
@@ -568,9 +626,47 @@
if ( error ) { ... }</pre>
</font>
- <p>One might now call <tt>FT_Get_Char_Index()</tt> with Big 5
- character codes to retrieve glyph indices.</p>
+ <p>Once a charmap has been selected, either through
+ <tt>FT_Select_CharMap</tt> or <tt>FT_Set_CharMap</tt>,
+ it is used by all subsequent calls to
+ <tt>FT_Get_Char_Index()</tt>.</p>
+
+
+ <h4>
+ d. Glyph Transforms:
+ </h4>
+ <p>It is possible to specify an affine transformation to be applied
+ to glyph images when they're loaded. Of course, this will only
+ work for scalable (vectorial) font formats.</p>
+
+ <p>To do that, simply call <tt>FT_Set_Transform</tt>, as in:</p>
+
+ <font color="blue"><pre>
+ error = FT_Set_Transform(
+ face, /* target face object */
+ &matrix, /* pointer to 2x2 matrix */
+ &delta ); /* pointer to 2d vector */
+ </pre></font>
+
+ <p>This function will set the current transform for a given face
+ object. Its second parameter is a pointer to a simple
+ <tt>FT_Matrix</tt> structure that describes a 2x2 affine matrix.
+ The third parameter is a pointer to a <tt>FT_Vector</tt> structure
+ that describe a simple 2d vector.</p>
+
+ <p>Note that the matrix pointer can be set to NULL, (in which case
+ the identity transform will be used). Coefficients of the matrix
+ are in 16.16 fixed float units.</p>
+
+ <p>The vector pointer can also be set to NULL (in which case a delta
+ of (0,0) will be used). The vector coordinates are expressed in
+ 1/64th of a pixel (also known as 26.6 fixed floats).</p>
+
+ <p><em>NOTA BENE: The transform is applied every glyph that is loaded
+ through <tt>FT_Load_Glyph</tt>. Note that loading a glyph bitmap
+ with a non-trivial transform will produce an error..</em></p>
+
<hr>
<h3>