ref: 883df43fec1bbd2e8658693c964045072ec3044d
parent: 241e151eb2e97d01734d8f52693b404943b3a765
author: Werner Lemberg <[email protected]>
date: Mon May 29 03:30:17 EDT 2000
Completely checked and fully formatted.
--- a/docs/design/io-frames.html
+++ b/docs/design/io-frames.html
@@ -1,12 +1,12 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="Author" content="David Turner">
- <meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]">
- <title>FreeType 2 Internals - I/O Frames</title>
+ <meta http-equiv="Content-Type"
+ content="text/html; charset=iso-8859-1">
+ <meta name="Author"
+ content="David Turner">
+ <title>FreeType 2 Internals - I/O Frames</title>
</head>
-<body>
<body text="#000000"
bgcolor="#FFFFFF"
@@ -14,234 +14,328 @@
vlink="#51188E"
alink="#FF0000">
-<center>
-<h1>
-FreeType 2.0 I/O Frames</h1></center>
+<h1 align=center>
+ FreeType 2.0 I/O Frames
+</h1>
+<h3 align=center>
+ © 2000 David Turner
+ (<a href="mailto:[email protected]">[email protected]</a>)<br>
+ © 2000 The FreeType Development Team
+ (<a href="http://www.freetype.org">www.freetype.org</a>)
+</h3>
+
<center>
-<h3>
-© 2000 David Turner (<a href="mailto:[email protected]">[email protected]</a>)<br>
-© 2000 The FreeType Development Team (<a href="http://www.freetype.org">www.freetype.org</a>)</h3></center>
+<table width="70%">
+<tr><td>
-<p><br>
-<hr WIDTH="100%">
-<br>
-<h2>Introduction:</h2>
-<ul>
- This document explains the concept of i/o <b>frames</b> as used in the
- FreeType 2 source code. It also enumerates the various functions and macros
- that can be used to read them.
- <p>
- It is targetted to FreeType hackers, or more simply to developers who would
- like a better understanding of the library's source code.
-</ul>
+ <hr>
-<p><hr><p>
+ <h2>
+ Introduction
+ </h2>
-<h2>I. What frames are:</h2>
-<ul>
- Simply speaking, a frame is an array of bytes in a font file that is
- "preloaded" into memory in order to be rapidly parsed. Frames are useful to
- ensure that every "load" is checked against end-of-file overruns, and
- provides nice functions to extract data in a variety of distinct formats.
- <p>
- But an example is certainly more meaningful than anything else.
- The following code:
- <p>
- <font color="blue"><pre>
- error = read_short(stream, &str.value1);
- if (error) goto ...
+ <p>This document explains the concept of I/O <b>frames</b> as used in the
+ FreeType 2 source code. It also enumerates the various functions and
+ macros that can be used to read them.</p>
- error = read_ulong(stream, &str.value2);
- if (error) goto ...
+ <p>It is targeted to FreeType hackers, or more simply to developers who
+ would like a better understanding of the library's source code.</p>
- error = read_ulong(stream, &str.value3);
- if (error) goto ...
- </pre></font>
- can easily be replaced with:
- <p>
- <font color="blue"><pre>
- error = FT_Access_Frame(stream, 2+4+4);
- if (error) goto ...
+ <hr>
- str.value1 = FT_Get_Short(stream);
- str.value2 = FT_Get_ULong(stream);
- str.value3 = FT_Get_ULong(stream);
+ <h2>
+ I. What frames are
+ </h2>
- FT_Forget_Frame(stream);
- </pre></font>
- <p>
- Here, the call to <tt>FT_Access_Frame</tt> will:<p>
+ <p>Simply speaking, a frame is an array of bytes in a font file that is
+ "preloaded" into memory in order to be rapidly parsed. Frames are useful
+ to ensure that every "load" is checked against end-of-file overruns, and
+ provides nice functions to extract data in a variety of distinct
+ formats.</p>
+
+ <p>But an example is certainly more meaningful than anything else. The
+ following code</p>
+
+ <font color="blue">
+ <pre>
+ error = read_short( stream, &str.value1 );
+ if ( error ) goto ...
+
+ error = read_ulong( stream, &str.value2 );
+ if ( error ) goto ...
+
+ error = read_ulong( stream, &str.value3 );
+ if ( error ) goto ...</pre>
+ </font>
+
+ <p>can easily be replaced with</p>
+
+ <font color="blue">
+ <pre>
+ error = FT_Access_Frame( stream, 2 + 4 + 4 );
+ if ( error ) goto ...
+
+ str.value1 = FT_Get_Short( stream );
+ str.value2 = FT_Get_ULong( stream );
+ str.value3 = FT_Get_ULong( stream );
+
+ FT_Forget_Frame( stream );</pre>
+ </font>
+
+ <p>Here, the call to <tt>FT_Access_Frame()</tt> will</p>
+
<ul>
- <li>Ensure that there are at least 2+4+4=10 bytes left in the stream.
- <li>"Preload" (for disk-based streams) 10 bytes from the current
- stream position.
- <li>Set the frame "cursor" to the first byte in the frame;
+ <li>
+ <p>Ensure that there are at least 2+4+4=10 bytes left in the
+ stream.</p>
+ </li>
+ <li>
+ <p>"Preload" (for disk-based streams) 10 bytes from the current
+ stream position.</p>
+ </li>
+ <li>
+ <p>Set the frame "cursor" to the first byte in the frame.</p>
+ </li>
</ul>
- <p>
- Each <tt>FT_Get_Short</tt> or <tt>FT_Get_ULong</tt> call will read a
- big-endian integer from the stream (2 bytes for <tt>FT_Get_Short</tt>,
- 4 bytes for <tt>FT_Get_ULong</tt>) and advance the frame cursor accordingly.
- <p>
- <tt>FT_Forget_Frame</tt> "releases" the frame from memory
- <p>
- There are several advantages to using frames :<p>
+
+ <p>Each <tt>FT_Get_Short()</tt> or <tt>FT_Get_ULong()</tt> call will read
+ a big-endian integer from the stream (2 bytes for
+ <tt>FT_Get_Short()</tt>, 4 bytes for <tt>FT_Get_ULong</tt>) and
+ advance the frame cursor accordingly.</p>
+
+ <p><tt>FT_Forget_Frame()</tt> "releases" the frame from memory.</p>
+
+ <p>There are several advantages to using frames:</p>
+
<ul>
- <li>single-check when loading tables
- <li><em>making code clearer</em> by providing simple parsing functions
- <em>while keeping code safe</em> from file over-runs and invalid
- offsets.
+ <li>
+ <p>Single-check when loading tables.</p>
+ </li>
+ <li>
+ <p><em>Making code clearer</em> by providing simple parsing functions
+ <em>while keeping code safe</em> from file over-runs and invalid
+ offsets.</p>
+ </li>
</ul>
- <p>
-</ul>
-<p><hr><p>
+ <hr>
-<h2>II. Accessing and reading a frame with macros:</h2>
-<ul>
- By convention in the FreeType source code, macros are able to use two implicit
- variables named "<tt>error</tt>" and "<tt>stream</tt>". This is useful because
- these two variables are extremely used in the library, and doing this only
- reduces our typing requirements and make the source code much clearer.
- <p>
- Note that <tt>error</tt> must be a local variable of type <tt>FT_Error</tt>,<br>
- while <tt>stream</tt> must be a local variable or argument of type <tt>FT_Stream</tt>;
- <p>
- The macro used to access a frame is
- <font color="purple"><tt><b>ACCESS_Frame(_size_)</b></tt></font>, it will
- translate to:<p>
- <ul><font color="blue">
- <tt>(error=FT_Access_Frame(stream,_size_)) != FT_Err_Ok</tt>.
- </font></ul>
- <p>
- Similarly, the macro
- <font color="purple"><b><tt>FORGET_Frame()</tt></b></font>
- translates to:<p>
- <ul><font color="blue">
- <tt>FT_Forget_Frame(stream)</tt>
- </font></ul>
- <p>
- Extracting integers can be performed with the <tt>GET_xxx</tt> macros, like:<p>
- <ul>
- <table>
- <tr>
- <td><b>Macro name</b> <td>Translation <td>Description
+ <h2>
+ II. Accessing and reading a frame with macros
+ </h2>
- <tr><td><font color="purple"><tt><b>
- GET_Byte()
- </b></tt></font><td><font color="blue"><tt>
- (FT_Get_Byte(stream))
- </tt></font><td>
- reads an 8-bit unsigned byte
+ <p>By convention in the FreeType source code, macros are able to use two
+ implicit variables named <tt>error</tt> and <tt>stream</tt>. This is
+ useful because these two variables are extremely often used in the
+ library, and doing this only reduces our typing requirements and make the
+ source code much clearer.</p>
- <tr><td><font color="purple"><tt><b>
- GET_Char()
- </b></tt></font><td><font color="blue"><tt>
- ((FT_Char)FT_Get_Byte(stream))
- </tt></font><td>
- reads an 8-bit <em>signed</em> byte
+ <p>Note that <tt>error</tt> must be a local variable of type
+ <tt>FT_Error</tt>, while <tt>stream</tt> must be a local variable or
+ argument of type <tt>FT_Stream</tt>.</p>
+
+ <p>The macro used to access a frame is <font
+ color="purple"><tt><b>ACCESS_Frame(_size_)</b></tt></font>, it will
+ translate to</p>
+
+ <font color="blue">
+ <pre>
+ ( error = FT_Access_Frame( stream, _size_ ) )
+ != FT_Err_Ok</tt></pre>
+ </font>
+
+ <p>Similarly, the macro <font
+ color="purple"><b><tt>FORGET_Frame()</tt></b></font> translates to</p>
+
+ <font color="blue">
+ <pre>
+ <tt>FT_Forget_Frame( stream )</tt></pre>
+ </font>
+
+ <p>Extracting integers can be performed with the <tt>GET_xxx()</tt>
+ macros, like</p>
+
+ <table align=center>
+ <tr valign="top">
+ <td>
+ <b>Macro name</b>
+ </td>
+ <td>
+ Translation
+ </td>
+ <td>
+ Description
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <font color="purple"><tt><b>GET_Byte()</b></tt></font>
+ </td>
+ <td>
+ <font color="blue"><tt>FT_Get_Byte(stream)</tt></font>
+ </td>
+ <td>
+ <p>Reads an 8-bit unsigned byte.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <font color="purple"><tt><b>GET_Char()</b></tt></font>
+ </td>
+ <td>
+ <font color="blue"><tt>(FT_Char)<br>
+ FT_Get_Byte(stream)</tt></font>
+ </td>
+ <td>
+ <p>Reads an 8-bit <em>signed</em> byte.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <font color="purple"><tt><b>GET_Short()</b></tt></font>
+ </td>
+ <td>
+ <font color="blue"><tt>FT_Get_Short(stream)</tt></font>
+ </td>
+ <td>
+ Reads a 16-bit signed big-endian integer.
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <font color="purple"><tt><b>GET_UShort()</b></tt></font>
+ </td>
+ <td>
+ <font color="blue"><tt>(FT_UShort)<br>
+ FT_Get_Short(stream)</tt></font>
+ </td>
+ <td>
+ Reads a 16-bit unsigned big-endian integer.
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <font color="purple"><tt><b>GET_Offset()</b></tt></font>
+ </td>
+ <td>
+ <font color="blue"><tt>FT_Get_Offset(stream)</tt></font>
+ </td>
+ <td>
+ Reads a 24-bit signed big-endian integer.
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <font color="purple"><tt><b>GET_UOffset()</b></tt></font>
+ </td>
+ <td>
+ <font color="blue"><tt>(FT_UOffset)<br>
+ FT_Get_Offset(stream)</tt></font>
+ </td>
+ <td>
+ Reads a 24-bit unsigned big-endian integer.
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <font color="purple"><tt><b>GET_Long()</b></tt></font>
+ </td>
+ <td>
+ <font color="blue"><tt>FT_Get_Long(stream)</tt></font>
+ </td>
+ <td>
+ Reads a 32-bit signed big-endian integer.
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <font color="purple"><tt><b>GET_ULong()</b></tt></font>
+ </td>
+ <td>
+ <font color="blue"><tt>(FT_ULong)<br>
+ FT_Get_Long(stream)</tt></font>
+ </td>
+ <td>
+ Reads a 32-bit unsigned big-endian integer.
+ </td>
+ </tr>
+ </table>
+
+ <p>(Note that an <b>Offset</b> is an integer stored with 3 bytes on
+ the file.)</p>
- <tr><td><font color="purple"><tt><b>
- GET_Short()
- </b></tt></font><td><font color="blue"><tt>
- (FT_Get_Short(stream))
- </tt></font><td>
- reads a 16-bit signed big-endian integer
+ <p>All this means that the following code</p>
- <tr><td><font color="purple"><tt><b>
- GET_UShort()
- </b></tt></font><td><font color="blue"><tt>
- ((FT_UShort)FT_Get_Short(stream))
- </tt></font><td>
- reads a 16-bit unsigned big-endian integer
+ <font color="blue">
+ <pre>
+ error = FT_Access_Frame( stream, 2 + 4 + 4 );
+ if ( error ) goto ...
- <tr><td><font color="purple"><tt><b>
- GET_Offset()
- </b></tt></font><td><font color="blue"><tt>
- (FT_Get_Offset(stream))
- </tt></font><td>
- reads a 24-bit signed big-endian integer
+ str.value1 = FT_Get_Short( stream );
+ str.value2 = FT_Get_ULong( stream );
+ str.value3 = FT_Get_ULong( stream );
- <tr><td><font color="purple"><tt><b>
- GET_UOffset()
- </b></tt></font><td><font color="blue"><tt>
- ((FT_UOffset)FT_Get_Offset(stream))
- </tt></font><td>
- reads a 24-bit unsigned big-endian integer
+ FT_Forget_Frame( stream );</pre>
+ </font>
- <tr><td><font color="purple"><tt><b>
- GET_Long()
- </b></tt></font><td><font color="blue"><tt>
- (FT_Get_Long(stream))
- </tt></font><td>
- reads a 32-bit signed big-endian integer
+ <p>can be simplified with macros:</p>
- <tr><td><font color="purple"><tt><b>
- GET_ULong()
- </b></tt></font><td><font color="blue"><tt>
- ((FT_ULong)FT_Get_Long(stream))
- </tt></font><td>
- reads a 32-bit unsigned big-endian integer
+ <font color="blue">
+ <pre>
+ if ( ACCESS_Frame( 2 +4 + 4 ) ) goto ...
- </table>
- </ul>
- <p>
- (Note that an <b>Offset</b> is an integer stored with 3 bytes on the file).
- <p>
- All this means that the following code:<p>
- <font color="blue"><pre>
- error = FT_Access_Frame(stream, 2+4+4);
- if (error) goto ...
+ str.value1 = GET_Short();
+ str.value2 = GET_ULong();
+ str.value3 = GET_ULong();
- str.value1 = FT_Get_Short(stream);
- str.value2 = FT_Get_ULong(stream);
- str.value3 = FT_Get_ULong(stream);
+ FORGET_Frame();</pre>
+ </font>
- FT_Forget_Frame(stream);<br>
- </pre></font>
- <p>
- Can be replaced with macros by:<p>
- <font color="blue"><pre>
- if ( ACCESS_Frame( 2+4+4 ) ) goto ...
+ <p>Which is clearer. Notice that <tt>error</tt> and <tt>stream</tt>
+ must be defined locally though for this code to work!</p>
- str.value1 = GET_Short();
- str.value2 = GET_ULong();
- str.value3 = GET_ULong();
+ <hr>
- FORGET_Frame();
- </pre></font>
- <p>
- Which is clearer. Notice that <b>error</b> and <b>stream</b> must be defined
- locally though for this code to work.. !!
-</ul>
+ <h2>
+ III. Alternatives
+ </h2>
-<p><hr><p>
+ <p>It is sometimes useful to read small integers from a font file without
+ using a frame. Some functions have been introduced in FreeType 2 to
+ do just that, and they are of the form <font
+ color="blue"><tt>FT_Read_xxxx</tt></font>.</p>
-<h2>III. Alternatives:</h2>
-<ul>
- It is sometimes useful to read small integers from a font file without using
- a frame. Some functions have been introduced in FreeType 2 to do just that,
- and they are of the form <font color="blue"><tt>FT_Read_xxxx</tt></font>.
- <p>
- For example,
- <font color="blue"><tt>FT_Read_Short( stream, &error )</tt></font> reads and
- returns a 2-byte big-endian integer from a <tt>stream</tt>, and place an
- error code in the <tt>error</tt> variable.
- <p>
- Thus, reading a single big-endian integer is shorter than using a frame
- for it.
- <p>
- Note that there is also the macros
- <font color="purple"><tt>READ_xxx()</tt></font> which translate to:<p>
- <font color="blue"><pre>
- <tt>( FT_Read_xxx(stream,&error), error != FT_Err_Ok )
- </pre></font>
- <p>
- and can be used as in:<p>
- <font color="blue"><pre>
- if ( READ_UShort(variable1) || READ_ULong (variable2) ) goto Fail;
- </pre></font>
- <p>
- when <b>error</b> and <b>stream</b> are already defined locally..
-</ul>
+ <p>For example, <font color="blue"><tt>FT_Read_Short(stream,
+ &error)</tt></font> reads and returns a 2-byte big-endian integer from a
+ <tt>stream</tt>, and places an error code in the <tt>error</tt>
+ variable.</p>
+ <p>Thus, reading a single big-endian integer is shorter than using a frame
+ for it.</p>
+
+ <p>Note that there are also macros <font
+ color="purple"><tt>READ_xxx()</tt></font> which translate to</p>
+
+ <font color="blue">
+ <pre>
+ FT_Read_xxx( stream, &error ), error != FT_Err_Ok</pre>
+ </font>
+
+ <p>and can be used as in</p>
+
+ <font color="blue">
+ <pre>
+ if ( READ_UShort( variable1 ) ||
+ READ_ULong ( variable2 ) )
+ goto Fail;</pre>
+ </font>
+
+ <p>if <tt>error</tt> and <tt>stream</tt> are already defined locally.</p>
+
+</td></tr>
+</table>
+</center>
+
+</body>
+</html>
--- a/docs/tutorial/index.html
+++ b/docs/tutorial/index.html
@@ -1,12 +1,12 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="Author" content="David Turner">
- <meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]">
- <title>FreeType 2 Tutorial</title>
+ <meta http-equiv="Content-Type"
+ content="text/html; charset=iso-8859-1">
+ <meta name="Author"
+ content="David Turner">
+ <title>FreeType 2 Tutorial</title>
</head>
-<body>
<body text="#000000"
bgcolor="#FFFFFF"
@@ -14,632 +14,746 @@
vlink="#51188E"
alink="#FF0000">
-<center>
-<h1>
-FreeType 2.0 Tutorial</h1></center>
+<h1 align=center>
+ FreeType 2.0 Tutorial
+</h1>
-<center>
-<h3>
-© 2000 David Turner (<a href="mailto:[email protected]">[email protected]</a>)<br>
-© 2000 The FreeType Development Team
-(<a href="http://www.freetype.org">www.freetype.org</a>)
-</h3></center>
+<h3 align=center>
+ © 2000 David Turner
+ (<a href="mailto:[email protected]">[email protected]</a>)<br>
+ © 2000 The FreeType Development Team
+ (<a href="http://www.freetype.org">www.freetype.org</a>)
+</h3>
<center>
-<table width=650><tr><td>
+<table width="70%">
+<tr><td>
-<p><br>
-<hr WIDTH="100%">
-<br>
-<h2>Introduction:</h2>
-<ul>
- This simple tutorial will teach you how to use the FreeType 2 library
- in your own applications.
-</ul>
+ <hr>
-<p><hr><p>
+ <h2>
+ Introduction
+ </h2>
-<h3>1. Header files :</h3>
-<ul>
- To include the main FreeType header file, simply use:<p>
- <ul><font color="blue"><tt>
- #include <freetype/freetype.h><p>
- </tt></font></ul>
- in your application code. Note that other files are available in the
- FreeType include directory, most of them being included by
- <tt>"freetype.h"</tt>. They will be described later in this tutorial.
-</ul>
+ <p>This short tutorial will teach you how to use the FreeType 2
+ library in your own applications.</p>
-<p><hr><p>
+ <hr>
-<h3>2. Initialise the library:</h3>
-<ul>
- Simply create a variable of type <tt>FT_Library</tt> named, for example,
- <tt>library</tt>, and call the function <tt>FT_Init_FreeType</tt> as in:
+ <h3>
+ 1. Header files
+ </h3>
- <font color="blue"><pre>
- #include <freetype/freetype.h>
+ <p>To include the main FreeType header file, simply say</p>
- FT_Library library;
+ <font color="blue">
+ <pre>
+ #include <freetype/freetype.h></pre>
+ </font>
- ....
+ <p>in your application code. Note that other files are available in the
+ FreeType include directory, most of them being included by
+ <tt>"freetype.h"</tt>. They will be described later in this
+ tutorial.</p>
- {- ..
- error = FT_Init_FreeType( &library );
- if (error) { .. an error occured during library initialisation .. }- }
- </pre></font>
- <p>
- This function is in charge of the following:<p>
- <ul>
- <li>Creating a new instance of the FreeType 2 library, and set
- the handle <tt>library</tt> to it.
- <p>
+ <hr>
- <li>Load each font driver that FreeType knows about in the library.
- This means that by default, your new <tt>library</tt> object is
- able to handle TrueType and Type 1 fonts gracefully.
- <p>
- </ul>
- <p>
- As you can see, the function returns an error code, like most others in the
- FreeType API. An error code of 0 <em>always</em> means that the operation
- was succesful; otherwise, the value describes the error, and <tt>library</tt>
- is set to NULL.
-</ul>
+ <h3>
+ 2. Initialize the library
+ </h3>
-<p><hr><p>
+ <p>Simply create a variable of type <tt>FT_Library</tt> named, for
+ example, <tt>library</tt>, and call the function
+ <tt>FT_Init_FreeType()</tt> as in</p>
-<h3>3. Load a font face:</h3>
-<ul>
- <h4>a. From a font file:</h4>
- <ul>
- Create a new <em>face</em> object by calling <tt>FT_New_Face</tt>. A
- <em>face</em> describes a given typeface and style. For example,
- "Times New Roman Regular" and "Times New Roman Italic" correspond to
- two different faces.
- <p>
- <font color="blue"><pre>
+ <font color="blue">
+ <pre>
+ #include <freetype/freetype.h>
- FT_Library library; /* handle to library */
- FT_Face face; /* handle to face object */
+ FT_Library library;
- error = FT_Init_FreeType( &library );
- if (error) { ..... }+ ...
- error = FT_New_Face( library,
- "/usr/share/fonts/truetype/arial.ttf",
- 0,
- &face );
- if (error == FT_Err_Unknown_File_Format)
+ {+ ...
+ error = FT_Init_FreeType( &library );
+ if ( error )
{- .... the font file could be opened and read, but it appears
- .... that its font format is unsupported
+ ... an error occurred during library initialization ...
}
- else if (error)
- {- .... another error code means that the font file could not
- .... be opened, read or simply that it is broken..
- }
- </pre></font>
- <p>
- As you certainly imagine, <tt>FT_New_Face</tt> opens a font file then
- tries to extract one face from it. Its parameters are :<p>
+ }</pre>
+ </font>
+
+ <p>This function is in charge of the following:</p>
+
<ul>
- <table cellpadding=5>
- <tr valign="top"><td><tt><b>library</b></tt>
- <td>handle to the FreeType library instance where the face object is
- created
+ <li>
+ <p>Creating a new instance of the FreeType 2 library, and set
+ the handle <tt>library</tt> to it.</p>
+ </li>
+ <li>
+ <p>Load each font driver that FreeType knows about in the library.
+ This means that by default, your new <tt>library</tt> object is able
+ to handle TrueType and Type 1 fonts gracefully.</p>
+ </li>
+ </ul>
- <tr valign="top"><td><tt><b>filepathname</b></tt>
- <td>the font file pathname (standard C string).
+ <p>As you can see, the function returns an error code, like most others
+ in the FreeType API. An error code of 0 <em>always</em> means that
+ the operation was successful; otherwise, the value describes the error,
+ and <tt>library</tt> is set to NULL.</p>
- <tr valign="top"><td><tt><b>face_index</b></tt>
- <td>Certain font formats allow several font faces to be embedded in
- a single file.<br>
- This index tells which face you want to load. An
- error will be returned if its value is too large.<br>
- Index 0 always work though.
+ <hr>
- <tr><td><tt><b>face</b></tt>
- <td>A <em>pointer</em> to the handle that will be set to
- describe the new face object.<br>
- It is set to NULL in case of error.
- </table>
- </ul>
- <p>
- To known how many faces a given font file contains, simply load its
- first face (use <tt>face_index</tt>=0), then see the value of
- <tt>face->num_faces</tt> which indicates how many faces are embedded in
- the font file.
- </ul>
- <p>
+ <h3>
+ 3. Load a font face
+ </h3>
- <h4>b. From memory:</h4>
- <ul>
- In the case where you have already loaded the font file in memory, you
- can similarly create a new face object for it by calling
- <tt>FT_New_Memory_Face</tt> as in:
- <p>
- <font color="blue"><pre>
+ <h4>
+ a. From a font file
+ </h4>
- FT_Library library; /* handle to library */
- FT_Face face; /* handle to face object */
+ <p>Create a new <em>face</em> object by calling <tt>FT_New_Face</tt>.
+ A <em>face</em> describes a given typeface and style. For example,
+ "Times New Roman Regular" and "Times New Roman Italic" correspond to
+ two different faces.</p>
- error = FT_Init_FreeType( &library );
- if (error) { ..... }+ <font color="blue">
+ <pre>
+ FT_Library library; /* handle to library */
+ FT_Face face; /* handle to face object */
- error = FT_New_Memory_Face( library,
- buffer, /* first byte in memory */
- size, /* size in bytes */
- 0, /* face_index */
- &face );
- if (error) { ... }- </pre></font>
- <p>
- As you can see, <tt>FT_New_Memory_Face</tt> simply takes a pointer to
- the font file buffer and its size in bytes instead of a file pathname.
- Other than that, it has exactly the same semantics than
- <tt>FT_New_Face</tt>.
- </ul>
- <p>
+ error = FT_Init_FreeType( &library );
+ if ( error ) { ... }- <h4>c. From other sources: (compressed files, network, etc..)</h4>
- <ul>
- There are cases where using a filepathname or preloading the file in
- memory is simply not enough. With FreeType 2, it is possible to provide
- your own implementation of i/o routines.
- <p>
- This is done through the <tt>FT_Open_Face</tt> function, which can be
- used to open a new font face with a custom input stream, select a specific
- driver for opening, or even pass extra parameters to the font driver
- when creating the object. We advise you to refer to the FreeType 2
- Reference in order to learn how to use it.
- <p>
- </ul>
- <p>
-</ul>
+ error = FT_New_Face( library,
+ "/usr/share/fonts/truetype/arial.ttf",
+ 0,
+ &face );
+ if ( error == FT_Err_Unknown_File_Format )
+ {+ ... the font file could be opened and read, but it appears
+ ... that its font format is unsupported
+ }
+ else if ( error )
+ {+ ... another error code means that the font file could not
+ ... be opened or read, or simply that it is broken...
+ }</pre>
+ </font>
-<p><hr><p>
+ <p>As you can certainly imagine, <tt>FT_New_Face</tt> opens a font
+ file, then tries to extract one face from it. Its parameters are</p>
-<h3>4. Accessing face content:</h3>
-<ul>
- A <em>face object</em> models all information that globally describes
- the face. Usually, this data can be accessed directly by dereferencing
- a handle, like :
- <p>
- <table cellpadding=5>
- <tr valign="top">
- <td><tt><b>face−>num_glyphs</b></tt>
- <td>gives the number of <em>glyphs</em> available in the font face. A glyph
- is simply a character image. It doesn't necessarily correspond to
- a <em>character code</em> though.
+ <table cellpadding=5>
+ <tr valign="top">
+ <td>
+ <tt><b>library</b></tt>
+ </td>
+ <td>
+ <p>handle to the FreeType library instance where the face object
+ is created</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>filepathname</b></tt>
+ </td>
+ <td>
+ <p>the font file pathname (standard C string).</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>face_index</b></tt>
+ </td>
+ <td>
+ <p>Certain font formats allow several font faces to be embedded
+ in a single file.</p>
- <tr valign="top">
- <td><tt><b>face−>flags</b></tt>
- <td>a 32-bit integer containing bit flags used to describe some face
- properties. For example, the flag <tt>FT_FACE_FLAG_SCALABLE</tt> is
- used to indicate that the face's font format is scalable and that
- glyph images can be rendered for all character pixel sizes. For more
- information on face flags, please read the <a href="#">FreeType API
- Reference</a>
+ <p>This index tells which face you want to load. An error will
+ be returned if its value is too large.</p>
- <tr valign="top">
- <td><tt><b>face−>units_per_EM</b></tt>
- <td>This field is only valid for scalable formats (it is set to 0
- otherwise). It indicates the number of font units covered by the
- EM.
+ <p>Index 0 always work though.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>face</b></tt>
+ </td>
+ <td>
+ <p>A <em>pointer</em> to the handle that will be set to describe
+ the new face object.</p>
- <tr valign="top">
- <td><tt><b>face−>num_fixed_sizes</b></tt>
- <td>this field gives the number of embedded bitmap <em>strikes</em> in
- the current face. A <em>strike</em> is simply a series of glyph
- images for a given character pixel size. For example, a font face
- could include strikes for pixel sizes 10, 12 and 14. Note that even
- scalable font formats can embedded bitmap strikes !
+ <p>It is set to NULL in case of error.</p>
+ </td>
+ </tr>
+ </table>
- <tr valign="top">
- <td><tt><b>face−>fixed_sizes</b></tt>
- <td>this is a pointer to an array of <tt>FT_Bitmap_Size</tt> element.
- each <tt>FT_Bitmap_Size</tt> indicates the horizontal and vertical
- <em>pixel sizes</em> for each of the strikes that are present in the face.
+ <p>To know how many faces a given font file contains, simply load its
+ first face (use <tt>face_index</tt>=0), then see the value of
+ <tt>face->num_faces</tt> which indicates how many faces are embedded
+ in the font file.</p>
- </table>
- <p>
- For a complete listing of all face properties and fields, please read
- the <a href="#">FreeType 2 API Reference</a>.
- <p>
-</ul>
+ <h4>
+ b. From memory
+ </h4>
-<p><hr><p>
-<h3>5. Setting the current pixel size:</h3>
-<ul>
- 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>
- 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>
- To do that, simply call <tt>FT_Set_Char_Size</tt>. Here's an example
- where the character size is set to 16 pts for a 300x300 dpi device:
- <p>
- <font color="blue"><pre>
- error = FT_Set_Char_Size( face, /* handle to face object */
- 0, /* char_width in 1/64th of points */
- 16*64, /* char_height in 1/64th of points */
- 300, /* horizontal device resolution */
- 300 ); /* vertical device resolution */
- </pre></font>
- <p>
- You'll notice that:<p>
- <ul>
- <li>The character width and heights are specified in 1/64th of points.<p>
+ <p>In the case where you have already loaded the font file in memory,
+ you can similarly create a new face object for it by calling
+ <tt>FT_New_Memory_Face</tt> as in</p>
- <li>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>
+ <font color="blue">
+ <pre>
+ FT_Library library; /* handle to library */
+ FT_Face face; /* handle to face object */
- <li>A value of 0 for the character width means "<em>same as character
- height</em>", a value of 0 for the character height means
- "<em>same as character width</em>". Otherwise, it is possible to
- specify different char width and height.<p>
+ error = FT_Init_FreeType( &library );
+ if ( error ) { ... }- <li>Using a value of 0 for the horizontal or vertical resolution means
- 72 dpi, which is the default.
- <p>
- </ul>
- <p>
- This function computes the character pixel size that corresponds to the
- character width and height and device resolutions. However, if you want
- to specify the pixel sizes yourself, you can simply call
- <tt>FT_Set_Pixel_Sizes</tt>, as in:
- <p>
- <font color="blue"><pre>
- error = FT_Set_Pixel_Sizes( face, /* handle to face object */
- 0, /* pixel_width */
- 16 ); /* pixel_height */
- </pre></font>
- <p>
- This example will set the character pixel sizes to 16x16 pixels. As
- previously, a value of 0 for one of the dimensions means "<em>same as
- the other</em>".
- <p>
- Note that both functions return an error code. Usually, an error occurs
- with a fixed-size font format (like FNT or PCF) when trying to set the
- pixel size to a value that is not listed in the
- <tt><b>face->fixed_sizes</b></tt> array.
-</ul>
+ error = FT_New_Memory_Face( library,
+ buffer, /* first byte in memory */
+ size, /* size in bytes */
+ 0, /* face_index */
+ &face );
+ if ( error ) { ... }</pre>+ </font>
-<p><hr><p>
+ <p>As you can see, <tt>FT_New_Memory_Face()</tt> simply takes a
+ pointer to the font file buffer and its size in bytes instead of a
+ file pathname. Other than that, it has exactly the same semantics as
+ <tt>FT_New_Face()</tt>.</p>
-<h3>6. Loading a glyph image:</h3>
-<ul>
- <h4>a. Converting a character code into a glyph index:</h4>
- <ul>
- Usually, an application wants to load a glyph image based on its
- <em>character code</em>, which is a unique value that defines the
- character for a given <em>encoding</em>. For example, the character
- code 65 represents the 'A' in the ASCII encoding.
- <p>
- A face object contains one or more tables, called <em>charmaps</em>,
- that are used to convert character codes to glyph indices. For example,
- most TrueType fonts contain two charmaps. One is used to convert Unicode
- character codes to glyph indices, the other is used to convert
- Apple Roman encoding into glyph indices. Such fonts can then be used
- either on Windows (which uses Unicode) and Macintosh (which uses
- Apple Roman, bwerk..). Note also that a given charmap might not map to all
- the glyphs present in the font.
- <p>
- By default, when a new face object is created, it lists all the charmaps
- contained in the font face and selects the one that supports Unicode
- character codes if it finds one. Otherwise, it tries to find support for
- Latin-1, then ASCII.
- <p>
- We'll describe later how to look for specific charmaps in a face. For
- now, we'll assume that the face contains at least a Unicode charmap that
- was selected during <tt>FT_New_Face</tt>. To convert a Unicode character
- code to a font glyph index, we use <tt>FT_Get_Char_Index</tt> as in:
- <p>
- <font color="blue"><pre>
- glyph_index = FT_Get_Char_Index( face, charcode );
- </pre></font>
- <p>
- This will look the glyph index corresponding to the given <tt>charcode</tt>
- in the charmap that is currently selected for the face. If charmap is
- selected, the function simply returns the charcode.
- <p>
- Note that this is one of the rare FreeType functions that do not return
- an error code. However, when a given character code has no glyph image in
- the face, the value 0 is returned. By convention, it always correspond to
- a special glyph image called the <b>missing glyph</b>, which usually is
- represented as a box or a space.
- <p>
- </ul>
- <p>
+ <h4>
+ c. From other sources (compressed files, network, etc.)
+ </h4>
- <h4>b. Loading a glyph from the face:</h4>
- <ul>
- Once you have a glyph index, you can load the corresponding glyph image.
- Note that the glyph image can be in several formats. For example, it will
- be a bitmap for fixed-size formats like FNT, FON or PCF. It will also
- be a scalable vector outline for formats like TrueType or Type 1. The
- glyph image can also be stored in an alternate way that is not known
- at the time of writing this documentation.
- <p>
- The glyph image is always stored in a special object called a
- <em>glyph slot</em>. As it names suggests, a glyph slot is simply a
- container that is able to hold one glyph image at a time, be it a bitmap,
- an outline, or something else. Each face object has a single glyph slot
- object that can be accessed as <b><tt>face−>glyph</tt></b>.
- <p>
- Loading a glyph image into the slot is performed by calling
- <tt>FT_Load_Glyph</tt> as in:
- <p>
- <font color="blue"><pre>
- error = FT_Load_Glyph( face, /* handle to face object */
- glyph_index, /* glyph index */
- load_flags ); /* load flags, see below */
- </pre></font>
- <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>
- <ul>
- <li>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>
+ <p>There are cases where using a file pathname or preloading the file
+ in memory is simply not enough. With FreeType 2, it is possible
+ to provide your own implementation of i/o routines.</p>
- <li>if there is an outline for the corresponding glyph, load it
- unless <tt>FT_LOAD_NO_OUTLINE</tt> is set. Otherwise, scale it
- to the current size, unless the <tt>FT_LOAD_NO_SCALE</tt> flag
- is set.
- <p>
+ <p>This is done through the <tt>FT_Open_Face()</tt> function, which
+ can be used to open a new font face with a custom input stream, select
+ a specific driver for opening, or even pass extra parameters to the
+ font driver when creating the object. We advise you to refer to the
+ FreeType 2 reference manual in order to learn how to use it.</p>
- <li>if the outline 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.
- </ul>
- <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>.
- </ul>
- <p>
+ <hr>
- <h4>c. Using other charmaps:</h4>
- <ul>
- As said before, when a new face object is created, it will look for
- a Unicode, Latin-1 or ASCII charmap and select it. The currently
- selected charmap is accessed via <b><tt>face−>charmap</tt></b>. This
- field is NULL when no charmap is selected, which typically happen 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>
- 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 look at what charmaps are available in a given
- face.
- <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>
- Each charmap has a few visible fields used to describe it in more details.
- 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>
- Here's an example code that looks for a chinese Big5 charmap then
- selects it via <tt>FT_Set_CharMap</tt>:
- <p>
- <font color="blue"><pre>
- FT_CharMap found = 0;
- FT_CharMap charmap;
- int n;
+ <h3>
+ 4. Accessing face content
+ </h3>
- for ( n = 0; n < face->num_charmaps; n++ )
- {- charmap = face>charmaps[n];
- if (charmap->encoding == ft_encoding_big5)
- {- found = charmap;
- break;
- }
- }
+ <p>A <em>face object</em> models all information that globally describes
+ the face. Usually, this data can be accessed directly by dereferencing
+ a handle, like</p>
- if (!found) { ... }+ <table cellpadding=5>
+ <tr valign="top">
+ <td>
+ <tt><b>face->num_glyphs</b></tt>
+ </td>
+ <td>
+ <p>Gives the number of <em>glyphs</em> available in the font face.
+ A glyph is simply a character image. It doesn't necessarily
+ correspond to a <em>character code</em> though.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>face->flags</b></tt>
+ </td>
+ <td>
+ <p>A 32-bit integer containing bit flags used to describe some
+ face properties. For example, the flag
+ <tt>FT_FACE_FLAG_SCALABLE</tt> is used to indicate that the face's
+ font format is scalable and that glyph images can be rendered for
+ all character pixel sizes. For more information on face flags,
+ please read the <a href="#">FreeType 2 API Reference</a>.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>face->units_per_EM</b></tt>
+ </td>
+ <td>
+ <p>This field is only valid for scalable formats (it is set to 0
+ otherwise). It indicates the number of font units covered by the
+ EM.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>face->num_fixed_sizes</b></tt>
+ </td>
+ <td>
+ <p>This field gives the number of embedded bitmap <em>strikes</em>
+ in the current face. A <em>strike</em> is simply a series of
+ glyph images for a given character pixel size. For example, a
+ font face could include strikes for pixel sizes 10, 12
+ and 14. Note that even scalable font formats can have
+ embedded bitmap strikes!</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>face->fixed_sizes</b></tt>
+ </td>
+ <td>
+ <p>this is a pointer to an array of <tt>FT_Bitmap_Size</tt>
+ elements. Each <tt>FT_Bitmap_Size</tt> indicates the horizontal
+ and vertical <em>pixel sizes</em> for each of the strikes that are
+ present in the face.</p>
+ </td>
+ </tr>
+ </table>
- /* now, select the charmap for the face object */
- error = FT_Set_CharMap( face, found );
- if (error) { .... }- </pre></font>
- <p>
- One might now call <tt>FT_Get_Char_Index</tt> with Big5 character codes
- to retrieve glyph indices.
- <p>
- </ul>
- <p>
-</ul>
+ <p>For a complete listing of all face properties and fields, please read
+ the <a href="#">FreeType 2 API Reference</a>.<p>
-<p><hr><p>
+ <hr>
-<h3>7. Accessing glyph image data:</h3>
-<ul>
- Glyph image data is accessible through <tt><b>face−>glyph</b></tt>.
- See the definition of the <tt>FT_GlyphSlot</tt> type for more details. As
- stated previously, each face has a single glyph slot, where <em>one</em> glyph
- image <em>at a time</em> can be loaded. Each time you call
- <tt>FT_Load_Glyph</tt>, you erase the content of the glyph slot with a new
- glyph image.
- <p>
- Note however that the glyph slot object itself doesn't change, only its
- content, which means that you can perfectly create a "shortcut" to access
- it as in:
- <p>
- <font color="blue"><pre>
- {- FT_GlyphSlot glyph = face->glyph; /* shortcut to glyph slot */
+ <h3>
+ 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>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>
+
+ <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>
+
+ <font color="blue">
+ <pre>
+ error = FT_Set_Char_Size(
+ face, /* handle to face object */
+ 0, /* char_width in 1/64th of points */
+ 16*64, /* char_height in 1/64th of points */
+ 300, /* horizontal device resolution */
+ 300 ); /* vertical device resolution */</pre>
+ </font>
+
+ <p>You will notice that:</p>
+
+ <ul>
+ <li>
+ <p>The character width and heights are specified in 1/64th of
+ points.<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>
+ </li>
+ <li>
+ <p>A value of 0 for the character width means "<em>same as
+ character height</em>", a value of 0 for the character height
+ means "<em>same as character width</em>". Otherwise, it is possible
+ to specify different char widths and heights.</p>
+ </li>
+ <li>
+ <p>Using a value of 0 for the horizontal or vertical resolution means
+ 72 dpi, which is the default.</p>
+ </li>
+ </ul>
+
+ <p>This function computes the character pixel size that corresponds to
+ the character width and height and device resolutions. However, if you
+ want to specify the pixel sizes yourself, you can simply call
+ <tt>FT_Set_Pixel_Sizes()</tt>, as in</p>
+
+ <font color="blue">
+ <pre>
+ error = FT_Set_Pixel_Sizes(
+ face, /* handle to face object */
+ 0, /* pixel_width */
+ 16 ); /* pixel_height */</pre>
+ </font>
- for ( n = 0; n < face->num_glyphs; n++ )
- {- .... load glyph n...
- .... access glyph data as glyph->xxxx
- }
- }
- </pre></font>
- <p>
- The <tt>glyph</tt> variable will be valid until its parent <tt>face</tt>
- is destroyed. Here are a few important fields of the glyph slot:
- <p>
- <table cellpadding=10>
- <tr valign="top">
- <td><tt><b>glyph−>format</b></tt>
- <td>Indicates the type of the loaded glyph image. Can be either
- <tt>ft_glyph_format_bitmap</tt>, <tt>ft_glyph_format_outline</tt>
- or other values.
+ <p>This example will set the character pixel sizes to 16x16 pixels.
+ As previously, a value of 0 for one of the dimensions means
+ "<em>same as the other</em>".</p>
+
+ <p>Note that both functions return an error code. Usually, an error
+ occurs with a fixed-size font format (like FNT or PCF) when trying to
+ set the pixel size to a value that is not listed in the
+ <tt><b>face->fixed_sizes</b></tt> array.</p>
+
+ <hr>
+
+ <h3>
+ 6. Loading a glyph image
+ </h3>
+
+ <h4>
+ a. Converting a character code into a glyph index
+ </h4>
+
+ <p>Usually, an application wants to load a glyph image based on its
+ <em>character code</em>, which is a unique value that defines the
+ character for a given <em>encoding</em>. For example, the character
+ code 65 represents the `A' in ASCII encoding.</p>
+
+ <p>A face object contains one or more tables, called
+ <em>charmaps</em>, that are used to convert character codes to glyph
+ indices. For example, most TrueType fonts contain two charmaps. One
+ is used to convert Unicode character codes to glyph indices, the other
+ is used to convert Apple Roman encoding into glyph indices. Such
+ fonts can then be used either on Windows (which uses Unicode) and
+ Macintosh (which uses Apple Roman, bwerk). Note also that a given
+ charmap might not map to all the glyphs present in the font.</p>
+
+ <p>By default, when a new face object is created, it lists all the
+ charmaps contained in the font face and selects the one that supports
+ Unicode character codes if it finds one. Otherwise, it tries to find
+ support for Latin-1, then ASCII.</p>
+
+ <p>We will describe later how to look for specific charmaps in a face.
+ For now, we will assume that the face contains at least a Unicode
+ charmap that was selected during <tt>FT_New_Face()</tt>. To convert a
+ Unicode character code to a font glyph index, we use
+ <tt>FT_Get_Char_Index()</tt> as in</p>
+
+ <font color="blue">
+ <pre>
+ glyph_index = FT_Get_Char_Index( face, charcode );</pre>
+ </font>
+
+ <p>This will look the glyph index corresponding to the given
+ <tt>charcode</tt> in the charmap that is currently selected for the
+ face. If charmap is selected, the function simply returns the
+ charcode.</p>
+
+ <p>Note that this is one of the rare FreeType functions that do not
+ return an error code. However, when a given character code has no
+ glyph image in the face, the value&nbso;0 is returned. By convention,
+ it always correspond to a special glyph image called the <b>missing
+ glyph</b>, which usually is represented as a box or a space.</p>
+
+ <h4>
+ b. Loading a glyph from the face
+ </h4>
+
+ <p>Once you have a glyph index, you can load the corresponding glyph
+ image. Note that the glyph image can be in several formats. For
+ example, it will be a bitmap for fixed-size formats like FNT, FON, or
+ PCF. It will also be a scalable vector outline for formats like
+ TrueType or Type 1. The glyph image can also be stored in an
+ alternate way that is not known at the time of writing this
+ documentation.</p>
+
+ <p>The glyph image is always stored in a special object called a
+ <em>glyph slot</em>. As its name suggests, a glyph slot is simply a
+ container that is able to hold one glyph image at a time, be it a
+ bitmap, an outline, or something else. Each face object has a single
+ glyph slot object that can be accessed as
+ <b><tt>face->glyph</tt></b>.</p>
+
+ <p>Loading a glyph image into the slot is performed by calling
+ <tt>FT_Load_Glyph()</tt> as in</p>
+
+ <font color="blue">
+ <pre>
+ error = FT_Load_Glyph(
+ face, /* handle to face object */
+ glyph_index, /* glyph index */
+ load_flags ); /* load flags, see below */</pre>
+ </font>
+
+ <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>
+
+ <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 an outline for the corresponding glyph, load it
+ unless <tt>FT_LOAD_NO_OUTLINE</tt> is set. Otherwise, scale it to
+ the current size, unless the <tt>FT_LOAD_NO_SCALE</tt> flag is
+ set.</p>
+ </li>
+ <li>
+ <p>If the outline 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>
+ </ul>
- <tr valign="top">
- <td><tt><b>glyph−>metrics</b></tt>
- <td>A simple structure used to hold the glyph image's metrics. Note
- that <em>most distances are expressed in 1/64th of pixels !</em>
- See the API reference or User Guide for a description of the
- <tt>FT_Glyph_Metrics</tt> structure.
+ <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>
+
+ <h4>
+ c. Using other charmaps
+ </h4>
+
+ <p>As said before, when a new face object is created, it will look for
+ a Unicode, Latin-1, or ASCII charmap and select it. The currently
+ selected charmap is accessed via <b><tt>face->charmap</tt></b>. This
+ field is NULL when no charmap is selected, which typically happens
+ 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>
+
+ <font color="blue">
+ <pre>
+ FT_CharMap found = 0;
+ FT_CharMap charmap;
+ int n;
+
+ for ( n = 0; n < face->num_charmaps; n++ )
+ {+ charmap = face->charmaps[n];
+ if ( charmap->encoding == ft_encoding_big5 )
+ {+ found = charmap;
+ break;
+ }
+ }
+
+ if ( !found ) { ... }+
+ /* now, select the charmap for the face object */
+ error = FT_Set_CharMap( face, found );
+ 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>
+
+ <hr>
+
+ <h3>
+ 7. Accessing glyph image data
+ </h3>
+
+ <p>Glyph image data is accessible through <tt><b>face->glyph</b></tt>.
+ See the definition of the <tt>FT_GlyphSlot</tt> type for more details.
+ As stated previously, each face has a single glyph slot, where
+ <em>one</em> glyph image <em>at a time</em> can be loaded. Each time
+ you call <tt>FT_Load_Glyph()</tt>, you erase the content of the glyph
+ slot with a new glyph image.</p>
+
+ <p>Note however that the glyph slot object itself doesn't change, only
+ its content, which means that you can perfectly create a "shortcut" to
+ access it as in</p>
+
+ <font color="blue">
+ <pre>
+ {+ /* shortcut to glyph slot */
+ FT_GlyphSlot glyph = face->glyph;
+
+ for ( n = 0; n < face->num_glyphs; n++ )
+ {+ ... load glyph n ...
+ ... access glyph data as glyph->xxxx
+ }
+ }</pre>
+ </font>
+
+ <p>The <tt>glyph</tt> variable will be valid until its parent
+ <tt>face</tt> is destroyed. Here are a few important fields of the
+ glyph slot:<p>
+
+ <table cellpadding=5>
+ <tr valign="top">
+ <td>
+ <tt><b>glyph->format</b></tt>
+ </td>
+ <td>
+ <p>Indicates the type of the loaded glyph image. Can be either
+ <tt>ft_glyph_format_bitmap</tt>, <tt>ft_glyph_format_outline</tt>,
+ or other values.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>glyph->metrics</b></tt>
+ </td>
+ <td>
+ <p>A simple structure used to hold the glyph image's metrics.
+ Note that <em>most distances are expressed in 1/64th of
+ pixels!</em> See the API reference or the user guide for a
+ description of the <tt>FT_Glyph_Metrics</tt> structure.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>glyph->bitmap</b></tt>
+ </td>
+ <td>
+ <p>If the glyph slot contains a bitmap, a simple
+ <tt>FT_Bitmap</tt> that describes it. See the API reference or
+ user guide for a description of the <tt>FT_Bitmap</tt>
+ structure.</p>
+ </td>
+ </tr>
+ <tr valign="top">
+ <td>
+ <tt><b>glyph->outline</b></tt>
+ </td>
+ <td>
+ <p>When the glyph slot contains a scalable outline, this structure
+ describes it. See the definition of the <tt>FT_Outline</tt>
+ structure.</p>
+ </td>
+ </tr>
+ </table>
- <tr valign="top">
- <td><tt><b>glyph−>bitmap</b></tt>
- <td>When the glyph slot contains a bitmap, a simple <tt>FT_Bitmap</tt>
- that describes it. See the API reference or user guide for a
- description of the <tt>FT_Bitmap</tt> structure.
+ <h3>
+ 8. Rendering glyph outlines into bitmaps
+ </h3>
- <tr valign="top">
- <td><tt><b>glyph−>outline</b></tt>
- <td>When the glyph slot contains a scalable outline, this structure
- describes it. See the definition of the <tt>FT_Outline</tt>
- structure.
- </table>
- <p>
-</ul>
+ <p>You can easily test the format of the glyph image by inspecting the
+ <tt>face->glyph->format</tt> variable. If its value is
+ <tt>ft_glyph_format_bitmap</tt>, the glyph image that was loaded is a
+ bitmap that can be directly blit to your own surfaces through your
+ favorite graphics library (FreeType 2 doesn't provide bitmap
+ blitting routines, as you may imagine :-)</p>
-<h3>8. Rendering glyph outlines into bitmaps:</h3>
-<ul>
- You can easily test the format of the glyph image by inspecting the
- <tt>face->glyph->format</tt> variable. If its value is
- <tt>ft_glyph_format_bitmap</tt>, the glyph image that was loaded is
- a bitmap that can be directly blit to your own surfaces through your
- favorite graphics library (FreeType 2 doesn't provide bitmap blitting
- routines, as you may imagine :-)
- <p>
- On the other hand, when the format if <tt>ft_glyph_format_outline</tt>
- or something else, the library provides a means to convert such glyph
- images to bitmaps through what are called <b>rasters</b>.
- <p>
+ <p>If the format is <tt>ft_glyph_format_outline</tt> or something else,
+ the library provides a means to convert such glyph images to bitmaps
+ through what are called <b>rasters</b>.</p>
+ <p>On the other hand, if the image is a scalable outline or something
+ else, FreeType provides a function to convert the glyph image into a
+ pre-existing bitmap that you will handle to it, named
+ <tt>FT_Get_Glyph_Bitmap</tt>. Here's a <em>simple</em> example code
+ that renders an outline into a <b>monochrome</b> bitmap:</p>
+ <font color="blue">
+ <pre>
+ {+ FT_GlyphSlot glyph;
- On the other hand, when the image is a scalable outline, or something else,
- FreeType provides a function to convert the glyph image into a
- pre-existing bitmap that you'll handle to it, named
- <tt>FT_Get_Glyph_Bitmap</tt>. Here's a <em>simple</em> example code
- that renders an outline into a <b>monochrome</b> bitmap :
- <p>
- <font color="blue"><pre>
- {- FT_GlyphSlot glyph;
+ ... load glyph ...
- .... load glyph ...
+ glyph = face->glyph; /* shortcut to glyph data */
+ if ( glyph->format == ft_glyph_format_outline )
+ {+ FT_Bitmap bit;
- glyph = face->glyph; /* shortcut to glyph data */
- if (glyph->format == ft_glyph_format_outline )
- {- FT_Bitmap bit;
+ /* set-up a bitmap descriptor for our target bitmap */
+ bit.rows = bitmap_height;
+ bit.width = bitmap_width;
+ bit.pitch = bitmap_row_bytes;
+ /* render into a mono bitmap */
+ bit.pixel_mode = ft_pixel_mode_mono;
+ bit.buffer = bitmap_buffer;
- /* set-up a bitmap descriptor for our target bitmap */
- bit.rows = bitmap_height;
- bit.width = bitmap_width;
- bit.pitch = bitmap_row_bytes;
- bit.pixel_mode = ft_pixel_mode_mono; /* render into a mono bitmap */
- bit.buffer = bitmap_buffer;
+ /* render the outline directly into the bitmap */
+ error = FT_Get_Glyph_Bitmap( face, &bit );
+ if ( error ) { ... }+ }
+ }</pre>
+ </font>
- /* render the outline directly into the bitmap */
- error = FT_Get_Glyph_Bitmap( face, &bit );
- if (error) { ... }- }
- }
- </pre></font>
- <p>
- You should note that <b><em><tt>FT_Get_Glyph_Bitmap</tt> doesn't create the
- bitmap.</em></b> It only needs a descriptor, of type <tt>FT_Bitmap</tt>,
- and writes directly into it.
- <p>
- Note that the FreeType scan-converter for outlines can also generate
- anti-aliased glyph bitmaps with 128 level of grays. For now, it is
- restricted to rendering to 8-bit gray-level bitmaps, though this may
- change in the future. Here's some code to do just that:
- <p>
- <font color="blue"><pre>
- {- FT_GlyphSlot glyph;
+ <p>You should note that <b><em><tt>FT_Get_Glyph_Bitmap()</tt> doesn't
+ create the bitmap</em></b>. It only needs a descriptor, of type
+ <tt>FT_Bitmap</tt>, and writes directly into it.</p>
- .... load glyph ...
+ <p>Note that the FreeType scan-converter for outlines can also generate
+ anti-aliased glyph bitmaps with 128 level of grays. For now, it is
+ restricted to rendering to 8-bit gray-level bitmaps, though this may
+ change in the future. Here is some code to do just that:</p>
- glyph = face->glyph; /* shortcut to glyph data */
- if (glyph->format == ft_glyph_format_outline )
- {- FT_Bitmap bit;
+ <font color="blue">
+ <pre>
+ {+ FT_GlyphSlot glyph;
- /* set-up a bitmap descriptor for our target bitmap */
- bit.rows = bitmap_height;
- bit.width = bitmap_width;
- bit.pitch = bitmap_row_bytes;
- bit.pixel_mode = ft_pixel_mode_gray; /* 8-bit gray-level bitmap */
- bit.grays = 128; /* MUST be 128 for now */
- bit.buffer = bitmap_buffer;
+ ... load glyph ...
- /* clean the bitmap - IMPORTANT */
- memset( bit.buffer, 0, bit.rows*bit.pitch );
+ glyph = face->glyph; /* shortcut to glyph data */
+ if ( glyph->format == ft_glyph_format_outline )
+ {+ FT_Bitmap bit;
- /* render the outline directly into the bitmap */
- error = FT_Get_Glyph_Bitmap( face, &bit );
- if (error) { ... }- }
- }
- </pre></font>
- <p>
- You'll notice that :<p>
- <ul>
- <li>As previously, <tt>FT_Get_Glyph_Bitmap</tt> doesn't generate the
- bitmap, it simply renders to it.<p>
+ /* set-up a bitmap descriptor for our target bitmap */
+ bit.rows = bitmap_height;
+ bit.width = bitmap_width;
+ bit.pitch = bitmap_row_bytes;
+ /* 8-bit gray-level bitmap */
+ bit.pixel_mode = ft_pixel_mode_gray;
+ /* MUST be 128 for now */
+ bit.grays = 128;
+ bit.buffer = bitmap_buffer;
- <li>The target bitmap must be cleaned before calling the function. This
- is a limitation of our current anti-aliasing algorithm and is
- EXTREMELY important.<p>
+ /* clean the bitmap - IMPORTANT */
+ memset( bit.buffer, 0, bit.rows*bit.pitch );
- <li>The anti-aliaser uses 128 levels of grays exclusively for now (this
- will probably change in a near future). This means that you <b>must</b>
- set <tt>bit.grays</tt> to 128. The generated image uses values from
- 0 (back color) to 127 (foreground color).
- <p>
+ /* render the outline directly into the bitmap */
+ error = FT_Get_Glyph_Bitmap( face, &bit );
+ if ( error ) { ... }+ }
+ }</pre>
+ </font>
- <li>It is <b>not</b> possible to render directly an anti-aliased outline into
- a pre-existing gray-level bitmap, or even any colored-format one
- (like RGB16 or paletted 8-bits). We will not discuss this issue in
- great details here, but the reason is that we do not want to deal
- with graphics composition (or alpha-blending) within FreeType.
- </ul>
- <p>
- </ul>
-</ul>
+ <p>You will notice that</p>
-</td></tr></table>
+ <ul>
+ <li>
+ <p>As previously, <tt>FT_Get_Glyph_Bitmap()</tt> doesn't generate
+ the bitmap, it simply renders to it.</p>
+ </li>
+ <li>
+ <p>The target bitmap must be cleaned before calling the function.
+ This is a limitation of our current anti-aliasing algorithm and is
+ EXTREMELY important.</p>
+ </li>
+ <li>
+ <p>The anti-aliaser uses 128 levels of grays exclusively for
+ now (this will probably change in a near future). This means that
+ you <b>must</b> set <tt>bit.grays</tt> to 128. The generated
+ image uses values from 0 (back color) to 127 (foreground color).</p>
+ </li>
+ <li>
+ <p>It is <b>not</b> possible to render directly an anti-aliased
+ outline into a pre-existing gray-level bitmap, or even any
+ colored-format one (like RGB16 or paletted 8-bits). We will not
+ discuss this issue in great details here, but the reason is that we
+ do not want to deal with graphics composition (or alpha-blending)
+ within FreeType.<p/>
+ </li>
+ </ul>
+</td></tr>
+</table>
</center>
-<p><hr>
+</body>
+</html>