+++ /dev/null
-<!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">
- <title>FreeType 2 Tutorial</title>
-</head>
-
-<body text="#000000"
- bgcolor="#FFFFFF"
- link="#0000EF"
- vlink="#51188E"
- alink="#FF0000">
-
-<h1 align=center>
- FreeType 2.0 Tutorial
-</h1>
-
-<h3 align=center>
- © 2000 David Turner
- (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
- © 2000 The FreeType Development Team
- (<a href="http://www.freetype.org">www.freetype.org</a>)
-</h3>
-
-<center>
-<table width="70%">
-<tr><td>
-
- <hr>
-
- <h2>
- Introduction
- </h2>
-
- <p>This short tutorial will teach you how to use the FreeType 2
- library in your own applications.</p>
-
- <hr>
-
- <h3>
- 1. Header files
- </h3>
-
- <p>To include the main FreeType header file, simply say</p>
-
- <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>
-
- <hr>
-
- <h3>
- 2. Initialize the library
- </h3>
-
- <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>
-
- <font color="blue">
- <pre>
- #include <freetype/freetype.h>
-
- FT_Library library;
-
- ...
-
- {
- ...
- error = FT_Init_FreeType( &library );
- if ( error )
- {
- ... an error occurred during library initialization ...
- }
- }</pre>
- </font>
-
- <p>This function is in charge of the following:</p>
-
- <ul>
- <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 modules that FreeType knows about in the library.
- This means that by default, your new <tt>library</tt> object is able
- to handle TrueType, Type 1, CID-keyed & OpenType/CFF fonts
- gracefully.</p>
- </li>
- </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 successful; otherwise, the value describes the error,
- and <tt>library</tt> is set to NULL.</p>
-
- <hr>
-
- <h3>
- 3. Load a font face
- </h3>
-
- <h4>
- a. From a font file
- </h4>
-
- <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>
-
- <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 or read, or simply that it is broken...
- }</pre>
- </font>
-
- <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>
-
- <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>
-
- <p>This index tells which face you want to load. An error will
- be returned if its value is too large.</p>
-
- <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>
-
- <p>It is set to NULL in case of error.</p>
- </td>
- </tr>
- </table>
-
- <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>
-
- <h4>
- b. From memory
- </h4>
-
- <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>
-
- <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 as
- <tt>FT_New_Face()</tt>.</p>
-
- <h4>
- c. From other sources (compressed files, network, etc.)
- </h4>
-
- <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>
-
- <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>
-
- <p>Note that providing a custom stream might also be used to access a
- TrueType font embedded in a Postscript Type 42 wrapper.</p>
-
- <hr>
-
- <h3>
- 4. Accessing face content
- </h3>
-
- <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>
-
- <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>
-
- <p>For a complete listing of all face properties and fields, please read
- the <a href="#">FreeType 2 API Reference</a>.<p>
-
- <hr>
-
- <h3>
- 5. Setting the current pixel size
- </h3>
-
- <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 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>
-
- <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. 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. 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
- 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>
- <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
- 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>
-
- <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 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.</p>
-
- <p>This function will try to load the corresponding glyph image
- from the face. Basically, this means that:</p>
-
- <ul>
- <li>
- <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>
-
- <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
- </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>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;
- FT_CharMap charmap;
- int n;
-
- for ( n = 0; n < face->num_charmaps; n++ )
- {
- charmap = face->charmaps[n];
- if ( charmap->platform_id == my_platform_id &&
- charmap->encoding_id == my_encoding_id )
- {
- found = charmap;
- break;
- }
- }
-
- if ( !found ) { ... }
-
- /* now, select the charmap for the face object */
- error = FT_Set_CharMap( face, found );
- if ( error ) { ... }</pre>
- </font>
-
- <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>
- 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>
-
- <h3>
- 8. Rendering glyph outlines into bitmaps
- </h3>
-
- <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>
-
- <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;
-
- ... 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;
- /* render into a mono bitmap */
- bit.pixel_mode = ft_pixel_mode_mono;
- 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>
-
- <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>
-
- <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;
- /* 8-bit gray-level bitmap */
- bit.pixel_mode = ft_pixel_mode_gray;
- /* MUST be 128 for now */
- bit.grays = 128;
- 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 will notice that</p>
-
- <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>
-
-</body>
-</html>
git://git.jankratochvil.net / reactos.git / blobdiff