📄 step1.html
字号:
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<style type="text/css">
div.pre
{
font-family: monospace;
text-align: left;
white-space: pre;
color: blue;
}
span.comment
{
color: gray;
}
</style>
<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 Tutorial<br>
Step 1 — simple glyph loading
</h1>
<h3 align=center>
© 2003 David Turner
(<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
© 2003 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 is the first section of the FreeType 2 tutorial. It will teach
you how to:</p>
<ul>
<li>initialize the library</li>
<li>open a font file by creating a new face object</li>
<li>select a character size in points or in pixels</li>
<li>load a single glyph image and convert it to a bitmap</li>
<li>render a very simple string of text</li>
<li>render a rotated string of text easily</li>
</ul>
<hr>
<h3>
1. Header files
</h3>
<p>The following are instructions required to compile an application that
uses the FreeType 2 library. <em><font color="red">Please read them
carefully; we have changed a few things since the last
release!</font></em></p>
<ol>
<li>
<p><b><font size="+1">Locate the FreeType 2 <tt>include</tt>
directory.</font></b><br></p>
<p>You have to add it to your compilation include path.</p>
<p>Note that on Unix systems, you can now run the
<tt>freetype-config</tt> script with the <tt>--cflags</tt> option to
retrieve the appropriate compilation flags. This script can also be
used to check the version of the library that is installed on your
system, as well as the required librarian and linker flags.</p>
</li>
<li>
<p><b><font size="+1">Include the file named
<tt>ft2build.h</tt>.</font></b></p>
<p>It contains various macro declarations that are later used to
<tt>#include</tt> the appropriate public FreeType 2 header
files.</p>
</li>
<li>
<p><b><font size="+1">Include the main FreeType 2 API header
file.</font></b></p>
<p>You should do that using the macro <tt>FT_FREETYPE_H</tt>,
like in the following example:</p>
<div class="pre">
#include <ft2build.h>
#include FT_FREETYPE_H
</div>
<p><tt>FT_FREETYPE_H</tt> is a special macro defined in the file
<tt>ftheader.h</tt>. It contains some installation-specific macros
to name other public header files of the FreeType 2 API.</p>
<p>You can read <a
href="../reference/ft2-header_file_macros.html">this section of the
FreeType 2 API Reference</a> for a complete listing of the
header macros.</p>
</li>
</ol>
<p>The use of macros in <tt>#include</tt> statements is ANSI-compliant.
It is used for several reasons:</p>
<ul>
<li>
<p>It avoids some painful conflicts with the FreeType 1.x public
header files.</p>
</li>
<li>
<p>The macro names are not limited to the DOS 8.3 file naming limit;
names like <tt>FT_MULTIPLE_MASTERS_H</tt> or <tt>FT_SFNT_NAMES_H</tt>
are a lot more readable and explanatory than the real file names
<tt>ftmm.h</tt> and <tt>ftsnames.h</tt>.</p>
</li>
<li>
<p>It allows special installation tricks that will not be discussed
here.</p>
</li>
</ul>
<p><font color="red">NOTE: Starting with FreeType 2.1.6, the old
header file inclusion scheme is no longer supported. This means that
you now get an error if you do something like the following:</font></p>
<div class="pre">
#include <freetype/freetype.h>
#include <freetype/ftglyph.h>
...
</div>
<hr>
<h3>
2. Initialize the library
</h3>
<p>Simply create a variable of type <a
href="../reference/ft2-base_interface.html#FT_Library">
<tt>FT_Library</tt></a> named, for example, <tt>library</tt>, and call
the function <a
href="../reference/ft2-base_interface.html#FT_Init_FreeType">
<tt>FT_Init_FreeType</tt></a> as in</p>
<div class="pre">
#include <ft2build.h>
#include FT_FREETYPE_H
FT_Library library;
...
error = FT_Init_FreeType( &library );
if ( error )
{
... an error occurred during library initialization ...
}
</div>
<p>This function is in charge of the following:</p>
<ul>
<li>
<p>It creates a new instance of the FreeType 2 library, and
sets the handle <tt>library</tt> to it.</p>
</li>
<li>
<p>It loads each module that FreeType knows about in the library.
Among others, 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 <tt>face</tt> object by calling <a
href="../reference/ft2-base_interface.html#FT_New_Face">
<tt>FT_New_Face</tt></a>. 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>
<div class="pre">
FT_Library library; <span class="comment">/* handle to library */</span>
FT_Face face; <span class="comment">/* handle to face object */</span>
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...
}
</div>
<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>library</tt>
</td>
<td>
<p>A handle to the FreeType library instance where the face object
is created.</p>
</td>
</tr>
<tr valign="top">
<td>
<tt>filepathname</tt>
</td>
<td>
<p>The font file pathname (a standard C string).</p>
</td>
</tr>
<tr valign="top">
<td>
<tt>face_index</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>face</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 (this is, <tt>face_index</tt> should be set to zero), then
check 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 into memory,
you can similarly create a new face object for it by calling <a
href="../reference/ft2-base_interface.html#FT_New_Memory_Face">
<tt>FT_New_Memory_Face</tt></a> as in</p>
<div class="pre">
FT_Library library; <span class="comment">/* handle to library */</span>
FT_Face face; <span class="comment">/* handle to face object */</span>
error = FT_Init_FreeType( &library );
if ( error ) { ... }
error = FT_New_Memory_Face( library,
buffer, <span class="comment">/* first byte in memory */</span>
size, <span class="comment">/* size in bytes */</span>
0, <span class="comment">/* face_index */</span>
&face );
if ( error ) { ... }
</div>
<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
into memory is simply not sufficient. With FreeType 2, it is
possible to provide your own implementation of i/o routines.</p>
<p>This is done through the <a
href="../reference/ft2-base_interface.html#FT_Open_Face">
<tt>FT_Open_Face</tt></a> 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>
<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 in <tt>face−>num_glyphs</tt>.</p>
<p>The complete list of available fields in in the <a
href="../reference/ft2-base_interface.html#FT_FaceRec">
<tt>FT_FaceRec</tt></a> structure description. However, we describe
here a few of them in more details:
</p>
<table cellpadding=5>
<tr valign="top">
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -