ref: b94713e9c58fa6655d69b6919c057acc465a4a89
parent: 3ba47068a60bc501d0eb7fe4383a30fc34c349de
author: David Turner <[email protected]>
date: Mon Jan 17 13:56:49 EST 2000
Added a FreeType 2 Tutorial !!
--- /dev/null
+++ b/docs/tutorial/index.html
@@ -1,0 +1,645 @@
+<!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>
+</head>
+<body>
+
+<body text="#000000"
+ bgcolor="#FFFFFF"
+ link="#0000EF"
+ vlink="#51188E"
+ alink="#FF0000">
+
+<center>
+<h1>
+FreeType 2.0 Tutorial</h1></center>
+
+<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>
+
+<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>
+
+<p><hr><p>
+
+<h3>1. Header files :</h3>
+<ul>
+ You only need to include the public header file named <tt>freetype.h</tt>
+ in your source code. Depending on how the library was installed on your
+ system, you might need to use :<p>
+ <ul><font color="blue"><tt>
+ #include <freetype.h><p>
+ </tt></font></ul>
+ or
+ <ul><font color="blue"><tt>
+ #include <freetype2/freetype.h><p>
+ </tt></font></ul>
+ in your application to include the public interface to FreeType.<p>
+</ul>
+
+<p><hr><p>
+
+<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:
+
+ <font color="blue"><pre>
+ #include <freetype.h>
+
+ FT_Library library;
+
+ ....
+
+ {+ ..
+ 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>
+
+ <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>
+
+<p><hr><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>
+
+ FT_Library library; /* handle to library */
+ FT_Face face; /* handle to face object */
+
+ 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)
+ {+ .... 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, 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>
+ <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
+
+ <tr valign="top"><td><tt><b>filepathname</b></tt>
+ <td>the font file pathname (standard C string).
+
+ <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.
+
+ <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>
+
+ <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>
+
+ FT_Library library; /* handle to library */
+ FT_Face face; /* handle to face object */
+
+ error = FT_Init_FreeType( &library );
+ if (error) { ..... }+
+ 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>
+
+ <h4>c. From other sources:</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 through the <tt>FT_Stream</tt>
+ type.
+ <p>
+ Basically, one has to set up a <tt>FT_Stream</tt> object, according to
+ the rules defined in the document named
+ <a href="#">FreeType 2 System Interface</a>, then pass it to the function
+ <tt>FT_Open_Face</tt> as in:
+ <p>
+ <font color="blue"><pre>
+
+ FT_Library library; /* handle to library */
+ FT_Face face; /* handle to face object */
+
+ error = FT_Init_FreeType( &library );
+ if (error) { ..... }+
+ ... set up stream object, with handle "stream" ...
+
+ error = FT_Open_Face( library,
+ stream, /* handle to stream objects */
+ 0, /* face_index */
+ &face );
+ if (error) { ... }+ </pre></font>
+ <p>
+ custom implementations of <tt>FT_Stream</tt> are great to provide advanced
+ features like automatic support of compressed files, network transparency,
+ using UTF-16 file pathnames, etc..
+ <p>
+ </ul>
+ <p>
+</ul>
+
+<p><hr><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.
+
+ <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>
+
+ <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.
+
+ <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 !
+
+ <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.
+
+ </table>
+ <p>
+ For a complete listing of all face properties and fields, please read
+ the <a href="#">FreeType 2 API Reference</a>.
+ <p>
+</ul>
+
+<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>
+
+ <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>
+
+ <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>
+
+ <li>Using a value of 0 for the horizontal or vertical resolution means
+ "<em>same value since last call</em>". By default a new face object
+ has a size whose resolutions are set to 72x72 dpi.
+ <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>
+
+<p><hr><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>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
+ 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>
+
+ <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>
+
+ <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>
+
+ <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.
+ <p>
+ The field <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;
+
+ 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 Big5 character codes
+ to retrieve glyph indices.
+ <p>
+ </ul>
+ <p>
+</ul>
+
+<p><hr><p>
+
+<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 on more details. You
+ can perfectly create a shortcut to the glyph slot as in:
+ <p>
+ <font color="blue"><pre>
+ {+ FT_GlyphSlot glyph;
+
+ .... load glyph ...
+
+ glyph = face->glyph; /* shortcut to glyph data */
+
+ .... access glyph data as glyph->xxxx
+ }
+ </pre></font>
+ <p>
+ For example, one can access the following fields:
+ <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.
+
+ <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>all 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.
+
+ <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.
+
+ <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>
+
+<h3>8. Rendering glyph outlines into bitmaps:</h3>
+<ul>
+ When the glyph image loaded in a glyph slot is a bitmap, you can use
+ your favorite graphics library to blit it to your own surfaces.
+ <p>
+ 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 ...
+
+ 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;
+ 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>
+ <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;
+
+ .... load glyph ...
+
+ 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;
+ bit.pixel_mode = ft_pixel_mode_gray; /* 8-bit gray-level bitmap */
+ bit.grays = 128; /* MUST be 128 for now */
+ bit.buffer = bitmap_buffer;
+
+ /* clean the bitmap - IMPORTANT */
+ memset( bit.buffer, 0, bit.rows*bit.pitch );
+
+ /* 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>
+
+ <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>
+
+ <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>
+
+ <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><hr>
+