rgraves
/
freetype2
forked from minhngoc25a/freetype2
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

removed obsolete documentation files 

they are now moved to the "www" module, under "www/freetype2/docs"
This commit is contained in:
David Turner 2001-03-23 11:20:35 +00:00
parent 7dc15dbbd8
commit 1389ce0188
48 changed files with 0 additions and 9675 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

267
docs/cache/cache.txt vendored
View File

@ -1,267 +0,0 @@
The FreeType 2 cache sub-system explained
(c) 2000 David Turner
-----------------------------------------------
Introduction :
--------------
this document describes the caching sub-system that comes
with the FreeType library, version 2.0. Note that unlike
the rest of the library, this code is still in beta stage
and might still suffer slight changes in the future.
Its basic design shouldn't evolve though and is explained
in this paper.
I. Requirements and Design Goals:
---------------------------------
The FT2 cache sub-system was designed to implement caching
of glyph images. However, it is extremely flexible and can
be easily extended to cache other kind of data like metrics,
character maps, coverage tables, etc..
II. Base Concepts:
------------------
1. The cache manager object:
at the heart of the caching sub-system is a single object
called the "cache manager". It is used to deal with FT_Face
and FT_Size objects, as well as to manager a LRU list of
abstract "cache nodes".
a. caching FT_Face and FT_Size objects:
each FT_Face object created by FreeType 2 can take from
a few hundred bytes to several tens of kilobytes, depending
on the original font's file format as well as its content.
there is no easy way to compute the size of a given FT_Face
object, so it's always a good idea to assume that it is
large and to want to limit the number of live face objects
as much as possible.
similarly, each FT_Face can have one or more FT_Size childs,
whose byte size depends heavily on the font format.
the first purpose of the cache manager is to provide a
small cache for FT_Face and FT_Size objects. Basically,
an application can use it as follows:
- each font face is described to the cache manager
through a typeless pointer, called a FTC_FaceID.
the cache manager itself doesn't interpret or use
the value of FTC_FaceIDs directly. Rather, it passes
them to a user-provided function called a
"face requester". see the defintion of the
FTC_Face_Requester type in <freetype/ftcache.h>
for details..
the face requester is in charge of translating a given
face into into a real new FT_Face object that is
returned to the cache manager. The latter will keep
the face object alive as long as it needs to.
the face requester is unique and must be passed
to the function named FTC_Manager_New used to
create/initialise a new cache manager.
- to lookup a given FT_Face, call the function
FTC_Manager_Lookup_Face as in the following code:
FTC_Manager_Lookup_Face( manager,
face_id,
&face );
if the corresponding FT_Face object is kept in
the cache manager's list, it will be returned
directly. Otherwise, this function will call
the user-provided face requester to create
a new FT_Face object, add it to the manager's
list to finally return it.
FT_Face objects are always destroyed by the cache
manager. An application that uses the cache
sub-system should never call FT_Done_Face !!
- to lookup a given FT_Size and FT_Face, call the
function FTC_Manager_Lookup_Size, as in:
FTC_Manager_Lookup_Size( manager,
ftc_font,
&face,
&size );
where "ftc_font" is a pointer to a FTC_Font descriptor
(a structure containing a FTC_FaceIDs and character
dimensions corresponding to the desired FT_Size).
note that the function returns both a FT_Face and
a FT_Size object. You don't need to call
FTC_Manager_Lookup_Face before it !!
also note that returned FT_Size objects are always
destroyed by the cache manager. A client application
that uses it should never call FT_Done_Size !!
the big advantage of using FTC_FaceIDs is that is
makes the caching sub-system completely independent
of the way font files are installed / listed / managed
in your application. In most implementations, a FTC_FaceID
is really a pointer to an application-specific structure
that describe the source font file + face index.
b - manage a MRU list of abstract "cache nodes":
the second role of the cache manager is to hold and manager
a list of abstract "cache nodes". The list is always sorted
in most-recently-used order. The manager always ensure that
the total size of nodes in memory doesn't over-reach a
certain threshold, by eliminating "old" nodes when
necessary.
the cache manager doesn't know much about the cache nodes:
- it knows how to move them in its list
- it knows how to destroy them when they're too old
- it knows how to "size" them (i.e. compute their byte
size in memory)
2. Cache objects:
the cache manager doesn't create new cache nodes however, this
is the charge of what are called "cache objects".
Basically, each cache object is in charge of managing cache
nodes of a certain type. Its role is to:
- provide a simple description of its cache nodes to the
manager (i.e. through a FTC_CacheNode_Class structure)
- provide a high-level API that can be called by client
applications to lookup cache nodes of the corresponding
type.
this function usually creates new nodes when they're not
available yet.
- also, and even though this is completely transparent to
the applications and the cache manager, each cache object
manages "node sets", where each set contains cache nodes
usually correspond to the same font face + font size.
For example, the cache sub-system currently comes with two
distinct cache classes:
- a FTC_Image_Cache, which is used to cache FT_Glyph images
(with one FT_Glyph per cache node).
- a FTC_SBit_Cache, which is used to cache small glyph bitmaps
("sbit" means "embedded bitmaps" in digital typography).
the small bitmaps glyph is useful because storing one glyph
image per cache node isn't memory efficient when the data
associated to each node is very small. Indeed, each cache
node has a minimal size of 20 bytes, which is huge when
your data is an 8x8 monochrome bitmap :-)
Hence, a FTC_SBit_Cache is capable of storing several
contiguous sbits in a single cache node, resulting in much
higher cached glyphs / total cache size.
an application can lookup a FT_Glyph image with a FTC_Image_Cache
by calling:
error = FTC_Image_Cache_Lookup( image_cache,
ftc_font,
glyph_index,
&ft_glyph );
or a FTC_SBit (small bitmap descriptor) by calling:
error = FTC_SBit_Cache_Lookup( sbit_cache,
ftc_font,
glyph_index,
&ftc_sbit );
III. Extending the cache sub-system:
It is possible to extend the current cache sub-system by
providing your own cache class and register it in the cache
manager. That might be useful to cache other kind of data
in the sub-system, like glyph metrics (without images),
To do it, you'll need to read the cache sub-system public
header files rather heavily :-) Fortunately, they're pretty
well commented and should guide you to your goal.
Note that the cache sub-system already provides two "abstract
cache" classes that can be re-used by your own implementation:
1. The abstract "FTC_GlyphCache" class:
this code is used to implement an abstract "glyph cache",
i.e. one that simply maps one glyph data per cache node.
it is sub-classed by FTC_Image_Cache, whose implementation
only consists in simple code to store a FT_Glyph in each
cache node.
you could sub-class it in your application to store glyph
images in a different format, for example.
see the files <freetype/cache/ftcglyph.h> and
"src/cache/ftcglyph.h" for details.
2. The abstract "FTC_ChunkCache" class:
this code is used to implement an abstract "glyph chunk cache".
it's very similar to a FTC_GlyphCache, except that it is capable
of storing several glyph-specific elements per cache node.
it is sub-classed by FTC_SBit_Cache, whose implementation
only consists in code to store a FTC_SBitRec record in each
node element.
you could sub-class it in your application to store small
glyph data, like metrics, glyph names, wathever.
see the files <freetype/cache/ftcchunk.h> and
"src/cache/ftcchunk.h" for details..
Note that the two abstract caches are rather complex because
they use "glyph sets". Each glyph set corresponds to a single
font face + font size combination. both caches are also
glyph-specific, though it is perfectly possible to use
broader selection criterion, here are a few examples:
- caching language coverage maps corresponding to
a given font face + language combination
- caching charmaps, layout tables, and other global
data..
- caching (font_face + font_size) specific "latin1"
ascender + descender
as you can see, a lot is possible with this design :-)

710
docs/convntns.txt
View File

@ -1,710 +0,0 @@
Conventions and Design in the FreeType 2 library
------------------------------------------------
Table of Contents
Introduction
I. Style and Formatting
1. Naming
2. Declarations & Statements
3. Blocks
4. Macros
5. Conventions
II. Design conventions
1. Modularity and Components Layout
2. Configuration and Debugging
III. Usage conventions
1. Error handling
2. Font File I/O
3. Memory management
4. Support for threaded environments
5. Object Management
Introduction
============
This text introduces the many conventions used within the FreeType 2
library code. Please read it before trying any modifications or
extensions of the source code.
I. Style and Formatting
=======================
The following coding rules are extremely important to keep the
library's source code homogeneously. Keep in mind the following
points:
- `Humans read source code, not machines' (Donald Knuth)
The library source code should be as readable as possible, even
by non-C experts. With `readable', two things are meant: First,
the source code should be pleasant to the eye, with sufficient
whitespace and newlines, to not look like a boring stack of
characters stuck to each other. Second, the source should be
_expressive_ enough about its goals. This convention contains
rules that can help the source focus on its purpose, not on a
particular implementation.
- `Paper is the _ultimate_ debugger' (David Turner :-)
There is nothing like sheets of paper (and a large floor) to
help you understand the design of a library you're new to, or to
debug it. The formatting style presented here is targeted at
printing. For example, it is more than highly recommended to
never produce a source line that is wider than 78 columns. More
on this below.
1. Naming
---------
a. Long and expressive labels
Never hesitate to use long labels for your types, variables,
etc.! Except maybe for things like very trivial types, the
longest is the best, as it increases the source's
_expressiveness_. Never forget that the role of a label is to
express the `function' of the entity it represents, not its
implementation!
NOTE: Hungarian notation is NOT expressive, as it sticks the
`type' of a variable to its name. A label like `usFoo'
rarely tells the use of the variable it represents.
And the state of a variable (global, static, dynamic)
isn't helpful anymore.
Conclusion: Avoid Hungarian Notation in FreeType 2.
When forging a name with several nouns
(e.g. `number-of-points'), use an uppercase letter for the first
letter of each word (except the first), like:
numberOfPoints
You are also welcome to introduce underscores `_' in your
labels, especially when sticking large nouns together, as it
`airs' the code greatly. E.g.:
`numberOfPoints' or `number_Of_Points'
`IncredibleFunction' or `Incredible_Function'
And finally, always put a capital letter after an underscore,
except in variable labels that are all lowercase:
`number_of_points' is OK for a variable (_all_ lowercase label)
`incredible_function' is NOT for a function!
^ ^
`Microsoft_windows' is a *shame*!
^ ^
`Microsoft_Windows' isn't really better, but at least its a
^ ^ correct function label within this
convention ;-)
b. Data types
Try to use C types to the very least! Rely on internally
defined equivalent types instead. For example, not all
compilers agree on the sign of `char'; the size of `int' is
platform-specific, etc.
There are equivalents to the most common types in the
`fttypes.h' public header file, like `FT_Short', `FT_UShort',
etc. Using the internal types will guarantee that you won't
need to replace every occurence of `short' or whatever when
compiling on a weird platform or with a weird compiler, and
there are many more than you could think of...
c. Functions
The name of a function should always begin with a capital
letter, as lowercase first letters are reserved for variables.
The name of a function should be, again, _expressive_! Never
hesitate to put long function names in your code: It will make
the code much more readable.
Expressiveness doesn't necessarily imply lengthiness though; for
instance, reading various data types from a file stream is
performed using the following functions defined in the
`ftstream.c' file of the `base' module:
FT_Get_Char(), FT_Get_Short(), FT_Get_Long(), etc.
Which is somewhat more readable than:
cget, sget, usget, lget, etc.
d. Variables
Variable names (at least meant for the public interface) should
always begin with a lowercase letter. Lowercase first letters
are reserved for variables in this convention, as it has been
already explained above. You are still welcome to use long and
expressive variable names.
Something like `numP' can express a number of pixels, porks,
pancakes, and much more... Something like `num_points' won't.
Unfortunately (mostly due to the lazyness of the developers),
short variable names are still used in many parts of the
library. Volunteers are highly welcome to improve this...
As a side note, a field name of a structure counts as a variable
name too.
2. Declarations & Statements
----------------------------
Try to align declarations and assignments in columns, if it proves
logically. For example (taken from `ttraster.c'):
struct TProfile_
{
FT_F26Dot6 X; /* current coordinate during sweep */
PProfile link; /* link to next profile - various purpose */
PLong offset; /* start of profile's data in render pool */
Int flow; /* profile orientation: asc/descending */
Long height; /* profile's height in scanlines */
Long start; /* profile's starting scanline */
UShort countL; /* number of lines to step before this */
/* profile becomes drawable */
PProfile next; /* next profile in same contour, used */
/* during drop-out control */
};
instead of
struct TProfile_
{
FT_F26Dot6 X; /* current coordinate during sweep */
PProfile link; /* link to next profile - various purpose */
PLong offset; /* start of profile's data in render pool */
Int flow; /* profile orientation: asc/descending */
Long height; /* profile's height in scanlines */
Long start; /* profile's starting scanline */
UShort countL; /* number of lines to step before this */
/* profile becomes drawable */
PProfile next; /* next profile in same contour, used */
/* during drop-out control */
};
This comes from the fact that you are more interested in the field
and its function than in its type.
Or:
x = i + 1;
y += j;
min = 100;
instead of
x=i+1;
y+=j;
min=100;
And don't hesitate to separate blocks of declarations with
newlines to `distinguish' logical sections.
E.g., taken from an old source file, in the declarations of the
CMap loader:
long n, num_SH;
unsigned short u;
long off;
unsigned short l;
long num_Seg;
unsigned short* glArray;
long table_start;
int limit, i;
TCMapDir cmap_dir;
TCMapDirEntry entry_;
PCMapTable Plcmt;
PCMap2SubHeader Plcmsub;
PCMap4 Plcm4;
PCMap4Segment segments;
instead of
long n, num_SH;
unsigned short u;
long off;
unsigned short l;
long num_Seg;
unsigned short *glArray;
long table_start;
int limit, i;
TCMapDir cmap_dir;
TCMapDirEntry entry_;
PCMapTable Plcmt;
PCMap2SubHeader Plcmsub;
PCMap4 Plcm4;
PCMap4Segment segments;
3. Blocks
---------
Block separation is done with `{' and `}'. We do not use the K&R
convention which becomes only useful with an extensive use of
tabs. The `{' and its corresponding `}' should always be on the
same column. It makes it easier to separate a block from the rest
of the source, and it helps your _brain_ associate the accolades
easily (ask any Lisp programmer on the topic!).
Use two spaces for the next indentation level.
Never use tabs in FreeType 2 code; their widths may vary with
editors and systems.
Example:
if (condition_test) {
waow mamma;
I'm doing K&R format;
just like the Linux kernel;
} else {
This test failed poorly;
}
should be rather formatted as
if ( condition_test )
{
This code isn't stuck to the condition;
read it on paper, you will find it more;
pleasant to the eye;
}
else
{
Of course, this is a matter of taste;
This is just the way it is in this convention;
and you should follow it to be homogenuous with;
the rest of the FreeType code;
}
4. Macros
---------
Macros should be made of uppercase letters. If a macro label is
forged from several words, it is possible to only uppercasify the
first word, using an underscore to separate the nouns. This is
used in in some files for macros like
GET_UShort(), USE_Stream(), etc.
The role of macros used throughout the engine is explained later
in this document.
5. Conventions
--------------
Currently, FreeType 2 source code uses the following formatting
rules:
. The data type is separated with two spaces from the variable,
structure, or function name:
const char foo;
Usually, the `*' operator is concatenated to the data type:
FT_Int* pointer;
However, when declaring resp. defining an `output' parameter
(i.e. a pointer which will be assigned by the function), the
last `*' must be placed on the right in order to denote this, as
in:
FT_New_Face( FT_Library library,
FT_Face *aface );
where the `*' is used to indicate that `aface' is returned. In
most cases, the name of such an output variable starts with `a'
or `an' (`aface' instead of `face', `anlru' instead of `lru',
etc.), following the English rules of the indefinite article.
. As mentioned above, multiple declarations are vertically
aligned:
FT_Short foo;
FT_Long bar;
FT_GlyphSlot slot;
. Declarations are separated with two blank lines from the
following code. This intentionally disturbs the code flow to
make variable definitions more visible.
{
char x, y;
x = 3;
y = 5;
}
. An opening parenthesis follows a function directly without
space; after a built-in C keyword, one space is used:
x = sin( y );
y = sizeof ( long );
Except for casts, empty parameters, and the closing semicolon,
parentheses are surrounded with space:
x = (char*)( foo + bar );
y = rand();
. Binary operators are surrounded by spaces; unary operators have
no space after it:
x = ( 3 + 4 ) / ( 7 - 2 );
y = -( 3 + 4 ) * 7;
. Array arguments are not surrounded by spaces:
array[3] = array[1] + array[2];
array[4] = array[1 + 3];
. Comma and semicolon have only space at the right side:
if ( x = 0; x < y; x++, y-- )
do_something();
Exception:
for (;;)
{
...
. Don't use
if ( x == y ) a = b;
but
if ( x == y )
a = b;
in general.
. Preprocessor directives are never indented and always start in
the first column.
. All function/structure/variable definitions start at column
three.
. All full-line comments (except the header of a file) start at
column three (even comments for preprocessor directives).
. Labels are sticking out two positions to the left:
switch ( x )
{
case 1:
do_something();
break;
default:
do_nothing();
break;
}
II. Design Conventions
======================
1. Modularity and Components Layout
-----------------------------------
The FreeType 2 engine has been designed with portability in mind.
This implies the ability to compile and run it on a great variety
of systems and weird environments, unlike many packages where the
word strictly means `runs on a bunch of Unix-like systems'. We
have thus decided to stick to the following restrictions:
- The C version is written entirely in ANSI C.
- The library, if compiled with gcc, doesn't produce any warning
with the `-ansi -pedantic' flags. Other compilers with better
checks may produce ANSI warnings -- please report.
(NOTE: It can of course be compiled by an `average' C compiler,
and even by a C++ one.)
- It only requires in its simplest form an ANSI libc to compile,
and no utilities other than a C preprocessor, compiler, and
linker.
- It consists of modules, starting with a `base' module which
provides the API, some auxiliary modules used by the font
drivers, the font driver modules itself, and the rasterizer
modules.
- The very low-level components can be easily replaced by
system-specific ones that do not rely on the standard libc.
These components deal mainly with i/o, memory, and mutex
operations.
- A client application only needs to include one header file named
`freetype.h' to use the engine. Other public header files like
`ftglyph.h' or `ftimage.h' provide functional extensions.
- All configuration options are gathered in two files,
`ftconfig.h' and `ftoption.h'. The former contains the
processor and OS specific configuration options, while the
latter treats options that may be enabled or disabled by the
user to enable and disable various features.
2. Configuration and Debugging
------------------------------
Configuration is covered by the `BUILD' documentation file.
Debugging is controlled by two macros in `ftoption.h',
FT_DEBUG_LEVEL_ERROR and FT_DEBUG_LEVEL_TRACE; don't use them in
code to be released. Check the source code of the `ftview.c'
demonstration program (in the `ft2demos' package) how tracing can
be used and activated.
III. Usage conventions
======================
1. Error Handling
-----------------
Most functions directly return an error code. A return value of 0
(FT_Err_Ok) means that no error occured, while a non-zero other
value indicates a failure of any kind.
We use code like this in FreeType 2:
if ( ( rc = Perform_Action_1( parms_of_1 ) ) ||
( rc = Perform_Action_2( parms_of_2 ) ) ||
( rc = Perform_Action_3( parms_of_3 ) ) )
goto Fail;
which is better but uses assignments within expressions, which are
always delicate to manipulate in C (the risk of writing `=='
exists, and would go unnoticed by a compiler). Moreover, the
assignments are a bit redundant and don't express much things
about the actions performed (they only speak of the error
management issue).
That is why some macros have been defined for the most frequently
used functions. They relate to low-level routines that are called
very often (mainly i/o and memory handling functions). Each macro
produces an implicit assignment to a variable called `error' and
can be used instead as a simple function call. Example:
if ( PERFORM_Action_1( parms_of_1 ) ||
PERFORM_Action_2( parms_of_2 ) ||
PERFORM_Action_3( parms_of_3 ) )
goto Fail;
with
#define PERFORM_Action_1( parms_1 ) \
( error = Perform_Action_1( parms_1 ) )
#define PERFORM_Action_2( parms_1 ) \
( error = Perform_Action_2( parms_1 ) )
#define PERFORM_Action_3( parms_1 ) \
( error = Perform_Action_3( parms_1 ) )
defined in some header file.
There, the developer only needs to define a local `error' variable
and use the macros directly in the code, without caring about the
actual error handling performed. Another advantage is that the
structure of source files remain very similar, even though the
error handling may be different.
This convention is very close to the use of exceptions in
languages like C++, Pascal, Java, etc. where the developer
focuses on the actions to perform, and not on every little error
checking.
2. Font File I/O
----------------
a. Streams
The engine uses `streams' to access the font files. A stream is
a structure containing information used to access files through
a system-specific i/o library.
The default implementation of streams uses the ANSI libc i/o
functions. However, for the sake of embedding in light systems
and independence of a complete C library, it is possible to
re-implement the component for a specific system or OS, letting
it use system calls.
b. Frames
TrueType is tied to the big-endian format, which implies that
reading shorts or longs from the font file may need conversions
depending on the target processor. To be able to easily detect
read errors and allow simple conversion calls or macros, the
engine is able to access a font file using `frames'.
A frame is simply a sequence of successive bytes taken from the
input file at the current position. A frame is pre-loaded into
memory by a call to the `ACCESS_Frame()' macro.
It is then possible to read all sizes of data through the
`GET_xxx()' macros described above.
When all important data is read, the frame can be released by a
call to `FORGET_Frame()'.
The benefits of frames are various. Consider these two
approaches at extracting values:
if ( ( error = Read_Short( &var1 ) ) ||
( error = Read_Long ( &var2 ) ) ||
( error = Read_Long ( &var3 ) ) ||
( error = Read_Short( &var4 ) ) )
return FAILURE;
and
/* Read the next 16 bytes */
if ( ACCESS_Frame( 16L ) )
return error; /* The Frame could not be read */
var1 = GET_Short(); /* extract values from the frame */
var2 = GET_Long();
var3 = GET_Long();
var4 = GET_Short();
FORGET_Frame(); /* release the frame */
In the first case, there are four error assignments with four
checks of the file read. This unnecessarily increases the size
of the generated code. Moreover, you must be sure that `var1'
and `var4' are short variables, `var2' and `var3' long ones, if
you want to avoid bugs and/or compiler warnings.
In the second case, you perform only one check for the read, and
exit immediately on failure. Then the values are extracted from
the frame, as the result of function calls. This means that you
can use automatic type conversion; there is no problem if
e.g. `var1' and `var4' are longs, unlike previously.
Finally, frames are ideal when you are using memory-mapped
files, as the frame is not really `pre-loaded' and never uses
any `heap' space.
IMPORTANT: You CANNOT nest several frame accesses. There is
only one frame available at a time for a specific
instance.
It is also the programmer's responsibility to never
extract more data than was pre-loaded in the frame!
(But you usually know how many values you want to
extract from the file before doing so).
3. Memory Management
--------------------
The library now has a component which uses an interface similar to
malloc()/free().
* FT_Alloc()
To be used like malloc(), except that it returns an error code,
not an address. Its arguments are the size of the requested
block and the address of the target pointer to the `fresh'
block. An error code is returned in case of failure (and this
will also set the target pointer to NULL), 0 in case of success.
FT_Alloc() internally calls the ft_alloc() function defined in
an FT_Memory object. All error checking is done by FT_Alloc()
itself so that ft_alloc() directly calls malloc().
* FT_Realloc()
Similar to FT_Alloc(); it calls realloc() by default.
* FT_Free()
As you may have already guessed, FT_Free() is FT_Alloc()'s
counterpart. It takes as argument the _target pointer's
address_! You should _never_ pass the block's address directly,
i.e. the pointer, to FT_Free().
Similar to FT_Alloc(), FT_Free() does the necessary error
checking and calls free() by default.
As the pointers addresses needed as arguments are typed `void**',
ftmemory.h provides some macros to help use the above functions
more easily, these are:
MEM_Alloc() A version of FT_Alloc() that casts the argument
pointer to (void**). Similar functions are
MEM_Alloc_Array(), MEM_Realloc(), and
MEM_Realloc_Array()
ALLOC() Same as MEM_Alloc(), but with an assignment to a
variable called `error'. See the section `error
handling' above for more info on this. Similar
functions are REALLOC(), ALLOC_ARRAY(), and
REALLOC_ARRAY().
FREE() A version of FT_Free() that casts the argument
pointer to (void**).
MEM_Set() An alias for `memset()', which can be easily
changed to anything else if you wish to use a
different memory manager than the functions
provided by the ANSI libc.
MEM_Copy() An alias of `memcpy()' or `bcopy()' used to move
blocks of memory. You may change it to something
different if necessary (e.g. not using libc).
MEM_Move() An alias of `memmove().' Change its definition if
necessary.
4. Support for threaded environments
------------------------------------
Thread synchronisation has been dropped in FreeType 2. The
library is already re-entrant, and if you really need two threads
accessing the same FT_Library object, you should synchronize
access to it yourself with a simple mutex.
--- end of convntns.txt ---

BIN
docs/design/basic-design.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.0 KiB

160
docs/design/design-1.html
View File

@ -1,160 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>The design of FreeType 2</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
The design of FreeType&nbsp;2
</h1>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
&nbsp;
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-2.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#ccccee"><td>
<h1>
Introduction
</h1>
</td></tr>
</table>
<p>This document provides details on the design and implementation of the
FreeType&nbsp;2 library. Its goal is to allow developers to better
understand the way how FreeType&nbsp;2 is organized, in order to let them
extend, customize, and debug it.</p>
<p>Before anything else, it is important to understand the
<em>purpose</em> of this library, i.e., why it has been written:</p>
<ul>
<li>
<p>It allows client applications to <em>access font files easily</em>,
wherever they could be stored, and as independently of the font format
as possible.</p>
</li>
<li>
<p>Easy <em>retrieval of global font data</em> most commonly found in
normal font formats (i.e. global metrics, encoding/charmaps,
etc.).</p>
</li>
<li>
<p>It allows easy <em>retrieval of individual glyph data</em>
(metrics, images, name, anything else).</p>
</li>
<li>
<p><em>Access to font format-specific "features"</em> whenever
possible (e.g. SFNT tables, Multiple Masters, OpenType Layout tables,
etc.).</p>
</li>
</ul>
<p>Its design has also severely been influenced by the following
requirements:</p>
<ul>
<li>
<p><em>High portability</em>. The library must be able to run on any
kind of environment. This requirement introduces a few drastic
choices that are part of FreeType&nbsp;2's low-level system
interface.</p>
</li>
<li>
<p><em>Extendability</em>. New features should be added with the
least modifications in the library's code base. This requirement
induces an extremely simple design where nearly all operations are
provided by modules.</p>
</li>
<li>
<p><em>Customization</b>. It should be easy to build a version of the
library that only contains the features needed by a specific project.
This really is important when you need to integrate it in a font
server for embedded graphics libraries.</p>
</li>
<li>
<p><em>Compactness</em> and <em>efficiency</em>. The primary target
for this library are embedded systems with low cpu and memory
resources.</p>
</li>
</ul>
<p>The rest of this document is divided in several sections. First, a few
chapters will present the library's basic design as well as the
objects/data managed internally by FreeType&nbsp;2.</p>
<p>A later section is then dedicated to library customization, relating
such topics as system-specific interfaces, how to write your own module
and how to tailor library initialization & compilation to your needs.</p>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
&nbsp;
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-3.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

187
docs/design/design-2.html
View File

@ -1,187 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>The design of FreeType 2</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
The design of FreeType&nbsp;2
</h1>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="design-1.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-3.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#ccccee"><td>
<h1>
I. Components and APIs
</h1>
</td></tr>
</table>
<p>It's better to describe FreeType&nbsp;2 as a collection of
<em>components</em>. Each one of them is a more or less abstract part of
the library that is in charge of one specific task. We will now explicit
the connections and relationships between them.</p>
<p>A first brief description of this system of components could be:</p>
<ul>
<li>
<p>Client applications typically call the FreeType&nbsp;2
<b>high-level API</b>, whose functions are implemented in a single
component called the <em>Base Layer</em>.</p>
</li>
<li>
<p>Depending on the context or the task, the base layer then calls one
or more <em>module</em> components to perform the work. In most
cases, the client application doesn't need to know which module was
called.</p>
</li>
<li>
<p>The base layer also contains a set of routines that are used for
generic things like memory allocation, list processing, i/o stream
parsing, fixed point computation, etc. these functions can also be
called by a module at any time, and they form what is called the
<b>low-level base API</b>.</p>
</li>
</ul>
<p>This is illustrated by the following graphics (note that component
entry points are represented as colored triangles):</p>
<center>
<img src="basic-design.png"
width="394" height="313"
alt="Basic FreeType design">
</center>
<p>Now, a few additional things must be added to complete this
picture:</p>
<ul>
<li>
<p>Some parts of the base layer can be replaced for specific builds of
the library, and can thus be considered as components themselves.
This is the case for the <tt>ftsystem</tt> component, which is in
charge of implementing memory management & input stream access, as
well as <tt>ftinit</tt>, which is in charge of library initialization
(i.e. implementing the <tt>FT_Init_FreeType()</tt> function).</p>
</li>
<li>
<p>FreeType&nbsp;2 comes also with a set of <em>optional
components</em>, which can be used either as a convenience for client
applications (e.g. the <tt>ftglyph</tt> component, used to provide a
simple API to manage glyph images independently of their internal
representation), or to access format-specific features (e.g. the
<tt>ftmm</tt> component used to access and manage Multiple Masters
data in Type&nbsp;1 fonts).</p>
</li>
<li>
<p>Finally, a module is capable of calling functions provided by
another module. This is very useful to share code and tables between
several font driver modules (for example, the <tt>truetype</tt> and
<tt>cff</tt> modules both use the routines provided by the
<tt>sfnt</tt> module).</p>
</li>
</ul>
<p>Hence, a more complete picture would be:</p>
<center>
<img src="detailed-design.png"
width="390" height="429"
alt="Detailed FreeType design">
</center>
<p>Please take note of the following important points:</p>
<ul>
<li>
<p>An optional component can use either the high-level or base API.
This is the case of <tt>ftglyph</tt> in the above picture.</p>
</li>
<li>
<p>Some optional components can use module-specific interfaces ignored
by the base layer. In the above example, <tt>ftmm</tt> directly
accesses the Type&nbsp;1 module to set/query data.</p>
</li>
<li>
<p>A replacable component can provide a function of the high-level
API. For example, <tt>ftinit</tt> provides
<tt>FT_Init_FreeType()</tt> to client applications.</p>
</li>
</ul>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
<a href="design-1.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-3.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

353
docs/design/design-3.html
View File

@ -1,353 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>The design of FreeType 2</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
The design of FreeType&nbsp;2
</h1>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="design-2.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-4.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#ccccee"><td>
<h1>
II. Public Objects and Classes
</h1>
</td></tr>
</table>
<p>We will now explain the abstractions provided by FreeType&nbsp;2 to
client applications to manage font files and data. As you would normally
expect, these are implemented through objects/classes.</p>
<h2>
1. Object Orientation in FreeType&nbsp;2
</h2>
<p>Though written in ANSI&nbsp;C, the library employs a few techniques,
inherited from object-oriented programming, to make it easy to extend.
Hence, the following conventions apply in the FreeType&nbsp;2 source
code:</p>
<ol>
<li>
<p>Each object type/class has a corresponding <em>structure
type</em> <b>and</b> a corresponding <em>structure pointer
type</em>. The latter is called the <em>handle type</em> for the
type/class.</p>
<p>Consider that we need to manage objects of type "foo" in
FreeType&nbsp;2. We would define the following structure and handle
types as follows:</p>
<font color="blue"><pre>
typedef struct FT_FooRec_* FT_Foo;
typedef struct FT_FooRec_
{
// fields for the "foo" class
...
} FT_FooRec;</pre>
</font>
<p>As a convention, handle types use simple but meaningful
identifiers beginning with <tt>FT_</tt>, as in <tt>FT_Foo</tt>,
while structures use the same name with a <tt>Rec</tt> suffix
appended to it ("Rec" is short for "record"). <em>Note that each
class type has a corresponding handle type</em>.</p>
</li>
<li>
<p>Class derivation is achieved internally by wrapping base class
structures into new ones. As an example, we define a "foobar" class
that is derived from "foo". We would do something like:</p>
<font color="blue"><pre>
typedef struct FT_FooBarRec_* FT_FooBar;
typedef struct FT_FooBarRec_
{
// the base "foo" class fields
FT_FooRec root;
// fields proper to the "foobar" class
...
} FT_FooBarRec;</pre>
</font>
<p>As you can see, we ensure that a "foobar" object is also a "foo"
object by placing a <tt>FT_FooRec</tt> at the start of the
<tt>FT_FooBarRec</tt> definition. It is called <b>root</b> by
convention.</p>
<p>Note that a <tt>FT_FooBar</tt> handle also points to a "foo"
object and can be typecasted to <tt>FT_Foo</tt>. Similarly, when
the library returns a <tt>FT_Foo</tt> handle to client applications,
the object can be really implemented as a <tt>FT_FooBar</tt> or any
derived class from "foo".</p>
</li>
</ol>
<p>In the following sections of this chapter, we will refer to "the
<tt>FT_Foo</tt> class" to indicate the type of objects handled through
<tt>FT_Foo</tt> pointers, be they implemented as "foo" or "foobar".</p>
<hr>
<h2>
2. The <tt>FT_Library</tt> class
</h2>
<p>This type corresponds to a handle to a single instance of the
library. Note that the corresponding structure <tt>FT_LibraryRec</tt>
is not defined in public header files, making client applications unable
to access its internal fields.</p>
<p>The library object is the <em>parent</em> of all other objects in
FreeType&nbsp;2. You need to create a new library instance before doing
anything else with the library. Similarly, destroying it will
automatically destroy all its children (i.e. faces and modules).</p>
<p>Typical client applications should call <tt>FT_Init_FreeType()</tt>
in order to create a new library object, ready to be used for further
actions.</p>
<p>Another alternative is to create a fresh new library instance by
calling the function <tt>FT_New_Library()</tt>, defined in the
<tt>&lt;freetype/ftmodule.h&gt;</tt> public header file. This function
will however return an "empty" library instance with no module
registered in it. You can "install" modules in the instance by calling
<tt>FT_Add_Module()</tt> manually.</p>
<p>Calling <tt>FT_Init_FreeType()</tt> is a lot more convenient, because
this function basically registers a set of default modules into each new
library instance. The way this list is accessed and/or computed is
determined at build time, and depends on the content of the
<tt>ftinit</tt> component. This process is explained in details later
in this document.</p>
<p>For now, one should consider that library objects are created with
<tt>FT_Init_FreeType()</tt>, and destroyed along with all children with
<tt>FT_Done_FreeType()</tt>.</p>
<hr>
<h2>
3. The <tt>FT_Face</tt> class
</h2>
<p>A face object corresponds to a single <em>font face</em>, i.e., a
specific typeface with a specific style. For example, "Arial" and
"Arial Italic" correspond to two distinct faces.</p>
<p>A face object is normally created through <tt>FT_New_Face()</tt>.
This function takes the following parameters: an <tt>FT_Library</tt>
handle, a C file pathname used to indicate which font file to open, an
index used to decide which face to load from the file (a single file may
contain several faces in certain cases), and the address of a
<tt>FT_Face</tt> handle. It returns an error code:</p>
<font color="blue"><pre>
FT_Error FT_New_Face( FT_Library library,
const char* filepathname,
FT_Long face_index,
FT_Face* face );</pre>
</font>
<p>In case of success, the function will return&nbsp;0, and the handle
pointed to by the <tt>face</tt> parameter will be set to a non-NULL
value.</p>
<p>Note that the face object contains several fields used to describe
global font data that can be accessed directly by client applications.
For example, the total number of glyphs in the face, the face's family
name, style name, the EM size for scalable formats, etc. For more
details, look at the <tt>FT_FaceRec</tt> definition in the
FreeType&nbsp;2 API Reference.</p>
<hr>
<h2>
4. The <tt>FT_Size</tt> class
</h2>
<p>Each <tt>FT_Face</tt> object <em>has</em> one or more
<tt>FT_Size</tt> objects. A <em>size object</em> is used to store data
specific to a given character width and height. Each newly created face
object has one size, which is directly accessible as
<tt>face-&gt;size</tt>.</p>
<p>The contents of a size object can be changed by calling either
<tt>FT_Set_Pixel_Sizes()</tt> or <tt>FT_Set_Char_Size()</tt>.</p>
<p>A new size object can be created with <tt>FT_New_Size()</tt>, and
destroyed manually with </tt>FT_Done_Size()</tt>. Note that typical
applications don't need to do this normally: they tend to use the
default size object provided with each <tt>FT_Face</tt>.</p>
<p>The public fields of <tt>FT_Size</tt> objects are defined in a very
small structure named <tt>FT_SizeRec</tt>. However, it is important to
understand that some font drivers define their own derivatives of
<tt>FT_Size</tt> to store important internal data that is re-computed
each time the character size changes. Most of the time, these are
size-specific <em>font hints</em>./p>
<p>For example, the TrueType driver stores the scaled CVT table that
results from the execution of the "cvt" program in a <tt>TT_Size</tt>
structure, while the Type&nbsp;1 driver stores scaled global metrics
(like blue zones) in a <tt>T1_Size</tt> object. Don't worry if you
don't understand the current paragraph; most of this stuff is highly
font format specific and doesn't need to be explained to client
developers&nbsp;:-)</p>
<hr>
<h2>
5. The <tt>FT_GlyphSlot</tt> class
</h2>
<p>The purpose of a glyph slot is to provide a place where glyph images
can be loaded one by one easily, independently of the glyph image format
(bitmap, vector outline, or anything else).</p>
<p>Ideally, once a glyph slot is created, any glyph image can be loaded
into it without additional memory allocation. In practice, this is only
possible with certain formats like TrueType which explicitly provide
data to compute a slot's maximum size.</p>
<p>Another reason for glyph slots is that they are also used to hold
format-specific hints for a given glyphs as well as all other data
necessary to correctly load the glyph.</p>
<p>The base <tt>FT_GlyphSlotRec</tt> structure only presents glyph
metrics and images to client applications, while actual implementation
may contain more sophisticated data.</p>
<p>As an example, the TrueType-specific <tt>TT_GlyphSlotRec</tt>
structure contains additional fields to hold glyph-specific bytecode,
transient outlines used during the hinting process, and a few other
things.
The Type&nbsp;1-specific <tt>T1_GlyphSlotRec</tt> structure holds glyph
hints during glyph loading, as well as additional logic used to properly
hint the glyphs when a native Type&nbsp;1 hinter is used.</p>
<p>Finally, each face object has a single glyph slot that is directly
accessible as <tt>face-&gt;glyph</tt>.</p>
<hr>
<h2>
6. The <tt>FT_CharMap</tt> class
</h2>
<p>The <tt>FT_CharMap</tt> type is used as a handle to character map
objects, or <em>charmaps</em>. A charmap is simply some sort of table
or dictionary which is used to translate character codes in a given
encoding into glyph indices for the font.</p>
<p>A single face may contain several charmaps. Each one of them
corresponds to a given character repertoire, like Unicode, Apple Roman,
Windows codepages, and other encodings.</p>
<p>Each <tt>FT_CharMap</tt> object contains a "platform" and an
"encoding" field used to identify precisely the character repertoire
corresponding to it.</p>
<p>Each font format provides its own derivative of
<tt>FT_CharMapRec</tt> and thus needs to implement these objects.</p>
<hr>
<h2>
7. Objects relationships
</h2>
<p>The following diagram summarizes what we have just said regarding the
public objects managed by the library, as well as explicitely describes
their relationships</p>
<center>
<img src="simple-model.png"
width=453 height=378
alt="Simple library model">
</center>
<p>Note that this picture will be updated at the end of the next
chapter, related to <em>internal objects</em>.</p>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
<a href="design-2.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-4.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

361
docs/design/design-4.html
View File

@ -1,361 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>The design of FreeType 2</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
The design of FreeType&nbsp;2
</h1>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="design-3.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-5.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#ccccee"><td>
<h1>
III. Internal Objects and Classes
</h1>
</td></tr>
</table>
<p>Let us have a look now at the <em>internal</em> objects that
FreeType&nbsp;2 uses, i.e., those not directly available to client
applications, and see how they fit into the picture.</p>
<h2>
1. Memory management
</h2>
<p>All memory management operations are performed through three specific
routines of the base layer, namely: <tt>FT_Alloc()</tt>,
<tt>FT_Realloc()</tt>, and <tt>FT_Free()</tt>. Each one of these
functions expects a <tt>FT_Memory</tt> handle as its first
parameter.</p>
<p>The latter is a pointer to a simple object used to describe the
current memory pool/manager. It contains a simple table of
alloc/realloc/free functions. A memory manager is created at library
initialization time by <tt>FT_Init_FreeType()</tt>, calling the function
<tt>FT_New_Memory()</tt> provided by the <tt>ftsystem</tt>
component.</p>
<p>By default, this manager uses the ANSI <tt>malloc()</tt>,
<tt>realloc()</tt>, and <tt>free()</tt> functions. However, as
<tt>ftsystem</tt> is a replaceable part of the base layer, a specific
build of the library could provide a different default memory
manager.</p>
<p>Even with a default build, client applications are still able to
provide their own memory manager by not calling
<tt>FT_Init_FreeType()</tt> but follow these simple steps:</p>
<ol>
<li>
<p>Create a new <tt>FT_Memory</tt> object by hand. The definition
of <tt>FT_MemoryRec</tt> is located in the public file
<tt>&lt;freetype/ftsystem.h&gt;</tt>.</p>
</li>
<li>
<p>Call <tt>FT_New_Library()</tt> to create a new library instance
using your custom memory manager. This new library doesn't yet
contain any registered modules.</p>
</li>
<li>
<p>Register the set of default modules by calling the function
<tt>FT_Add_Default_Modules()</tt> provided by the <tt>ftinit</tt>
component, or manually register your drivers by repeatedly
calling <tt>FT_Add_Module()</tt>.</p>
</li>
</ol>
<hr>
<h2>
2. Input streams
</h2>
<p>Font files are always read through <tt>FT_Stream</tt> objects. The
definition of <tt>FT_StreamRec</tt> is located in the public file
<tt>&lt;freetype/ftsystem.h&gt;</tt>, which allows client developers to
provide their own implementation of streams if they wish so.</p>
<p>The function <tt>FT_New_Face()</tt> will always automatically create
a new stream object from the C&nbsp;pathname given as its second
argument. This is achieved by calling the function
<tt>FT_New_Stream()</tt> provided by the <tt>ftsystem</tt> component.
As the latter is replaceable, the implementation of streams may vary
greatly between platforms.</p>
<p>As an example, the default implementation of streams is located in
the file <tt>src/base/ftsystem.c</tt> and uses the ANSI
<tt>fopen()</tt>, <tt>fseek()</tt>, and <tt>fread()</tt> calls.
However, the Unix build of FreeType&nbsp;2 provides an alternative
implementation that uses memory-mapped files, when available on the host
platform, resulting in a significant access speed-up.</p>
<p>FreeType distinguishes between memory-based and disk-based streams.
In the first case, all data is directly accessed in memory (e.g.
ROM-based, write-only static data and memory-mapped files), while in the
second, portions of the font files are read in chunks called
<em>frames</em>, and temporarily buffered similarly through typical
seek/read operations.</p>
<p>The FreeType stream sub-system also implements extremely efficient
algorithms to very quickly load structures from font files while
ensuring complete safety in the case of a "broken file".</p>
<p>The function <tt>FT_New_Memory_Face()</tt> can be used to directly
create/open a <tt>FT_Face</tt> object from data that is readily
available in memory (including ROM-based fonts).</p>
<p>Finally, in the case where a custom input stream is needed, client
applications can use the function <tt>FT_Open_Face()</tt>, which can
accept custom input streams. This may be useful in the case of
compressed or remote font files, or even embedded font files that need
to be extracted from certain documents.</p>
<p>Note that each face owns a single stream, which is also destroyed by
<tt>FT_Done_Face()</tt>. Generally speaking, it is certainly
<em>not</em> a good idea to keep numerous <tt>FT_Face</tt> objects
opened.</p>
<hr>
<h2>
3. Modules
</h2>
<p>A FreeType&nbsp;2 module is itself a piece of code. However, the
library creates a single <tt>FT_Module</tt> object for each module that
is registered when <tt>FT_Add_Module()</tt> is called.</p>
<p>The definition of <tt>FT_ModuleRec</tt> is not publicly available to
client applications. However, each <em>module type</em> is described by
a simple public structure named <tt>FT_Module_Class</tt>, defined in
<tt>&lt;freetype/ftmodule.h&gt;</tt>, and is described later in this
document:</p>
<p>You need a pointer to an <tt>FT_Module_Class</tt> structure when
calling <tt>FT_Add_Module()</tt>, whose declaration is:</p>
<font color="blue"><pre>
FT_Error FT_Add_Module( FT_Library library,
const FT_Module_Class* clazz );</pre>
</font>
<p>Calling this function will do the following:</p>
<ul>
<li>
<p>It will check whether the library already holds a module object
corresponding to the same module name as the one found in
<tt>FT_Module_Class</tt>.</p>
</li>
<li>
<p>If this is the case, it will compare the module version number to
see whether it is possible to <em>upgrade</em> the module to a new
version. If the module class's version number is smaller than the
already installed one, the function returns immediately. Similarly,
it checks that the version of FreeType&nbsp;2 that is running is
correct compared to the one required by the module.</p>
</li>
<li>
<p>It creates a new <tt>FT_Module</tt> object, using data and flags
of the module class to determine its byte size and how to properly
initialize it.</p>
</li>
<li>
<p>If a module initializer is present in the module class, it will
be called to complete the module object's initialization.</p>
</li>
<li>
<p>The new module is added to the library's list of "registered"
modules. In case of an upgrade, the previous module object is
simply destroyed.</p>
</li>
</ul>
<p>Note that this function doesn't return an <tt>FT_Module</tt> handle,
given that module objects are completely internal to the library (and
client applications shouldn't normally mess with them&nbsp;:-)</p>
<p>Finally, it is important to understand that FreeType&nbsp;2
recognizes and manages several kinds of modules. These will be
explained in more details later in this document, but we will list for
now the following types:</p>
<ul>
<li>
<p><em>Renderer</em> modules are used to convert native glyph images
to bitmaps/pixmaps. FreeType&nbsp;2 comes with two renderer modules
by default: one to generate monochrome bitmaps, the other to
generate high-quality anti-aliased pixmaps.</p>
</li>
<li>
<p><em>Font driver</em> modules are used to support one or more font
formats. Typically, each font driver provides a specific
implementation/derivative of <tt>FT_Face</tt>, <tt>FT_Size</tt>,
<tt>FT_GlyphSlot</tt>, as well as <tt>FT_CharMap</tt>.</p>
</li>
<li>
<p><em>Helper</em> modules are shared by several font drivers. For
example, the <tt>sfnt</tt> module parses and manages tables found in
SFNT-based font formats; it is then used by both the TrueType and
OpenType font drivers.</p>
</li>
<li>
<p>Finally, the <em>auto-hinter</em> module has a specific place in
the library's design, as its role is to process vectorial glyph
outlines, independently of their native font format, to produce
optimal results at small pixel sizes.</p>
</li>
</ul>
<p>Note that every <tt>FT_Face</tt> object is <em>owned</em> by the
corresponding font driver, depending on the original font file's format.
This means that all face objects are destroyed when a module is
removed/unregistered from a library instance (typically by calling the
<tt>FT_Remove_Module()</tt> function).</p>
<p><em>Because of this, you should always take care that no
<tt>FT_Face</tt> object is opened when you upgrade or remove a module
from a library, as this could cause unexpected object deletion!</em></p>
<hr>
<h2>
4. Libraries
</h2>
<p>We now come back to our well-known <tt>FT_Library</tt> object. From
what have been said before, we already know that a library instance owns
at least the following:</p>
<ul>
<li>
<p>A memory manager object (<tt>FT_Memory</tt>), used for all
allocation/releases within the instance.</p>
</li>
<li>
<p>A list of <tt>FT_Module</tt> objects, corresponding to the
"installed" or "registered" modules of the instance. This list can
be changed at any time through <tt>FT_Add_Module()</tt> and
<tt>FT_Remove_Module()</tt>.</p>
</li>
<li>
<p>Remember that face objects are owner by font drivers that are
themselves modules owned by the library.</p>
</li>
</ul>
<p>There is however another object owned by the library instance that
hasn't been described yet: the <em>raster pool</em>.</p>
<p>The <em>raster pool</em> is simply a block of memory of fixed size
that is used internally as a "scratch area" for various memory-hungry
transient operations, avoiding memory allocation. For example, it is
used by each renderer when converting a vectorial glyph outline into a
bitmap (actually, that's where its name comes from&nbsp;:-).</p>
<p>The size of the raster pool is fixed at initialisation time (it
defaults to 16kByte) and cannot be changed at run-time (though we could
fix this if there is a real need for that).</p>
<p>When a transient operation needs more memory than the pool's size, it
can decide to either allocate a heap block as an exceptional condition,
or sub-divide recursively the task to perform in order to never exceed
the pool's threshold.</p>
<p>This extremely memory-conservative behaviour is certainly one of the
keys to FreeType's performance in certain areas (most importantly in
glyph rendering/scanline-conversion).</p>
<hr>
<h2>
5. Summary
</h2>
<p>Finally, the following picture illustrates what has been said in this
section, as well as the previous, by presenting the complete object
graph of FreeType&nbsp;2's base design:</p>
<center>
<img src="library-model.png"
width=411 height=405
alt="Complete library model">
</center>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
<a href="design-3.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-5.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

458
docs/design/design-5.html
View File

@ -1,458 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>The design of FreeType 2</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
The design of FreeType&nbsp;2
</h1>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="design-4.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-6.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#ccccee"><td>
<h1>
IV. Module Classes
</h1>
</td></tr>
</table>
<p>We will now try to explain more precisely the <em>types</em> of modules
that FreeType&nbsp;2 is capable of managing. Note that each one of them
is decribed with more details in the following chapters of this
document.</p>
<ul>
<li>
<p><em>Renderer</em> modules are used to manage scalable glyph images.
This means <em>transforming</em> them, computing their <em>bounding
box</em>, and <em>converting</em> them to either <em>monochrome</em>
or <em>anti-aliased</em> bitmaps</em>.</p>
<p>Note that FreeType&nbsp;2 is capable of dealing with <em>any</em>
kind of glyph images, as long as a renderer module is provided for it.
The library comes by default with two renderers:</p>
<p><table cellpadding=8>
<tr valign=top>
<td>
<tt>raster</tt>
</td>
<td>
<p>Supports the conversion of vectorial outlines (described by a
<tt>FT_Outline</tt> object) to <em>monochrome</em> bitmaps.
</td>
</tr>
<tr valign=top>
<td>
<tt>smooth</tt>
</td>
<td>
<p>Supports the conversion of the same outlines to high-quality
<em>anti-aliased</em> pixmaps (using 256 levels of gray). Note
that this renderer also supports direct span generation.</p>
</td>
</tr>
</table></p>
<li>
<p><em>Font driver</em> modules are used to support one or more
specific font format. By default, FreeType&nbsp;2 comes with the
following font drivers:</p>
<p><table cellpadding=8>
<tr valign=top>
<td>
<tt>truetype</tt>
</td>
<td>
<p>supports TrueType font files</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>type1</tt>
</td>
<td>
<p>supports Postscript Type&nbsp;1 fonts, both in binary
(<tt>.pfb</tt>) or ASCII (<tt>.pfa</tt>) formats, including
Multiple Master fonts.</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>cid</tt>
</td>
<td>
<p>supports Postscript CID-keyed fonts</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>cff</tt>
</td>
<td>
<p>supports OpenType, CFF as well as CEF fonts (CEF is a
derivative of CFF used by Adobe in its SVG viewer)</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>winfonts</tt>
</td>
<td>
<p>supports Windows bitmap fonts (i.e. <tt>.fon</tt> and
<tt>.fnt</tt>)</p>
</td>
</tr>
</table></p>
<p>Note that font drivers can support bitmapped or scalable glyph
images. A given font driver that supports B&eacute;zier outlines
through <tt>FT_Outline</tt> can also provide its own hinter, or rely
on FreeType's <tt>autohinter</tt> module.</p>
</li>
<li>
<p><em>Helper</em> modules are used to hold shared code that is often
used by several font drivers, or even other modules. Here are the
default helpers:</p>
<p><table cellpadding=8>
<tr valign=top>
<td>
<tt>sfnt</tt>
</td>
<td>
used to support font formats based on the <tt>SFNT</tt> storage
scheme: TrueType & OpenType fonts as well as other variants (like
TrueType fonts that only contain embedded bitmaps)
</td>
</tr>
<tr valign=top>
<td>
<tt>psnames</tt>
</td>
<td>
used to provide various useful functions related to glyph names
ordering and Postscript encodings/charsets. For example, this
module is capable of automatically synthetizing a Unicode charmap
from a Type&nbsp;1 glyph name dictionary.
</td>
</tr>
<tr valign=top>
<td>
<tt>psaux</tt>
</td>
<td>
used to provide various useful functions related to Type&nbsp;1
charstring decoding, as this "feature" is needed by the
<tt>type1</tt>, <tt>cid</tt>, and <tt>cff</tt> drivers.
</td>
</tr>
</table></p>
</li>
<li>
<p>Finally, the <em>autohinter</em> module has a specific role in
FreeType&nbsp;2, as it can be used automatically during glyph loading
to process individual glyph outlines when a font driver doesn't
provide it's own hinting engine.</p>
<p>This module's purpose and design is also heavily described on the
FreeType web site.</p>
</li>
</ul>
<p>We will now study how modules are described, then managed by the
library.</p>
<h3>
1. The <tt>FT_Module_Class</tt> structure
</h3>
<p>As described later in this document, library initialization is
performed by calling the <tt>FT_Init_FreeType()</tt> function. The
latter is in charge of creating a new "empty" <tt>FT_Library</tt>
object, then register each "default" module by repeatedly calling the
<tt>FT_Add_Module()</tt> function.</p>
<p>Similarly, client applications can call <tt>FT_Add_Module()</tt> any
time they wish in order to register a new module in the library. Let us
take a look at this function's declaration:</p>
<font color="blue"><pre>
extern FT_Error FT_Add_Module(
FT_Library library,
const FT_Module_Class* clazz );</pre>
</font>
<p>As one can see, this function expects a handle to a library object,
as well as a pointer to a <tt>FT_Module_Class</tt> structure. It
returns an error code. In case of success, a new module object is
created and added to the library. Note by the way that the module isn't
returned directly by the call!</p>
<p>Here the definition of <tt>FT_Module_Class</tt>, with some
explanation. The following code is taken from
<tt>&lt;freetype/ftmodule.h&gt;</tt>:</p>
<font color="blue"><pre>
typedef struct FT_Module_Class_
{
FT_ULong module_flags;
FT_Int module_size;
const FT_String* module_name;
FT_Fixed module_version;
FT_Fixed module_requires;
const void* module_interface;
FT_Module_Constructor module_init;
FT_Module_Destructor module_done;
FT_Module_Requester get_interface;
} FT_Module_Class;</pre>
</font>
<p>A description of its fields:</p>
<p><table cellpadding=8>
<tr valign=top>
<td>
<tt>module_flags</tt>
</td>
<td>
<p>A set of bit flags used to describe the module's category. Valid
values are:</p>
<ul>
<li>
<tt>ft_module_font_driver</tt> if the module is a font driver
</li>
<li>
<tt>ft_module_renderer</tt> if the module is a renderer
</li>
<li>
<tt>ft_module_hinter</tt> if the module is an auto-hinter
</li>
<li>
<tt>ft_module_driver_scalable</tt> if the module is a font
driver supporting scalable glyph formats
</li>
<li>
<tt>ft_module_driver_no_outlines</tt> if the module is a font
driver supporting scalable glyph formats that <em>cannot</em> be
described by an <tt>FT_Outline</tt> object
</li>
<li>
<tt>ft_module_driver_has_hinter</tt> if the module is a font
driver that provides its own hinting scheme/algorithm
</li>
</ul>
</td>
</tr>
<tr valign=top>
<td>
<tt>module_size</tt>
</td>
<td>
<p>An integer that gives the size in <em>bytes</em> of a given
module object. This should <em>never</em> be less than
<tt>sizeof(FT_ModuleRec)</tt>, but can be more if the module needs
to sub-class the base <tt>FT_ModuleRec</tt> class.</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>module_name</tt>
</td>
<td>
<p>The module's internal name, coded as a simple ASCII
C&nbsp;string. There can't be two modules with the same name
registered in a given <tt>FT_Library</tt> object. However,
<tt>FT_Add_Module()</tt> uses the <tt>module_version</tt> field to
detect module upgrades and perform them cleanly, even at
run-time.</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>module_version</tt>
</td>
<td>
<p>A 16.16 fixed float number giving the module's major and minor
version numbers. It is used to determine whether a module needs to
be upgraded when calling <tt>FT_Add_Module()</tt>.</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>module_requires</tt>
</td>
<td>
<p>A 16.16 fixed float number giving the version of FreeType&nbsp;2
that is required to install this module. The default value is
0x20000 for FreeType version&nbsp; 2.0</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>module_requires</tt>
</td>
<td>
<p>Most modules support one or more "interfaces", i.e. tables of
function pointers. This field is used to point to the module's main
interface, if there is one. It is a short-cut that prevents users
of the module to call "get_interface()" each time they need to
access one of the object's common entry points.</p>
<p>Note that is is optional, and can be set to NULL. Other
interfaces can also be accessed through the <tt>get_interface()</tt>
field.</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>module_init</tt>
</td>
<td>
<p>A pointer to a function used to initialize the fields of a fresh
new <tt>FT_Module</tt> object. It is called <em>after</em> the
module's base fields have been set by the library, and is generally
used to initialize the fields of <tt>FT_ModuleRec</tt>
subclasses.</p>
<p>Most module classes set it to NULL to indicate that no extra
initialization is necessary.</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>module_done</tt>
</td>
<td>
<p>A pointer to a function used to finalize the fields of a given
<tt>FT_Module</tt> object. Note that it is called <em>before</em>
the library unsets the module's base fields, and is generally used
to finalize the fields of <tt>FT_ModuleRec</tt> subclasses.</p>
<p>Most module classes set it to NULL to indicate that no extra
finalization is necessary</p>
</td>
</tr>
<tr valign=top>
<td>
<tt>get_interface</tt>
</td>
<td>
<p>A pointer to a function used to request the address of a given
module interface. Set it to NULL if you don't need to support
additional interfaces but the main one.</p>
</td>
</tr>
</table></p>
<h3>
2. The <tt>FT_Module</tt> type
</h3>
<p>The <tt>FT_Module</tt> type is a handle (i.e. a pointer) to a given
module object/instance, whose base structure is given by the internal
<tt>FT_ModuleRec</tt> type. We will intentionally <em>not</em> describe
this structure here, as there is no point to look so far into the
library's design.</p>
<p>When <tt>FT_Add_Module</tt> is called, it first allocates a new
module instance, using the <tt>module_size</tt> class field to determine
its byte size. The function initializes the root <tt>FT_ModuleRec</tt>
field, then calls the class-specific initializer <tt>module_init</tt>
when this field is not set to NULL.</p>
<p>Note that the library defines several sub-classes of
<tt>FT_ModuleRec</tt>, which are, as you could have guessed:</p>
<ul>
<li><p><tt>FT_Renderer</tt> for renderer modules</p>
<li><p><tt>FT_Driver</tt> for font driver modules</p>
<li><p><tt>FT_AutoHinter</tt> for the auto-hinter</p>
</ul>
<p>Helper modules use the base <tt>FT_ModuleRec</tt> type. We will
describe these classes in the next chapters.</p>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
<a href="design-4.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-6.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

94
docs/design/design-6.html
View File

@ -1,94 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>The design of FreeType 2</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
The design of FreeType&nbsp;2
</h1>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="design-5.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
&nbsp;
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#ccccee"><td>
<h1>
TO BE CONTINUED...
</h1>
</td></tr>
</table>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
<a href=design-5.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
&nbsp;
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

BIN
docs/design/detailed-design.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.4 KiB

81
docs/design/index.html
View File

@ -1,81 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>The design of FreeType 2</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
The design of FreeType&nbsp;2
</h1>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="70%">
<tr><td>
<p>This document describes the details of FreeType&nbsp;2's internals.
Read this carefully if you need to understand the innards of the library
in order to hack or extend it.</p>
<table width="100%">
<tr valign=center
bgcolor="#CCCCFF">
<td align=center>
<h2>
Table of Contents
</h2>
</td>
</tr>
</table>
<center>
<table width="80%">
<tr><td>
<h2>
<a href="design-1.html">Introduction</a>
</h2>
<h2>
<a href="design-2.html">I. Components and APIs</a>
</h2>
<h2>
<a href="design-3.html">II. Public Objects and Classes</a>
</h2>
<h2>
<a href="design-4.html">III. Internal Objects and Classes</a>
</h2>
<h2>
<a href="design-5.html">IV. Module Classes</a>
</h2>
</td></tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

BIN
docs/design/library-model.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.2 KiB

639
docs/design/modules.html
View File

@ -1,639 +0,0 @@
<html>
<head><title>FreeType 2 - Modules</title>
<basefont face="Georgia, Arial, Helvetica, Geneva">
<style content="text/css">
P { text-align=justify }
H1 { text-align=center }
H2 { text-align=center }
LI { text-align=justify }
</style>
</head>
<body text=#000000 bgcolor=#ffffff>
<center><table width="500"><tr><td>
<center><h1>FreeType 2 Modules</h1></center>
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
<h1>Introduction</h1>
</td></tr></table>
<p>
The purpose of this document is to present in great details the way
FreeType 2 uses and manages modules. Among other things, it answers
the following questions:</p>
<ul>
<li><p>
what is a module, and what kind of modules are recognized
by the library?
</p></li>
<li><p>
how are modules registered and managed by the library?
</p></li>
<li><p>
how to write a new module, especially new font drivers?
</p></li>
<li><p>
how to select specific modules for a given build of the
library ?
</p></li>
<li><p>
how to compile modules as stand-alone DLLs / shared objects?
</p></li>
</ul>
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
<h1>Overview</h1>
</td></tr></table>
<h3>1. Library design:</h3>
<p>The design of the library is pretty basic:</p>
<ul>
<li><p>
client applications typically call the FreeType 2 high-level
API, whose functions are implemented in a single component
called the <em>Base Layer</em>.
</p></li>
<li><p>
depending on the context or the task, the base
layer then calls one or more modules to perform the
work. In most cases, the client application doesn't
need to know what module was called.
</p></li>
<li><p>
the base layer also contains a set of routines that are
used for generic things like memory allocation, list
processing, i/o stream parsing, fixed point computation,
etc.. these functions can also be called by a module
at any, and they form what is called the "low-level
base API".
</p></li>
</ul>
<p>This is illustrated by the following graphics:</p>
<center><img src="basic-design.png" width="312" height="312"></center>
<p>Note that, however, FT2 comes with a set of <em>optional</em>
components that can be ommited from certain builds, and whose
purpose vary between two situations:</p>
<ul>
<li><p>
some are located on top of the high-level API and provide
convenience functions that make certain things easier
for typical applications. They typically do not call
modules directly, though they can use the low level
base API for certain tasks.</p>
<p>As an example, see the the <tt>ftglyph</tt> component
that is used to manipulate glyph images more conveniently
than the default API.</p>
</p></li>
<li><p>
some other components complement the base layer, by providing
additional routines. Most of them allow client applications
to access format-specific data.</p>
<p>For example, the <tt>ftmm</tt> component provides high-level
functions to specify Multiple Master coordinates for MM Type 1
fonts.</p>
</p></li>
</ul>
<p>This is illustrated by the following graphics:</p>
<center><img src="detailed-design.png" width="365" height="392"></center>
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
<h1>Module Classes</h1>
</td></tr></table>
<p>
The library is capable of managing and using several kinds of
modules:</p>
<ul>
<li><p>
<b>renderer</b> modules are used to convert scalable glyph images
to bitmaps. FreeType 2 comes by default with two of them:</p>
<center><table cellpadding=5><tr valign=top><td>
<p><b><tt>raster1</tt></b></p>
</td><td>
<p>supports the conversion of vectorial outlines (described by a
<tt>FT_Outline</tt> object) to <em>monochrome</em> bitmaps.
</td></tr><tr valign=top><td></p>
<p><b><tt>smooth</tt></b></p>
</td><td>
<p>supports the conversion of the same outlines to high-quality
<em>anti-aliased</em> pixmaps.</p>
</td></tr></table></center>
<p>The specification and interface of renderers is described in
details within this document.</p>
<p>Note that most font formats use <tt>FT_Outline</tt> objects
to describe scalable glyph images. However, FT2 is flexible
and allows specific modules to register and support other
formats. As an example, it's (at least theorically :-) perfectly
possible to write a renderer module that is capable of directly
converting MetaFont glyph definitions to bitmaps or pixmaps !
(of course, this assumes that you also write a MetaFont font
driver to load the definitions :-).
</p></li>
<li><p>
<b>font driver</b> modules are used to support one or more specific
font format. By default, FT2 comes with the following modules:</p>
<center><table cellpadding=5><tr valign=top><td>
<p><tt><b>truetype</b></tt></p>
</td><td>
<p>supports TrueType font files</p>
</td></tr><tr valign=top><td>
<p><tt><b>type1</b></tt></p>
</td><td>
<p>supports Postscript Type 1 fonts, both in binary (.pfb) or ASCII
(.pfa) formats, including Multiple Master fonts.</p>
</td></tr><tr valign=top><td>
<p><tt><b>cid</b></tt></p>
</td><td>
<p>supports Postscript CID-keyed fonts</p>
</td></tr><tr valign=top><td>
<p><tt><b>cff</b></tt></p>
</td><td>
<p>supports OpenType, CFF as well as CEF fonts (CEF is a derivative
of CFF used by Adobe in its SVG viewer).</p>
</td></tr><tr valign=top><td>
<p><tt><b>winfonts</b></tt></p>
</td><td>
<p>supports Windows bitmap fonts (i.e. ".FON" and ".FNT").</p>
</td></tr>
</td></tr></table></center>
<p>Note that font drivers can support bitmapped or scalable glyph
images. A given font driver that supports bezier outlines through
the <tt>FT_Outline</tt> can also provide its own hinter, or rely
on FreeType's <b>autohinter</b> module.
</p></li>
<li><p>
<b>helper</b> modules are used to hold shared code that is
often used by several font drivers, or even other modules.
Here are a few examples of helper modules that come with
FreeType 2:</p>
<table cellpadding=5><tr valign=top><td>
<b><tt>sfnt</tt></b>
</td><td>
used to support font formats based on the "<tt>SFNT</tt>"
storage scheme. This means TrueType & OpenType fonts as
well as other variants (like TrueType fonts that only
contain embedded bitmaps).
</td></tr><tr valign=top><td>
<b><tt>psnames</tt></b>
</td><td>
used to provide various useful function related to glyph
names ordering and Postscript encodings/charsets. For example,
this module is capable of automatically synthetizing a Unicode
charmap from a Type 1 glyph name dictionary.
</td></tr></table></center>
</p></li>
<li><p>
finally, the <b>autohinter</b> module has a specific role in
FreeType 2, as it can be used automatically during glyph loading
to process individual glyph outlines when a font driver doesn't
provide it's own hinting engine.
</p></li>
</ul>
<p>We will now study how modules are described, then managed by
the library.</p>
<h3>1. The <tt>FT_Module_Class</tt> structure:</h3>
<p>As described later in this document, library initialisation is
performed by calling the <tt>FT_Init_FreeType</tt> function. The
latter is in charge of creating a new "empty" <tt>FT_Library</tt>
object, then register each "default" module by repeatedly calling
the <tt>FT_Add_Module</tt> function.</p>
<p>Similarly, client applications can call <tt>FT_Add_Module</tt>
any time they wish in order to register a new module in the library.
Let's take a look at this function's declaration:</p>
<pre><font color="blue">
extern FT_Error FT_Add_Module( FT_Library library,
const FT_Module_Class* clazz );
</font></pre>
<p>As one can see, this function expects a handle to a library object,
as well as a pointer to a <tt>FT_Module_Class</tt> structure. It
returns an error code. In case of success, a new module object is
created and added to the library. Note by the way that the module
isn't returned directly by the call !.</p>
<p>Let's study the definition of <tt>FT_Module_Class</tt>, and explain it
a bit. The following code is taken from
<tt>&lt;freetype/ftmodule.h&gt;</tt>:</p>
<pre><font color="blue">
typedef struct FT_Module_Class_
{
FT_ULong module_flags;
FT_Int module_size;
const FT_String* module_name;
FT_Fixed module_version;
FT_Fixed module_requires;
const void* module_interface;
FT_Module_Constructor module_init;
FT_Module_Destructor module_done;
FT_Module_Requester get_interface;
} FT_Module_Class;
</font></pre>
<p>here's a description of its fields:</p>
<center><table cellpadding=5><tr valign=top><td>
<p><b>module_flags</b></p>
</td><td>
<p>this is a set of bit flags used to describe the module's
category. Valid values are:</p>
<ul>
<li><p>
<b>ft_module_font_driver</b> if the module is a font driver
</p></li>
<li><p>
<b>ft_module_renderer</b> if the module is a renderer
</p></li>
<li><p>
<b>ft_module_hinter</b> if the module is an auto-hinter
</p></li>
<li><p>
<b>ft_module_driver_scalable</b> if the module is a font
driver supporting scalable glyph formats.
</p></li>
<li><p>
<b>ft_module_driver_no_outlines</b> if the module is a
font driver supporting scalable glyph formats that <em>cannot</em>
be described by a <tt>FT_Outline</tt> object
</p></li>
<li><p>
<b>ft_module_driver_has_hinter</b> if the module is a font
driver that provides its own hinting scheme/algorithm
</p></li>
</ul>
</td></tr><tr valign=top><td>
<p><b>module_size</b></p>
</td><td>
<p>an integer that gives the size in <em>bytes</em> of a given module
object. This should <em>never</em> be less than
<tt>sizeof(FT_ModuleRec)</tt>, but can be more when the module
needs to sub-class the base <tt>FT_ModuleRec</tt> class.</p>
</td></tr><tr valign=top><td>
<p><b>module_name</b></p>
</td><td>
<p>this is the module's internal name, coded as a simple ASCII C
string. There can't be two modules with the same name registered
in a given <tt>FT_Library</tt> object. However, <tt>FT_Add_Module</tt>
uses the <b>module_version</b> field to detect module upgrades
and perform them cleanly, even at run-time.</p>
</td></tr><tr valign=top><td>
<p><b>module_version</b></p>
</td><td>
<p>a 16.16 fixed float number giving the module's major and minor
version numbers. It is used to determine wether a module needs
to be upgraded when calling <tt>FT_Add_Module</tt>.</p>
</td></tr><tr valign=top><td>
<p><b>module_requires</b></p>
</td><td>
<p>a 16.16 fixed float number giving the version of FreeType 2 that
is required to install this module. By default, should be 0x20000
for FreeType 2.0</p>
</td></tr><tr valign=top><td>
<p><b>module_requires</b></p>
</td><td>
<p>most modules support one or more "interfaces", i.e. tables of function
pointers. This field is used to point to the module's main interface,
where there is one. It's a short-cut that prevents users of the module
to call "get_interface" each time they need to access one of the object's
common entry points.</p>
<p>Note that is is optional, and can be set to NULL. Other interfaces
can also be accessed through the <b>get_interface</b> field.</p>
</td></tr><tr valign=top><td>
<p><b>module_init</b></p>
</td><td>
<p>this is a pointer to a function used to initialise the fields of
a fresh new <tt>FT_Module</tt> object. It is called <em>after</em> the module's
base fields have been set by the library, and is generally used to
initialise the fields of <tt>FT_ModuleRec</tt> subclasses.</p>
<p>Most module classes set it to NULL to indicate that no extra
initialisation is necessary</p>
</td></tr><tr valign=top><td>
<p><b>module_done</b></p>
</td><td>
<p>this is a pointer to a function used to finalise the fields of
a given <tt>FT_Module</tt> object. Note that it is called <em>before</em> the
library unsets the module's base fields, and is generally used to
finalize the fields of <tt>FT_ModuleRec</tt> subclasses.</p>
<p>Most module classes set it to NULL to indicate that no extra
finalisation is necessary</p>
</td></tr><tr valign=top><td>
<p><b>get_interface</b></p>
</td><td>
<p>this is a pointer to a function used to request the address of
a given module interface. Set it to NULL if you don't need to support
additional interfaces but the main one.</p>
</td></tr><tr valign=top><td>
</td></tr></table></center>
<h3>2. The <tt>FT_Module</tt> type:</h3>
<p>the <tt>FT_Module</tt> type is a handle (i.e. a pointer) to a given
module object / instance, whose base structure is given by the
internal <tt>FT_ModuleRec</tt> type (we will not detail its
structure here).</p>
<p>When <tt>FT_Add_Module</tt> is called, it first allocate a new
module instance, using the <tt><b>module_size</b></tt> class
field to determine its byte size. The function initializes
a the root <tt>FT_ModuleRec</tt> fields, then calls
the class-specific initializer <tt><b>module_init</b></tt>
when this field is not set to NULL.</p>
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
<h1>Renderer Modules</h1>
</td></tr></table>
<p>As said previously, <b>renderers</b> are used to convert scalable
glyph images to bitmaps or pixmaps. Each renderer module is defined
through a <b>renderer class</b>, whose definition is found in the
file <tt>&lt;freetype/ftrender.h&gt;</tt>. However, a few concepts
need to be explained before having a detailed look at this structure.
</p>
<h3>1. Glyph formats:</h3>
<p>Each glyph image that is loaded by FreeType (either through
<tt>FT_Load_Glyph</tt> or <tt>FT_Load_Char</tt>), has a given
<em>image format</em>, described by the field
<tt>face-&gt;glyph-&gt;format</tt>. It is a 32-byte integer that
can take any value. However, the file <tt>&lt;freetype/ftimage.h&gt;</tt>
defines at least the following values:</p>
<center><table cellpadding=5>
<tr valign=top><td>
<tt><b>ft_glyph_format_bitmap</b></tt>
</td><td>
this value is used to indicate that the glyph image is a bitmap or pixmap.
Its content can then be accessed directly from
<tt>face-&gt;glyph-&gt;bitmap</tt> after the glyph was loaded.
</td></tr>
<tr valign=top><td>
<tt><b>ft_glyph_format_outline</b></tt>
</td><td>
this value is used to indicate that the glyph image is a scalable vectorial
outline, that can be described by a <tt>FT_Outline</tt> object. Its content
can be accessed directly from
<tt>face-&gt;glyph-&gt;outline</tt> after the glyph was loaded.
this is the format that is commonly returned by TrueType, Type1 and
OpenType / CFF fonts.
</td></tr>
<tr valign=top><td>
<tt><b>ft_glyph_format_plotter</b></tt>
</td><td>
this value is equivalent to <tt><b>ft_glyph_format_outline</b></tt> except
that the outline stored corresponds to path strokes, instead of filled
outlines. It can be returned from certain Type 1 fonts (notably the Hershey
collection of free fonts).
</td></tr>
<tr valign=top><td>
<tt><b>ft_glyph_format_composite</b></tt>
</td><td>
this value is used to indicate that the glyph image is really a "compound"
of several other "sub-glyphs". This value is only returned when a glyph
is loaded with the <tt><b>FT_LOAD_NO_RECURSE</b></tt> flag. The list of
subglyphs that make up the composite can be accessed directly as
<tt>face-&gt;glyph-&gt;subglyphs</tt> after the glyph was loaded.
</td></tr>
</table></center>
<p>Note that this is only a list of pre-defined formats supported by
FreeType. Nothing prevents an application to install a new font
driver that creates other kinds of glyph images. For example, one
could imagine a MetaFont font driver, that would be capable to
parse font definition files and create in-memory "glyph programs",
that could be returned in <tt>face-&gt;glyph-&gt;other</tt>.</p>
<h3>2. The <tt>FT_Outline</tt> type:</h3>
<p>This structure, which is also defined, and heavily commented, in
the file <tt>&lt;freetype/ftimage.h&gt;</tt>, is used to hold
a scalable glyph image that is made of one or more contours, each
contour being described by line segments or bezier arcs (either
quadratic or cubic). The outline itself is stored in a compact
way that makes processing it easy.</p>
<p>Points are placed in a 2D plane that uses the y-upwards convention,
and their coordinates are stored in 1/64th of pixels (also known
as the 26.6 fixed point format). Pixels correspond to single squares
whose borders are on integer coordinates (i.e. mutiples of 64).
In other words, pixel centers are located on half pixel coordinates.</p>
<p>Outlines can be very easily transformed (translated, rotated, etc..)
before being converted to bitmap, which allows for sophisticated
use of text. FreeType 2 comes by default with two "outline renderer"
modules:</p>
<p><ul>
<li><b>raster1</b>, used to convert them to monochrome bitmaps</li>
<li><b>smooth</b>, used to convert them to high-quality anti-aliased
pixmaps</li>
</ul></p>
<h3>3. Bitmaps and scan-conversion:</h3>
<p>Bitmaps and pixmaps are described through a <tt>FT_Bitmap</tt>
structure, which is defined and heavily commented in
<tt>&lt;freetype/ftimage.h&gt;</tt>
<pre><font color="blue">
typedef struct FT_Renderer_Class_
{
FT_Module_Class root;
FT_Glyph_Format glyph_format;
FTRenderer_render render_glyph;
FTRenderer_transform transform_glyph;
FTRenderer_getCBox get_glyph_cbox;
FTRenderer_setMode set_mode;
FT_Raster_Funcs* raster_class;
} FT_Renderer_Class;
</font></pre>
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
<h1>Font Driver Modules</h1>
</td></tr></table>
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
<h1>Library Initialisation & Dynamic Builds</h1>
</td></tr></table>
<p>By default, all components of FreeType 2 are compiled independently,
then grouped into a single static library file that can be installed
or used directly to compile client applications</p>
<p>Such applications must normally call the <tt>FT_Init_FreeType</tt>
function before using the library. This function is in charge of
two things:</p>
<ul>
<li><p>
First, it creates a <tt>FT_Library</tt> object (by calling
the public function <tt>FT_New_Library</tt>). This new
object is "empty" and has no module registered in it.
</p></li>
<li><p>
Then, it registers all "default modules" by repeatedly calling
<tt>FT_Add_Module</tt>.
</p></li>
</ul>
<p>It is important to notice that the default implementation of
<tt>FT_Init_FreeType</tt>, which is located in the source
file <tt>"src/base/ftinit.c"</tt> always uses a <em>static</em>
list of modules that is generated at compile time from the
configuration file <tt>&lt;freetype/config/ftmodule.h&gt;</tt>.
</p>
<p>There are cases where this may be inadequate. For example, one
might want to compile modules as independent DLLs in a specific
location (like <tt>"/usr/lib/freetype/module/"</tt>), and have
the library initialisation function load the modules dynamically
by parsing the directory's content</p>
<p>This is possible, and we're going to explain how to do it.</p>
<h4>a. Building the library as a DLL (i.e. "shared object" on Unix)</h4>
<p>But first of all, let's explain how to build FreeType 2 as a single
DLL or shared object, i.e. one that includes the base layer, all
default modules and optional components into a single file.</p>
<p>When building dynamic libraries, certain compilers require specific
directives to <em>declare</em> exported DLL entry points. For example, the
"<tt>__cdecl</tt>" directive is required by Win32 compilers, as it forces
the use of the "C" parameter passing convention (instead of "smarter"
schemes, which usually use registers and the stack to pass parameters).</p>
<p>To make matter worse, some of these compilers require the directive
before the function's return type, while some others want it between
the return type and the function's identifier.</p>
<p>To allow such compilations, the <tt>FT_EXPORT_DEF()</tt> macro is
used in all public header files in order to declare each high-level
API function of FreeType 2, as in the following example, taken from
<tt>&lt;freetype/freetype.h&gt;</tt>:</p>
<pre><font color="blue">
FT_EXPORT_DEF(FT_Error) FT_Init_FreeType( void );
</font></pre>
<p>the definition of <tt>FT_EXPORT_DEF(x)</tt> defaults to <tt>"extern x"</tt>,
except when a specific definition is given in the library's system-specific
configuration file <tt>&lt;freetype/config/ftconfig.h&gt;</tt>. This
allows project builders to specify the exact compilation directive
they need.</p>
<p>Similarly, the <tt>FT_EXPORT_FUNC(x)</tt> macro is defined and used to
<em>define</em> exported functions within the FreeType 2 source code.
However, it is only used at compilation time.</p>
<p>Note that on Unix, there is no need for specific exportation directives.
However, the code must be compiled in a special way, named Position
Independent Code ("PIC"), which is normally selected through specific
compiler flags (like "-PIC" with gcc).</p>
<h4>b. Building modules as DLLs</h4>
<p>In order to build modules as dynamic libraries, we first need to compile
the base layer (and optional components) as a single DLL. This is very
similar to the case we just described, except that we also need to
export all functions that are part of the "low level base API",
as these will get called by the modules in various cases.</p>
<p>Similarly to the high-level API, all functions of the low-level base
API are declared in the internal header files of FreeType 2 with the
<tt>BASE_DEF(x)</tt> macro. The latter is similar to
<tt>FT_EXPORT_DEF</tt> and defaults to <tt>"extern x"</tt> unless
you specify a specific definition in
<tt>&lt;freetype/config/ftconfig.h&gt;</tt>.</p>
<p>
<hr>
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
<h1>Conclusion</h1>
</td></tr></table>
</td></tr></table></center>
</body>
</html>

BIN
docs/design/simple-model.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.0 KiB

352
docs/freetype2.html
View File

@ -1,352 +0,0 @@
<html>
<head>
<title>FreeType 2 Introduction</title>
<basefont face="Georgia, Arial, Helvetica, Geneva">
<style content="text/css">
P { text-align=justify }
H1 { text-align=center }
H2 { text-align=center }
LI { text-align=justify }
</style>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<font size=1>http://www.freetype.org</font><p>
<center>
<a href="freetype.html">
<img src="image/freetype.jpg" width=550 height=105 alt="The FreeType Project" border=0></a>
<h1>An Introduction to FreeType 2</h1>
</center>
<center><table width=750 cellspacing=10 cellpadding=30><tr><td>
<hr><p>
DOCUMENT INDEX:<br>
<ul>
<li><a href="#what">What is FreeType 2 ?</a>
<li><a href="#features">Features</a>
<li><a href="#requirements">Requirements</a>
<li><a href="#patents">Patents issues</a>
</ul><p>
<hr><p>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="what">What is FreeType 2 ?</h2>
</td></tr><tr><td>
<p>The FreeType project is a team of volunteers who develop free, portable
and high-quality software solutions for digital typography. We specifically
target embedded systems and focus on bringing small, efficient and
ubiquitous products.</p>
<p>the FreeType 2 library is our new software font engine. It has been
designed to provide the following important features:</p>
<ul>
<li><p>
<b>A universal and simple API to manage font files:</b><br>
<ul>
<p>The FreeType 2 API is simple and easy to use. It supports both
bitmapped and scalable fonts and is well-suited to manage font
files of all formats. Unlike other font libraries, FreeType 2
returns and manages outline font data (images & metrics).</p>
</ul>
</p></li>
<li><p>
<b>Support for several font formats through loadable modules:</b><br>
<ul>
<p>FreeType 2 uses <em>"font drivers"</em>. Each driver is a loadable
module used to support one specific font format. Each driver can also
provide specific extensions used to access format-specific features of
the font.</p>
</ul>
</p></li>
<li><p>
<b>High-quality anti-aliasing:</b><br>
<ul>
<p>FreeType 2 produces etremely smooth outlines at small sizes, with its new
anti-aliasing renderer, which produces bitmaps with 256-levels of gray.
It uses a new algorithm that has been specifically designed to render
small complex shapes (like glyphs) at high speed. Indeed, it's even
faster than the monochrome renderer for small character sizes (under
20 pixels) !!
</p>
</ul>
<li><b>High portability & performance:</b><br>
<ul>
<p>The FreeType 2 source code is written in ANSI C and runs on any
platform with a compliant compiler. Client applications can
provide their own memory manager or input stream to the library
(which means that font files can come from any place: disk,
memory, compressed file, network, etc..).
</p>
</ul>
</ul>
<p>Note that <em>the beta of FreeType 2 is available <b>now</b></em>. For more
info, check our <a href="download.html">Download page</a> or see the source
and its diffs through our <a href="cgi-bin/cvsweb.cgi">CVS Web interface</a>.
</p>
</ul>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="features">Features</h2>
</td></tr><tr><td>
<h3>Supported font formats</h3>
<p>FreeType 2 readily supports the following font formats:</p>
<ul>
<li>TrueType files (.ttf) and collections (.ttc)</li>
<li>Type 1 font files both in ASCII (.pfa) or binary (.pfb) format</li>
<li>Type 1 Multiple Master fonts. The FreeType 2 API also provides
routines to manage design instances easily</li>
<li>Type 1 CID-keyed fonts</li>
<li>OpenType/CFF (.otf) fonts</li>
<li>CFF/Type 2 fonts</li>
<li>Adobe CEF fonts (.cef), used to embed fonts in SVG documents
with the Adobe SVG viewer plugin.</li>
<li>Windows FNT/FON bitmap fonts</li>
</ul>
<p>Note that Apple's TrueType GX fonts are supported as normal TTFs,
(the advanced tables are ignored).</p>
<p>Besides, it's possible to add support for new font formats by providing
a specific <em>font driver</em> module. Modules can be added either at
build time (when recompiling the library), or at <em>run-time</em>;
this allows, for example, applications to register their own
font driver to support program-specific formats.</p>
<h3>Patent-free automatic hinter</h3>
<p>TrueType fonts are normally renderered (hinted) with the help of a
specific bytecode where the behaviour of a few opcodes is patented by
Apple. We're currently in contact with Apple to discuss the importance
of such patents and their use in open source projects like FreeType.
</p>
<p>In the meantime, we have developped our own alternative technology that
is capable of automatically hinting scalable glyph images. It is
now part of the FreeType 2 source tree as the "autohint" module,
and is used to hint glyphs when the bytecode interpreter is disabled
(through a configuration macro when building the engine). Note that
the auto-hinter is also used to handle glyphs in other formats like
CFF and Type 1.</p>
<p>The auto-hinter provides pretty good results (in some cases, it even
significantly improves the output of poorly hinted fonts) but we'll
continue to improve it with each new release of FreeType to achieve
the highest possible quality.</p>
<h3>Modular design:</h3>
<p>The design of FreeType 2 is extremely modular as most features are
supported through optional modules. This means it's easily possible to
only compile the features you need. As each module is between
10 and 20 Kb in size, it's possible to build a bare-bones
font engine that supports anti-aliasing in about 30 Kb !!</p>
<p>Configuration is performed by modifications of only two header
files (one to select global features, another one to select modules)
and don't need tweaking of source code. Note that it is however
possible to provide your own implementation of certain components.</p>
<p>For example, when building on Unix, the engine will automatically
use memory-mapped files when available on the target platform,
thus significantly increasing font file i/o.</p>
<p>Due to its very flexible design, it is possible to add, remove and
upgrade modules at run-time.</p>
<h3>Advanced glyph management</h3>
<p>The API comes with a standard extension used to extract individual
glyph images from font files. These images can be bitmaps, scalable
bezier outlines or even anything else. (e.g. bi-color or metafont
glyphs, as long as they're supported by a module).</p>
<p>Each scalable glyph image can be transformed, measured and
rendered into a monochrome or anti-aliased bitmaps easily
through a uniform interface.
This allows client applications to easily cache glyphs or
perform text rendering effects with minimal difficulty
(look at the FreeType 2 Tutorial to see how to render
rotated text with very few lines of code).
</p>
<h3>Advanced font access</h3>
<p>The FreeType 2 API is useful to retrieve advanced information from
various fonts:</p>
<ul>
<li>vertical metrics are available whenever found in the font file</li>
<li>kerning distances are available when found in the font file. It
is also possible to "attach" a given additional file to a given
font face. This is useful to load kerning distances from an
.afm file into a Type 1 face for example.</li>
<li>provides ASCII glyph names whenever available in the font
(TrueType, OpenType, Type1, etc..)</li>
<li>provides access to important tables for SFNT-based font formats
(i.e. TrueType, OpenType, CEF, etc..), like the name table,
font header, maximum profile, etc...</li>
<li>automatic synthesis of Unicode-based character maps for
those fonts or formats that do not provide one. This is
extremely useful with Type 1 fonts which are normally
limited to a stupid 256-characters encoding.</li>
</ul>
<h3>Simple & clean API</h3>
<p>The FreeType 2 high-level API is simple and straightforward, as it
has been specifically designed to make the most commmon font operations
easy</p>
<p>As a comparison, the number of function calls needed to perform a
the tasks of font face creation/opening and glyph loading/rendering
has been reduced by a factor of 4 !!</p>
<p>The API is also independent of any font-format specific issue, though
it provides standard extensions to access format-specific tables and
information. More extensions can also be easily added through new
modules</p>
<h3>Robust & Portable code</h3>
<p>Because it is written in industry-standard ANSI C, FreeType 2 compiles
on all platforms with a compliant compiler. Because the default build
only relies on the C library, it is free of any system-specific
dependencies, even if it is possible to "enhance" certain components
by providing a specific implementation.</p>
<p>The code doesn't use global or static variables. Client applications
can provide their own memory manager. Font files can be read from
a disk file, memory, or through a client-provided input stream. This
allows to support compressed font files, remote fonts, fonts embedded
in other streams (e.g. Type42 fonts), etc..</p>
<p>An advanced i/o sub-system is used to optimise file access, as well
as reduce memory usage of the library when the file is memory-based
( ROM, RAM, memory-mapped ).</p>
<h3>Open Source & Vendor Independence</h3>
<p>Finally, FreeType 2 is released under its own BSD-like open source
license, one of the less restricting licenses available, and this
means that:</p>
<ul>
<li><p>
It can be included in all kinds of products, be they proprietary
or not.
</p></li>
<li><p>
As any module can be added or replaced anytime, any third party
vendor has the ability to provide its own set of modules (under
its own license) in order to support proprietary font formats or
more advanced features (e.g. a new auto-hinter, or a new
anti-aliasing renderer for LCDs or TV screens).
</p></li>
</ul>
<p>One could even imagine an application using the FreeType 2 API with
a "wrapper" module used to access system-specific fonts (like through
the Windows GDI). This would mean native font support with more portable
application code (as simply changing the wrapper module would be required
to port the application to another system).</p>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="requirements">Requirements</h2>
</td></tr><tr><td>
<p>FreeType 2 is written in ANSI&nbsp;C and should compile with no problems
on a great variety of platforms. We have taken care of removing all
compilation warnings from major compliant compilers. Detailed compilation
instructions are provided in the software archive.</p>
<p>This version of the library has been succesfully compiled and run
under the following systems: Dos, OS/2, Windows, Macintosh, Unix
(including the 64-bits DEC Unix, a.k.a. "True64"). You should not
encounter major problems compiling it on any other kind of platform.
In all cases, contact us if you do.</p>
<p>Note that a small set of demonstration programs is also separately
available. They include a tiny graphics sub-system that is used to
display and show-off the library's capabilities on the following
platforms: X11, MacOS, OS/2 & Windows.</p>
<p>Please visit our <a href="http://www.freetype.org/download.html">
Download section</a> to access the software archives.</p>
</ul>
</td></tr></table>
<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
<h2 align=center><a name="patents">Patents issues</h2>
</td></tr><tr><td>
<p>The FreeType 2 source code includes a TrueType bytecode interpreter that
is covered by the Apple patents. However, this piece of code is never
compiled by default in this release (unlike in previous betas) making
a default build of the library <em>entirely patent-free !!</em></p>
<p>Note that in order to compile the interpreter, one needs to define
the configuration macro <tt><b>TT_CONFIG_OPTION_BYTECODE_INTERPRETER</b></tt> configuration
macro in the file "<tt>ftoption.h</tt>". More details are available in
the software archive. Note that the use of the interpreter is normally
protected by US, UK and French patents. In the event you'd absolutely
need it, you may have to <a href="mailto:patents@apple.org">contact
Apple legal department</a> for licensing conditions, depending on your
location and the places you distribute/sell your products.</p>
<p>Please do not ask us any detailed information regarding licensing, as
we're still discussing with Apple this issue, we're unable to inform
the public of what's currently going on..</p>
</td></tr></table>
<hr>
<p>
<a href="index.html">Back to FreeType homepage</a><p>
</td></tr></table>
</body>
</html>

729
docs/ft2faq.html
View File

@ -1,729 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType 2 FAQ</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<font size=1>http://www.freetype.org</font><p>
<h1 align=center>
<a href="freetype.html">
<img src="image/freetype.jpg"
width=550 height=105
alt="The FreeType Project"
border=0></a>
<h1>The FreeType&nbsp;2 FAQ</h1>
</h1>
<center>
<table width="75%">
<tr><td>
<hr><p>
Document index
<ul>
<li><a href="#general">General</a>
<ul><p>
<li>
<a href="#general-dead">I thought the FreeType project was dead.
Is this true?</a>
</li>
<li>
<a href="#general-long">Why did it take so long to release
FreeType&nbsp;2?</a>
</li>
<li>
<a href="#general-unix">Is FreeType&nbsp;2 a Unix-only
project?</a>
</li>
<li>
<a href="#general-x11">When will X11 support anti-aliased
glyphs?</a>
</li>
<li>
<a href="#general-ft1">Is FreeType&nbsp;2 backwards compatible
to FreeType&nbsp;1.x?</a>
</li>
<li>
<a href="#general-edit">Can I use FreeType&nbsp;2 to edit fonts
or create new ones?</a>
</li>
</p></ul>
</li>
<li><a href="#builds">Compilation & Configuration</a>
<ul><p>
<li>
<a href="#builds-compile">How do I compile the FreeType&nbsp;2
library?</a>
</li>
<li>
<a href="#builds-config">How do I configure my library build?</a>
</li>
<li>
<a href="#builds-modules">How do I select the modules I need?</a>
</li>
<li>
<a href="#builds-flat">How do I compile all FreeType&nbsp;2 files
in a single directory?</a>
</li>
</p></ul>
</li>
<li>
<a href="#autohint">The FreeType&nbsp;2 autohinter</a>
<ul><p>
<li>
<a href="#autohint-license">Under which license is the auto-hinter
released?</a>
</li>
<li>
<a href="#autohint-work">How does auto-hinting work in
FreeType&nbsp;2?</a>
</li>
<li>
<a href="#autohint-cjk">Why doesn't the auto-hinter work well
with CJK fonts?</a>
</li>
</p></ul>
</li>
<li>
<a href="#other">Other questions</a>
<ul><p>
<li>
<a href="#other-color">How can I set the color of text rendered
by FreeType?</a>
</li>
<li>
<a href="#other-depth">Can I use FreeType to draw text on a pixmap
with arbitrary depth?</a>
</li>
<li>
<a href="#other-size">I set the pixel size to 8x8, but the
resulting glyphs are larger than that. Why?</a>
</li>
<li>
<a href="#other-bbox">How can I compute the bounding box of a text
string without loading its glyphs?</a>
</li>
<li>
<a href="#other-antialias">Which anti-aliasing algorithm is
used in the FreeType&nbsp;2 renderer?</a>
</li>
<li>
<a href="#other-opentype">When will FreeType&nbsp;2 support
OpenType?</a>
</li>
</p></ul>
</li>
</ul>
<p><hr></p>
<table width="100%">
<tr bgcolor="#CCCCEE"><td>
<h2 align=center>
<a name="general">General questions & answers
</h2>
</td></tr>
<tr><td>
<a name="general-dead">
<h3>
I.1 I though the FreeType project was dead. Is this true?
</h3>
<p>Well, not exactly&nbsp;:-) It's true that the TrueType patents
issues have been less than a graceful event to handle but it didn't not
really killed the project per se, as Apple hasn't made an official
statement yet regarding the use of the patented "technology" in open
source projects (or other products).</p>
<p>We have thus continued updating FreeType&nbsp;1.x, and started
developing FreeType&nbsp;2 with the idea of providing this time a
completely patent free font engine. However, we largely preferred not
to broadly communicate about it until we've got a satisfying
implementation to show.</p>
<hr>
<a name="general-long">
<h3>
I.2 Why did it take so long to release FreeType&nbsp;2?
</h3>
<p>Several factors come to mind. The first one is that FreeType&nbsp;2
is a much more complex and dense project that was mostly developed
during non-working hours. And surely some important changes in the life
(like marriage, new jobs and kids) of some the FreeType developers
cannot be ignored&nbsp;:-)</p>
<p>A second one is that a first version of the library was designed one
year ago (and already worked with a multitude of font drivers), though
with a design that was judged by its authors as well as beta testers as
not enough flexible or consistent. In short, it worked well but we were
not exactly proud of it (call us perfectionists). It has then be
significantly reworked to become what we are now distributing as
FreeType&nbsp;2</p>
<p>Finally, it would have been hard to distribute such a library without
an alternative technology to replace the patented bytecode interpreter.
This involved significant research work that could only be performed
correctly full-time, and we had to found a company to fund such a
development and still make it available under a BSD-like license. Huge
thanks to <a href="http://www.catharon.com">Catharon Productions,
Inc.</a> for their commitment to this project.</p>
<p>And of course, we added support for more font files, and we will
continue to as long as the specifications are available and that we find
an interest in it. For example, FreeType&nbsp;2 is to date the only
software library available on the market that supports the new Adobe
"CEF" font format.</p>
<hr>
<a name="general-unix">
<h3>
I.3 Is FreeType&nbsp;2 a Unix-only project?
</h3>
<p>Absolutely not, even though many people still seem to think
so&nbsp;:-) FreeType&nbsp;2, just like version&nbsp;1.x, can be compiled
on any platform with an ANSI compiler. Some beta versions of the
library are even heavily used in brand new OSes (see the <a
href="http://www.atheos.cx">AtheOS</a> screenshots for examples).</p>
<p>The library is itself mainly developed on several platforms (Windows
& Linux, though a great deal has also been achieved on OS/2) and the
code is highly generic and modular to adapt even the most strict
environments like low-memory embedded systems.</p>
<hr>
<a name="general-x11">
<h3>
I.4 When will X11/XFree support anti-aliased text?
</h3>
<p>This question isn't exactly related to FreeType as we have no direct
connection to the XFree people, but we have been asked so frequently
about it that it deserves a prominent place in this FAQ&nbsp;:-)</p>
<p>FreeType has been capable of anti-aliasing since version&nbsp;1.0.
The reason why XFree doesn't support it is directly related to the
limitations of the design and specification of X11. More
specifically:</p>
<ul>
<li>
X11 assumes that all glyph images are monochrome bitmaps, hence the
X&nbsp;font library and server are unable to send anything else to
the X&nbsp;server.
</li>
<li>
Even if the X&nbsp;font library/server was able to generate
anti-aliased bitmaps (and this has been already done through
extensions), the X&nbsp;rendering model doesn't allow translucent
composition of "gray" pixmaps onto an arbitrary drawable.
</li>
</ul>
<p>As both the font and rendering models of X11 are limited, it is
basically impossible to draw anti-aliased glyphs without performing
<em>huge</em> hacks within the server.</p>
<p>Note that Keith Packard, from XFree86 fame, has recently started
working on a new rendering model for X11 in order to support new
features (mainly transparency and anti-aliased fonts). This will be
provided through protocol extensions. The question of knowing whether
legacy X applications will be able to display anti-aliased text is still
very uncertain.</p>
<hr>
<a name="general-ft1">
<h3>
I.5 Is FreeType&nbsp;2 backwards compatible with FreeType&nbsp;1.x?
</h3>
<p>Not directly, though we had the project to provide an optional binary
compatibility layer on top of it in order to easily re-link applications
with the new version. However, this idea has been dropped as it is
possible to install and use the two versions independently on any system
(read: no namespace conflicts).</p>
<p>The FreeType&nbsp;2 API is a lot simpler than the one in&nbsp;1.x
while being much more powerful. We thus encourage you to adapt your
source code to it as this should not involve much work.</p>
<hr>
<a name="general-edit">
<h3>
I.6 Can I use FreeType&nbsp;2 to edit fonts or create new ones?
</h3>
<p>The answer is a definitive <b>no</b>, because the library was
specifically designed to <em>read</em> font files with small code size
and very low memory usage.</p>
<p>We thus do not plan to support editing or creation in the font engine
in any way, as this would imply a complete rewrite. This doesn't mean
that we won't introduce a font editing/creation library in the future,
as this really depends on how many people are asking for it (or how much
they would be willing to pay for it), as well as the time of the
FreeType developers.</p>
<p>Do not expect anything in this direction until we officially announce
something though. There are other axes of development for this project
(like text-layout capabilities, glyph caching, etc.) that may be more
important to us at the moment.</p>
</td></tr>
</table>
<br>
<table width="100%">
<tr bgcolor="#CCCCEE"><td>
<h2 align=center>
<a name="builds">Compilation & Configuration
</h2>
</td></tr>
<tr><td>
<a name="builds-compile">
<h3>
II.1 How do I compile the FreeType&nbsp;2 library?
</h3>
<p>The library can be compiled in various ways, and a detailed
documentation is available in the file <tt>freetype2/docs/BUILD</tt>.
However, we will summarize the process to a few cases:</p>
<h4>
a. Using the command-line&nbsp;2 build system
</h4>
<p>The engine comes with a sophisticated build system that is used to
configure and compile a build of the library. You will need <em>GNU
Make</em> installed on your platform (<b>Note:</b> It will
<em>not</em> work with other Make tools).</p>
<p>Basically, you will need to invoke <tt>make</tt> a first time in
the top-level FreeType&nbsp;2 directory in order to set up the build.
This will detect your current platform and choose a configuration
sub-makefile to drive the build. A specific compiler can be selected
on some platforms by providing an additional target. For example, on
Win32:</p>
<ul>
<li>
<b><tt>make visualc</tt></b> will select the Visual&nbsp; C++
compiler
</li>
<li>
<b><tt>make lcc</tt></b> will select the Win32-lcc compiler
</li>
</ul>
<p>Note that on Unix, when the first time make is called, a configure
script located in <tt>freetype2/builds/unix</tt> will be run in order
to automatically detect the platform & compiler.</p>
<p>A summary will be displayed showing the detected platform and
compiler selected. You will then be able to start the build by
invoking <tt>make</tt> a second time. In case of problem, consult the
<tt>BUILD</tt> document.</p>
<h4>
b. Direct compilation
</h4>
<p>You can also directly compile the library from the command line by
using these simple rules:</p>
<ul>
<li>
You should place the directories <tt>freetype2/include</tt> and
<tt>freetype2/src</tt> in your include path in order to compile
any component of the library. You can also add the
system-specific build directory (i.e.
<tt>builds/<em>system</em>/</tt>) in the case where an alternate
implementation of some of the components is available there (e.g.
the memory-mapped i/o implementation on some Unix systems).
</li>
<li>
The components of the library are located in sub-directories of
<tt>src</tt>, for example: <tt>src/base</tt>,
<tt>src/truetype</tt>, etc.
</li>
<li>
Each component is normally compiled through a single C file that
<em>wraps</em> other sources in the component's directory. For
example, you should build the TrueType font driver by compiling
the file <tt>src/truetype/truetype.c</tt>. The list of
C&nbsp;files to compile for a feature-complete build of the
library is given in the <tt>BUILD</tt> document.
</li>
</ul>
<h4>
c. Using a graphical IDE
</h4>
<p>Well, the process is vastly similar to the one described in b.,
except that you need to set the include paths, source code paths, etc.
in dialog boxes before running the compilation.</p>
<hr>
<a name="builds-config">
<h3>
II.2 How do I configure my build of the library?
</h3>
<p>Each build of the library is configured through two header files
located in <tt>include/freetype/config</tt>:</p>
<ul>
<li>
<tt>ftoption.h</tt>
<br>
This file contains various configuration macros whose definition can
be toggled on a per-build basis. Each macro is heavily commented in
this file's comment, and we invite you to refer to it directly.
</li>
<li>
<tt>ftmodule.h</tt>
<br>
This file contains the list of all the modules that are initially
registered (added) when the function <tt>FT_Init_FreeType()</tt> is
called. See the next answer to know how to change it and why it may
be important.
</li>
</ul>
<p>Alternatively, some specific implementations of some FreeType&nbsp;2
components can be provided in a <tt>builds/<em>system</em>/</tt>
directory (e.g. the Unix-specific <tt>ftsystem.c</tt> that uses
memory-mapped file for i/o).</p>
<hr>
<a name="builds-modules">
<h3>
II.3 How do I select the modules I need in my build?
</h3>
<p>The function <tt>FT_Init_FreeType()</tt> creates a new instance of
the FreeType&nbsp;2 library and registers a set of "default" modules
before returning to the calling application. Its default implementation
is in the file <tt>src/base/ftinit.c</tt>.</p>
<p>The list of default modules used by <tt>ftinit.c</tt> is located in
the configuration file <tt>include/freetype/config/ftmodule.h</tt>.
Normally, it is automatically generated by the build system by invoking
the "<tt><b>make modules</b></tt>" command in the top level
FreeType&nbsp;2 directory (Note: this only works with GNU Make; you can
edit the file by hand otherwise). It does so by parsing all
sub-directories of <tt>src</tt> that contain a file named
<tt>module.mk</tt>.</p>
<p>Note that a specific port or project is free to provide its own
implementation of <tt>ftinit.c</tt> in order to ensure a different
initialization sequence. For example, one could do something like:</p>
<ul>
<li>
Compile each module as a shared library (DLL or <tt>.so</tt>) with a
common "entry point" to retrieve a pointer to its module class
(there is already some code that allows this when compiling each
module).
</li>
<li>
Place these modules in a directory like
<tt>/usr/lib/freetype2/modules/</tt>.
</li>
<li>
Provide an implementation of <tt>ftinit.c</tt> that would scan the
directory for valid modules.
</li>
</ul>
<p>This example only emphasizes the flexibility that is left to
developers when building the library.</p>
<hr>
<a name="builds-flat">
<h3>
II.4 How do I compile all FreeType&nbsp;2 files in a single
directory?
</h3>
<p>Some projects may need, for the sake of simplicity or ease of
building, to compile the FreeType&nbsp;2 library with all source files
copied to a single directory. This is possible.</p>
<p>To do so, you have to copy all source files located under
<tt>src</tt> to your own directory (you must retain the include files in
a distinct hierarchy though), then compile each of the FreeType&nbsp;2
component with the macro <tt>FT_FLAT_COMPILE</tt>. This will change the
way <tt>#include</tt> works during the build.</p>
</td></tr>
</table>
<br>
<table width="100%">
<tr bgcolor="#CCCCEE"><td>
<h2 align=center>
<a name="autohint">The FreeType&nbsp;2 auto-hinter
</h2>
</td></tr>
<tr><td>
<a name="autohint-license">
<h3>
III.1 Under which license is the FreeType&nbsp;2 auto-hinter released?
</h3>
<p>The auto-hinter was initially designed and implemented under contract
for <a href="http://www.catharon.com">Catharon Productions, Inc</a>
which gladly accepted to released it under an open-source license
compatible with the FreeType one.</p>
<p>This license can be found in
<tt>src/autohint/CatharonLicense.txt</tt> and requires that you cite
Catharon Productions in your documentation (just like you do with
FreeType) when using the auto-hinting module.</p>
<p>Other than that, you still have the same freedom than with the good
old FreeType license. Enjoy!</p>
<hr>
<a name="autohint-work">
<h3>
III.2 How does the auto-hinter work?
</h3>
<p>Well, a complete description would be difficult. Have a look at the
dedicated <a href="autohinting/index.html">auto-hinter pages</a> on the
FreeType site, as they describe most of its details with graphics and
explanations. You could also look at the source code if you want
to&nbsp;:-)</p>
<p>To give a few details, the auto-hinter is used to perform
grid-fitting on scalable font formats that use B&eacute;zier outlines as
their primary glyph image format (this means nearly all scalable font
formats today). If a given font driver doesn't provide its own hinter,
the auto-hinter is used by default. If a format-specific hinter is
provided, it is still possible to use the auto-hinter using the
<tt>FT_LOAD_FORCE_AUTOHINT</tt> bit flag when calling
<tt>FT_Load_Glyph()</tt>.</p>
<p>The auto-hinter currently doesn't use external hints to do its job,
as it automatically computes global metrics (when it "opens" a font for
the first time) and glyph "hints" from their outline. Note that we plan
the ability to specify external hints, given that it is based on a
constraint system. That could be used to support native hints in
Type&nbsp;1/Type&nbsp;2 fonts, for example.</p>
<hr>
<a name="autohint-cjk">
<h3>
III.3 Why does the auto-hinter doesn't work correctly with CJK
fonts?
</h3>
<p>The auto-hinter was first designed to manage and hint Latin-based
fonts, as they consist of most of the fonts available today. It doesn't
hint Asian fonts, as well as a few other complex scripts, because we
didn't put enough research on the topic yet. Hinting CJK isn't really
more difficult than Latin, just different, with a set of different
constraints (basically, more distortion of glyphs is acceptable as long
as certain features like triple-stem positions are respected more
strictly).</p>
<p>We thus plan to handle such a case in the near future. Please be
patient.</p>
</td></tr>
</table>
<br>
<table width="100%">
<tr bgcolor="#CCCCEE"><td>
<h2 align=center>
<a name="other">Other questions
</h2>
</td></tr>
<tr><td>
<a name="other-depth">
<h3>
IV.1 Can I use FreeType to draw text on a pixmap with arbitratry depth?
</h3>
<p>Not directly, as FreeType is a font library, not a general purpose
graphics library or text rendering service. However, note that the
anti-aliased renderer allows you to convert a vectorial glyph outline
into a list of "spans" (i.e. horizontal pixel segments with same
coverage) that can be rendered through user-provided callbacks.</p>
<p>By providing the appropriate span callback, you can render
anti-aliased text to any kind of surface. You can also use any color or
fill pattern/image if you want to. This process is called <em>direct
rendering</em>. For more information, please read the documentation
contained in the following files:</p>
<ul>
<li>
<p><tt>&lt;freetype/ftimage.h&gt;</tt> contains the definition of
the <tt>FT_Raster_Params</tt> type used with direct rendering.</p>
</li>
<li>
<p><tt>&lt;freetype/ftoutln.h&gt;</tt> contains the definition of
the <tt>FT_Outline_Render()</tt> function that can be used to
convert vectorial outlines to span lists.</p>
</li>
</ul>
<p>Here's some code that uses them:</p>
<font color="blue"><pre>
FT_Raster_Params params;
FT_Outline outline;
... load vectorial glyph in "outline" ...
params.flags = ft_raster_flag_aa | ft_raster_flag_direct;
params.gray_spans = (FT_Raster_Span_Func)your_own_span_function_here;
params.user = your_own_data_pointer;
error = FT_Outline_Render( library, &amp;outline, &amp;params );</pre>
</font>
<p>Note that direct rendering is <em>not</em> available with monochrome
output, as the current renderer uses a two-pass algorithm to generate
glyphs with correct drop-out control.</p>
<hr>
<a name="other-color">
<h3>
IV.2 How can I set the color of text rendered by FreeType?
</h3>
<p>Basically, you can't do that, because FreeType is simply a font
library. In general, you will need to use your favorite graphics
library to draw the FreeType glyphs with the appropriate color.</p>
<p>Note that for anti-aliased glyphs, you can "set the color" by using
<em>direct rendering</em> as described in <a href="#other-depth">this
answer</a>.</p>
<hr>
<a name="other-size">
<h3>
IV.3 I set the pixel size to 8x8, but the resulting glyphs are larger
(or smaller) than that. Why?
</h3>
<p>A lot of people have difficulties to understand this topic, because
they think of glyphs as fixed-width resp. fixed-height "cells", like
those of fonts used in terminals/consoles. This assumption is simply
not valid with most "modern" font formats, even bitmapped-based ones
like <tt>PCF</tt> or <tt>BDF</tt>.</p>
<p>Be aware that the <em>character size</em> that is set either through
<tt>FT_Set_Char_Size()</tt> or <tt>FT_Set_Pixel_Sizes()</tt> isn't
directly related to the dimension of the glyph bitmaps generated.</p>
<p>Rather, the character size is indeed the size of <em>an abstract
square</em>, called the <em>EM</em>, used by typographers to design
fonts. Scaling two distinct fonts to the same character size, be it
expressed in points or pixels, will generally result in bitmaps with
<em>distinct dimensions</em>!</p>
<p>Note that historically, the EM corresponded to the width of a capital
"M" in Latin typefaces. However, later improvements in typography led
to designs that greatly detract from this rule. Today, it is not
possible to connect the EM size to a specific font "feature" in a
reliable way.</p>
<hr>
<a name="other-bbox">
<h3>
IV.4 How can I compute the bounding box of a given string of text
without loading its glyphs before?
</h3>
<p>A lot of people want to be able to compute the size in pixels of a
simple string of text with minimal overhead. For example, that can be
useful to draw centered text within a button. (to be continued...)</p>
<hr>
<a name="other-antialias">
<h3>
IV.5 Which anti-aliasing algorithm is used by FreeType&nbsp;2?</h3>
<p>The algorithm has been specifically designed for FreeType. It is
based on ideas that were originally found in the implementation of the
<a href="http://www.levien.com/libart">libArt</a> graphics library to
compute the <em>exact pixel coverage</em> of a vector image with
absolutely no sub-sampling/filtering.</p>
<p>However, these two implementations are radically distinct and use
vastly different models. The FreeType&nbsp;2 renderer is optimized
specifically for rendering small complex shapes, like glyphs, at very
high speed while using very few memory; while libArt shines at general
shape/polygon processing, especially large ones.</p>
<p>The FreeType&nbsp;2 anti-aliasing renderer is indeed <em>faster</em>
than the monochrome renderer for small character sizes (typically
&lt;20&nbsp;pixels). The reason is that the monochrome renderer must
perform two passes on the outline in order to perform drop-out control
according to the TrueType specification (we could drop this requirement
later though).</p>
<p>We will try to document its design in a later document, though this
is not a priority for now.</p>
<hr>
<a name="other-opentype">
<h3>
IV.6 When will FreeType&nbsp;2 support OpenType?
</h3>
<p>Well, the engine already reads OpenType/CFF files perfectly. What it
doesn't do is handle "OpenType Layout" tables yet.</p>
<p>FreeType&nbsp;1 comes with a set of extensions that are used to load
and manage OpenType Layout tables. It even has a demonstration program
named <tt>ftstrtto</tt> to show its capabilities.</p>
<p>For FreeType&nbsp;2, we have decided that the layout operations
provided through these tables are better placed in a specific
text-layout library, (many people having asked for such a thing). This
new engine will not depend on FreeType2 explicitly and will be developed
as a separate project. We plan to announce it in a few weeks with all
gory details, once the definitive 2.0&nbsp;release of FreeType has been
made.</p>
</td></tr>
</table>
<p><hr></p>
<a href="index.html">Back to FreeType homepage</a><p>
</td></tr>
</table>
</body>
</html>

BIN
docs/glyphs/Image1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.9 KiB

BIN
docs/glyphs/Image2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.0 KiB

BIN
docs/glyphs/Image3.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.9 KiB

BIN
docs/glyphs/Image4.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.5 KiB

BIN
docs/glyphs/bbox1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.8 KiB

BIN
docs/glyphs/bbox2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.7 KiB

BIN
docs/glyphs/body_comparison.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.4 KiB

BIN
docs/glyphs/bravo_kerned.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.3 KiB

BIN
docs/glyphs/bravo_unkerned.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.3 KiB

BIN
docs/glyphs/clipping.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.9 KiB

BIN
docs/glyphs/down_flow.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.2 KiB

199
docs/glyphs/glyphs-1.html
View File

@ -1,199 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType Glyph Conventions</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
FreeType Glyph Conventions
</h1>
<h2 align=center>
Version&nbsp;2.1
</h2>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
&nbsp;
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-2.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#CCCCFF"
valign=center><td>
<h2>
I. Basic typographic concepts
</h2>
</td></tr>
</table>
<a name="section-1">
<h3>
1. Font files, format and information
</h3>
<p>A font is a collection of various character images that can be used
to display or print text. The images in a single font share some common
properties, including look, style, serifs, etc. Typographically
speaking, one has to distinguish between a <em>font family</em> and its
multiple <em>font faces</em>, which usually differ in style though come
from the same template.</p>
For example, "Palatino Regular" and "Palatino Italic" are two distinct
<em>faces</em> from the same famous <em>family</em>, called "Palatino"
itself.</p>
<p>The single term <em>font</em> is nearly always used in ambiguous ways
to refer to either a given family or given face, depending on the
context. For example, most users of word-processors use "font" to
describe a font family (e.g. "Courier", "Palatino", etc.); however most
of these families are implemented through several data files depending
on the file format: For TrueType, this is usually one per face (i.e.
<tt>arial.ttf</tt> for "Arial Regular", <tt>ariali.ttf</tt> for "Arial
Italic", etc.). The file is also called a "font" but really contains a
font face.</p>
<p>A <em>digital font</em> is thus a data file that may contain <em>one
or more font faces</em>. For each of these, it contains character
images, character metrics, as well as other kind of information
important to the layout of text and the processing of specific character
encodings. In some awkward formats, like Adobe's Type&nbsp;1, a single
font face is described through several files (i.e. one contains the
character images, another one the character metrics). We will ignore
this implementation issue in most parts of this document and consider
digital fonts as single files, though FreeType&nbsp;2.0 is able to
support multiple-files fonts correctly.</p>
<p>As a convenience, a font file containing more than one face is called
a <em>font collection</em>. This case is rather rare but can be seen in
many Asian fonts, which contain images for two or more representation
forms of a given scripts (usually for horizontal and vertical
layout.</p>
<a name="section-2">
<h3>
2. Character images and mappings
</h3>
<p>The character images are called <em>glyphs</em>. A single character
can have several distinct images, i.e. several glyphs, depending on
script, usage or context. Several characters can also take a single
glyph (good examples are Roman ligatures like "fi" and "fl" which can be
represented by a single glyph). The relationships between characters
and glyphs can be very complex, but won't be discussed in this document.
Moreover, some formats use more or less awkward schemes to store and
access glyphs. For the sake of clarity, we only retain the following
notions when working with FreeType:</p>
<ul>
<li>
<p>A font file contains a set of glyphs; each one can be stored as a
bitmap, a vector representation or any other scheme (most scalable
formats use a combination of mathematical representation and control
data/programs). These glyphs can be stored in any order in the font
file, and is typically accessed through a simple glyph index.</p>
</li>
<li>
<p>The font file contains one or more tables, called a <em>character
map</em> (or charmap in short), which is used to convert character
codes for a given encoding (e.g. ASCII, Unicode, DBCS, Big5, etc..)
into glyph indices relative to the font file. A single font face
may contain several charmaps. For example, most TrueType fonts
contain an Apple-specific charmap as well as a Unicode charmap,
which makes them usable on both Mac and Windows platforms.</p>
</li>
</ul>
<a name="section-3">
<h3>
3. Character and font metrics
</h3>
<p>Each glyph image is associated with various metrics which are used to
describe how it must be placed and managed when rendering text. These
are described in more details in section&nbsp;III; they relate to glyph
placement, cursor advances as well as text layout. They are extremely
important to compute the flow of text when rendering a string of
text.</p>
<p>Each scalable format also contains some global metrics, expressed in
notional units, to describe some properties of all glyphs in the same
face. Examples for global metrics are the maximum glyph bounding box,
the ascender, descender and text height for the font.</p>
<p>Though these metrics also exist for non-scalable formats, they only
apply for a set of given character dimensions and resolutions, and are
usually expressed in pixels.</p>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
&nbsp;
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-2.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

397
docs/glyphs/glyphs-2.html
View File

@ -1,397 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType Glyph Conventions</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
FreeType Glyph Conventions
</h1>
<h2 align=center>
Version&nbsp;2.1
</h2>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-1.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-3.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#CCCCFF"
valign=center><td>
<h2>
II. Glyph outlines
</h2>
</td></tr>
</table>
<p>This section describes the way scalable representations of glyph
images, called outlines, are used by FreeType as well as client
applications.</p>
<a name="section-1">
<h3>
1. Pixels, points and device resolutions
</h3>
<p>Though it is a very common assumption when dealing with computer
graphics programs, the physical dimensions of a given pixel (be it for
screens or printers) are not squared. Often, the output device, be it a
screen or printer, exhibits varying resolutions in both horizontal and
vertical direction, and this must be taken care of when rendering
text.</p>
<p>It is thus common to define a device's characteristics through two
numbers expressed in <em>dpi</em> (dots per inch). For example, a
printer with a resolution of 300x600&nbsp;dpi has 300&nbsp;pixels per
inch in the horizontal direction, and 600 in the vertical one. The
resolution of a typical computer monitor varies with its size
(15"&nbsp;and 17"&nbsp;monitors don't have the same pixel sizes at
640x480), and of course the graphics mode resolution.</p>
<p>As a consequence, the size of text is usually given in
<em>points</em>, rather than device-specific pixels. Points are a
simple <em>physical</em> unit, where 1&nbsp;point&nbsp;=&nbsp;1/72th of
an inch, in digital typography. As an example, most Roman books are
printed with a body text whose size is somewhere between 10 and
14&nbsp;points.</p>
<p>It is thus possible to compute the size of text in pixels from the
size in points with the following formula:</p>
<center>
<tt>pixel_size = point_size * resolution / 72</tt>
</center>
<p>The resolution is expressed in <em>dpi</em>. Since horizontal and
vertical resolutions may differ, a single point size usually defines a
different text width and height in pixels.</p>
<p><em>Unlike what is often thought, the "size of text in pixels" is not
directly related to the real dimensions of characters when they are
displayed or printed. The relationship between these two concepts is a
bit more complex and relate to some design choices made by the font
designer. This is described in more detail in the next sub-section (see
the explanations on the EM square).</em></p>
<a name="section-2">
<h3>
2. Vectorial representation
</h3>
<p>The source format of outlines is a collection of closed paths called
<em>contours</em>. Each contour delimits an outer or inner
<em>region</em> of the glyph, and can be made of either <em>line
segments</em> or <em>B&eacute;zier arcs</em>.</p>
<p>The arcs are defined through <em>control points</em>, and can be
either second-order (these are <em>conic</em> B&eacute;ziers) or
third-order (<em>cubic</em> B&eacute;ziers) polynomials, depending on
the font format. Note that conic B&eacute;ziers are usually called
<em>quadratic</em> B&eacute;ziers in the literature. Hence, each point
of the outline has an associated flag indicating its type (normal or
control point). And scaling the points will scale the whole
outline.</p>
<p>Each glyph's original outline points are located on a grid of
indivisible units. The points are usually stored in a font file as
16-bit integer grid coordinates, with the grid origin's being at (0,0);
they thus range from -16384 to&nbsp;16383. (Even though point
coordinates can be floats in other formats such as Type&nbsp;1, we will
restrict our analysis to integer values for simplicity).</p>
<p><em>The grid is always oriented like the traditional mathematical
two-dimensional plane, i.e., the <i>X</i>&nbsp;axis from the left to the
right, and the <i>Y</i>&nbsp;axis from bottom to top.</em></p>
<p>In creating the glyph outlines, a type designer uses an imaginary
square called the <em>EM square</em>. Typically, the EM square can be
thought of as a tablet on which the characters are drawn. The square's
size, i.e., the number of grid units on its sides, is very important for
two reasons:</p>
<ul>
<li>
<p>It is the reference used to scale the outlines to a given text
dimension. For example, a size of 12pt at 300x300&nbsp;dpi
corresponds to 12*300/72&nbsp;=&nbsp;50&nbsp;pixels. This is the
size the EM square would appear on the output device if it was
rendered directly. In other words, scaling from grid units to
pixels uses the formula:</p>
<p><center>
<tt>pixel_size = point_size * resolution / 72</tt><br>
<tt>pixel_coord = grid_coord * pixel_size / EM_size</tt>
</center></p>
</li>
<li>
<p>The greater the EM size is, the larger resolution the designer
can use when digitizing outlines. For example, in the extreme
example of an EM size of 4&nbsp;units, there are only 25&nbsp;point
positions available within the EM square which is clearly not
enough. Typical TrueType fonts use an EM size of 2048&nbsp;units;
Type&nbsp;1 PostScript fonts have a fixed EM size of 1000&nbsp;grid
units but point coordinates can be expressed as floating values.</p>
</li>
</ul>
<p>Note that glyphs can freely extend beyond the EM square if the font
designer wants so. The EM is used as a convenience, and is a valuable
convenience from traditional typography.</p>
<p>Grid units are very often called <em>font units</em> or <em>EM
units</em>.</p>
<p><em>As said before, <tt>pixel_size</tt> computed in the above formula
does not relate directly to the size of characters on the screen. It
simply is the size of the EM square if it was to be displayed. Each
font designer is free to place its glyphs as it pleases him within the
square. This explains why the letters of the following text have not
the same height, even though they are displayed at the same point size
with distinct fonts:</em>
<p><center>
<img src="body_comparison.png"
height=40 width=580
alt="Comparison of font heights">
</center></p>
<p>As one can see, the glyphs of the Courier family are smaller than
those of Times New Roman, which themselves are slightly smaller than
those of Arial, even though everything is displayed or printed at a size
of 16&nbsp;points. This only reflects design choices.</p>
<a name="section-3">
<h3>
3. Hinting and Bitmap rendering
</h3>
<p>The outline as stored in a font file is called the "master" outline,
as its points coordinates are expressed in font units. Before it can be
converted into a bitmap, it must be scaled to a given size/resolution.
This is done through a very simple transformation, but always creates
undesirable artifacts, e.g. stems of different widths or heights in
letters like "E" or "H".</p>
<p>As a consequence, proper glyph rendering needs the scaled points to
be aligned along the target device pixel grid, through an operation
called <em>grid-fitting</em> (often called<em>hinting</em>). One of its
main purposes is to ensure that important widths and heights are
respected throughout the whole font (for example, it is very often
desirable that the "I" and the "T" have their central vertical line of
the same pixel width), as well as to manage features like stems and
overshoots, which can cause problems at small pixel sizes.</p>
<p>There are several ways to perform grid-fitting properly; most
scalable formats associate some control data or programs with each glyph
outline. Here is an overview:</p>
<ul>
<li>
<p><em>explicit grid-fitting</em></p>
<p>The TrueType format defines a stack-based virtual machine, for
which programs can be written with the help of more than
200&nbsp;opcodes (most of these relating to geometrical operations).
Each glyph is thus made of both an outline and a control program to
perform the actual grid-fitting in the way defined by the font
designer.</p>
</li>
<li>
<p><em>implicit grid-fitting (also called hinting)</em></p>
<p>The Type&nbsp;1 format takes a much simpler approach: Each glyph
is made of an outline as well as several pieces called
<em>hints</em> which are used to describe some important features of
the glyph, like the presence of stems, some width regularities, and
the like. There aren't a lot of hint types, and it is up to the
final renderer to interpret the hints in order to produce a fitted
outline.</p>
</li>
<li>
<p><em>automatic grid-fitting</em></p>
<p>Some formats simply include no control information with each
glyph outline, apart from metrics like the advance width and height.
It is then up to the renderer to "guess" the more interesting
features of the outline in order to perform some decent
grid-fitting.</p>
</li>
</ul>
<p>The following table summarises the pros and cons of each scheme.</p>
<center>
<table width="90%"
bgcolor="#CCCCCC"
cellpadding=5>
<tr bgcolor="#999999">
<td>
<center>
<b>grid-fitting scheme</b>
</center>
</td>
<td>
<center>
<b>advantages</b>
</center>
</td>
<td>
<center>
<b>disadvantages</b>
</center>
</td>
</tr>
<tr>
<td valign=top>
<center>
<b>explicit</b>
</center>
</td>
<td valign=top>
<p><b>Quality.</b> Excellent results at small sizes are possible.
This is very important for screen display.</p>
<p><b>Consistency.</b> All renderers produce the same glyph
bitmaps.</p>
</td>
<td valign=top>
<p><b>Speed.</b> Intepreting bytecode can be slow if the glyph
programs are complex.</p>
<p><b>Size.</b> Glyph programs can be long.</p>
<p><b>Technical difficulty.</b>
It is extremely difficult to write good hinting
programs. Very few tools available.</p>
</td>
</tr>
<tr>
<td valign=top>
<center>
<b>implicit</b>
</center>
</td>
<td valign=top>
<p><b>Size.</b> Hints are usually much smaller than explicit glyph
programs.</p>
<p><b>Speed.</b>
Grid-fitting is usually a fast process.</p>
</td>
<td valign=top>
<p><b>Quality.</b> Often questionable at small sizes. Better with
anti-aliasing though.</p>
<p><b>Inconsistency.</b> Results can vary between different
renderers, or even distinct versions of the same engine.</p>
</td>
</tr>
<tr>
<td valign=top>
<center>
<b>automatic</b>
</center>
</td>
<td valign=top>
<p><b>Size.</b> No need for control information, resulting in
smaller font files.</p>
<p><b>Speed.</b> Depends on the grid-fitting algorithm. Usually
faster than explicit grid-fitting.</p>
</td>
<td valign=top>
<p><b>Quality.</b> Often questionable at small sizes. Better with
anti-aliasing though.</p>
<p><b>Speed.</b> Depends on the grid-fitting algorithm.</p>
<p><b>Inconsistency.</b> Results can vary between different
renderers, or even distinct versions of the same engine.</p>
</td>
</tr>
</table>
</center>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-1.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-3.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

430
docs/glyphs/glyphs-3.html
View File

@ -1,430 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType Glyph Conventions</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
FreeType Glyph Conventions
</h1>
<h2 align=center>
Version&nbsp;2.1
</h2>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-2.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-4.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#CCCCFF"
valign=center><td>
<h2>
III. Glyph metrics
</h2>
</td></tr>
</table>
<a name="section-1">
<h3>
1. Baseline, pens and layouts
</h3>
<p>The baseline is an imaginary line that is used to "guide" glyphs when
rendering text. It can be horizontal (e.g. Roman, Cyrillic, Arabic,
etc.) or vertical (e.g. Chinese, Japanese, Korean, etc). Moreover, to
render text, a virtual point, located on the baseline, called the <em>pen
position</em> or <em>origin</em>, is used to locate glyphs.</p>
<p>Each layout uses a different convention for glyph placement:</p>
<ul>
<li>
<p>With horizontal layout, glyphs simply "rest" on the baseline.
Text is rendered by incrementing the pen position, either to the
right or to the left.</p>
<p>The distance between two successive pen positions is
glyph-specific and is called the <em>advance width</em>. Note that
its value is <em>always</em> positive, even for right-to-left
oriented alphabets, like Arabic. This introduces some differences
in the way text is rendered.</p>
<p><em>The pen position is always placed on the baseline.</em></p>
<p><center>
<img src="Image1.png"
height=179 width=458
alt="horizontal layout">
</center></p>
</li>
<li>
<p>With a vertical layout, glyphs are centered around the
baseline:</p>
<p><center>
<img src="Image2.png"
height=275 width=162
alt="vertical layout">
</center></p>
</li>
</ul>
<a name="section-2">
<h3>
2. Typographic metrics and bounding boxes
</h3>
<p>A various number of face metrics are defined for all glyphs in a
given font.</p>
<ul>
<li>
<p><em>Ascent</em></p>
<p>The distance from the baseline to the highest/upper grid
coordinate used to place an outline point. It is a positive value,
due to the grid's orientation with the <i>Y</i>&nbsp;axis
upwards.</p>
</li>
<li>
<p><em>Descent</em></p>
<p>The distance from the baseline to the lowest grid coordinate used
to place an outline point. This is a negative value, due to the
grid's orientation.</p>
</li>
<li>
<p><em>Linegap</em></p>
<p>The distance that must be placed between two lines of text. The
baseline-to-baseline distance should be computed as:
<center><p>
<tt>ascent - descent + linegap</tt>
</p></center>
<p>if you use the typographic values.</p>
</li>
</ul>
<p>Other, simpler metrics are:</p>
<ul>
<li>
<p><em>The glyph's bounding box</em>, also called <em>bbox</em></p>
<p>This is an imaginary box that encloses all glyphs from the font,
usually as tightly as possible. It is represented by four fields,
namely <tt>xMin</tt>, <tt>yMin</tt>, <tt>xMax</tt>, and
<tt>yMax</tt>, that can be computed for any outline. Their values
can be in font units (if measured in the original outline) or in
fractional/integer pixel units (when measured on scaled
outlines).</p>
<p>Note that if it wasn't for grid-fitting, you wouldn't need to
know a box's complete values, but only its dimensions to know how
big is a glyph outline/bitmap. However, correct rendering of hinted
glyphs needs the preservation of important grid alignment on each
glyph translation/placement on the baseline.</p>
</li>
<li>
<p><em>Internal leading</em></p>
<p>This concept comes directly from the world of traditional
typography. It represents the amount of space within the
<em>leading</em> which is reserved for glyph features that lay
outside of the EM square (like accentuation). It usually can be
computed as:</p>
<center><p>
<tt>internal leading = ascent - descent - EM_size</tt>
</p></center>
</li>
<li>
<p><em>External leading</em></p>
<p>This is another name for the line gap.</p>
</li>
</ul>
<a name="section-3">
<h3>
3. Bearings and Advances
</h3>
Each glyph has also distances called <em>bearings</em> and
<em>advances</em>. Their definition is constant, but their values
depend on the layout, as the same glyph can be used to render text
either horizontally or vertically:
<ul>
<li>
<p><em>Left side bearing</em> or <em>bearingX</em></p>
<p>The horizontal distance from the current pen position to the
glyph's left bbox edge. It is positive for horizontal layouts, and
in most cases negative for vertical ones.</p>
</li>
<li>
<p><em>Top side bearing</em> or <em>bearingY</em></p>
<p>The vertical distance from the baseline to the top of the glyph's
bbox. It is usually positive for horizontal layouts, and negative
for vertical ones.</p>
</li>
<li>
<p><em>Advance width</em> or <em>advanceX</em></p>
<p>The horizontal distance the pen position must be incremented (for
left-to-right writing) or decremented (for right-to-left writing) by
after each glyph is rendered when processing text. It is always
positive for horizontal layouts, and null for vertical ones.</p>
</li>
<li>
<p><em>Advance height</em> <em>advanceY</em></p>
<p>The vertical distance the pen position must be decremented by
after each glyph is rendered. It is always null for horizontal
layouts, and positive for vertical layouts.</p>
</li>
<li>
<p><em>Glyph width</em></p>
<p>The glyph's horizontal extent. For unscaled font coordinates, it
is <tt>bbox.xMax-bbox.xMin</tt>. For scaled glyphs, its computation
requests specific care, described in the grid-fitting chapter
below.</p>
</li>
<li>
<p><em>Glyph height</em>
<p>The glyph's vertical extent. For unscaled font coordinates, it is
<tt>bbox.yMax-bbox.yMin</tt>. For scaled glyphs, its computation
requests specific care, described in the grid-fitting chapter
below.</p>
</li>
<li>
<p><em>Right side bearing</em></p>
<p>Only used for horizontal layouts to describe the distance from
the bbox's right edge to the advance width. It is in most cases a
non-negative number:</p>
<p><center>
<tt>advance_width - left_side_bearing - (xMax-xMin)</tt>
</center></p>
</li>
</ul>
<p>Here is a picture giving all the details for horizontal metrics:
<center><p>
<img src="Image3.png"
height=253 width=388
alt="horizontal glyph metrics">
</p></center>
<p>And here is another one for the vertical metrics:</p>
<center><p>
<img src="Image4.png"
height=278 width=294
alt="vertical glyph metrics">
</p></center>
<a name="section-4">
<h3>
4. The effects of grid-fitting
</h3>
<p>Because hinting aligns the glyph's control points to the pixel grid,
this process slightly modifies the dimensions of character images in
ways that differ from simple scaling.</p>
<p>For example, the image of the lowercase "m" letter sometimes fits a
square in the master grid. However, to make it readable at small pixel
sizes, hinting tends to enlarge its scaled outline in order to keep its
three legs distinctly visible, resulting in a larger character
bitmap.</p>
<p>The glyph metrics are also influenced by the grid-fitting process:
<ul>
<li>
The image's width and height are altered. Even if this is only by
one pixel, it can make a big difference at small pixel sizes.
</li>
<li>
The image's bounding box is modified, thus modifying the bearings.
</li>
<li>
The advances must be updated. For example, the advance width must
be incremented if the hinted bitmap is larger than the scaled one,
to reflect the augmented glyph width.
</li>
</ul>
<p>This has some implications:</p>
<ul>
<li>
Because of hinting, simply scaling the font ascent or descent might
not give correct results. A possible solution is to keep the
ceiling of the scaled ascent, and floor of the scaled descent.
</li>
<li>
There is no easy way to get the hinted glyph and advance widths of a
range of glyphs, as hinting works differently on each outline. The
only solution is to hint each glyph separately and record the
returned values. Some formats, like TrueType, even include a table
of pre-computed values for a small set of common character pixel
sizes.
</li>
<li>
Hinting depends on the final character width and height in pixels,
which means that it is highly resolution-dependent. This property
makes correct WYSIWYG layouts difficult to implement.
</li>
</ul>
<em>
<p>Performing 2D transformations on glyph outlines is very easy with
FreeType. However, when using translation on a hinted outlines, one
should aways take care of <b>exclusively using integer pixel
distances</b> (which means that the parameters to the
<tt>FT_Translate_Outline()</tt> API should all be multiples
of&nbsp;64, as the point coordinates are in 26.6&nbsp;fixed float
format).</p>
<p>Otherwise, the translation will simply <em>ruin the hinter's
work</em>, resulting in a very low quality bitmaps!</p>
</em>
<a name="section-5">
<h3>
5. Text widths and bounding box
</h3>
<p>As seen before, the "origin" of a given glyph corresponds to the
position of the pen on the baseline. It is not necessarily located on
one of the glyph's bounding box corners, unlike many typical bitmapped
font formats. In some cases, the origin can be out of the bounding box,
in others, it can be within it, depending on the shape of the given
glyph.</p>
<p>Likewise, the glyph's "advance width" is the increment to apply to
the pen position during layout, and is not related to the glyph's
"width", which really is the glyph's bounding width.
<p>The same conventions apply to strings of text. This means that:
<ul>
<li>
The bounding box of a given string of text doesn't necessarily
contain the text cursor, nor is the latter located on one of its
corners.
</li>
<li>
The string's advance width isn't related to its bounding box
dimensions. Especially if it contains beginning and terminal spaces
or tabs.
</li>
<li>
Finally, additional processing like kerning creates strings of text
whose dimensions are not directly related to the simple
juxtaposition of individual glyph metrics. For example, the advance
width of "VA" isn't the sum of the advances of "V" and "A" taken
separately.
</li>
</ul>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-2.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-4.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

231
docs/glyphs/glyphs-4.html
View File

@ -1,231 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType Glyph Conventions</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
FreeType Glyph Conventions
</h1>
<h2 align=center>
Version&nbsp;2.1
</h2>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-3.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-4.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#CCCCFF"
valign=center><td>
<h2>
IV. Kerning
</h2>
</td></tr>
</table>
<p>The term <em>kerning</em> refers to specific information used to
adjust the relative positions of coincident glyphs in a string of text.
This section describes several types of kerning information, as well as
the way to process them when performing text layout.</p>
<a name="section-1">
<h3>
1. Kerning pairs
</h3>
<p>Kerning consists of modifying the spacing between two successive
glyphs according to their outlines. For example, a "T" and a "y" can be
easily moved closer, as the top of the "y" fits nicely under the upper
right bar of the "T".</p>
<p>When laying out text with only their standard widths, some
consecutive glyphs seem a bit too close or too distant. For example,
the space between the "A" and the "V" in the following word seems a
little wider than needed.</p>
<center><p>
<img src="bravo_unkerned.png"
height=37 width=116
alt="the word 'bravo' unkerned">
</p></center>
<p>Compare this to the same word, where the distance between these two
letters has been slightly reduced:</p>
<center><p>
<img src="bravo_kerned.png"
height=37 width=107
alt="the word 'bravo' with kerning">
</p></center>
<p>As you can see, this adjustment can make a great difference. Some
font faces thus include a table containing kerning distances for a set
of given glyph pairs for text layout.</p>
<ul>
<li>
<p>The pairs are ordered, i.e., the space for pair (A,V) isn't
necessarily the space for pair (V,A). They also index glyphs, and
not characters.</p>
</li>
<li>
<p>Kerning distances can be expressed in horizontal or vertical
directions, depending on layout and/or script. For example, some
horizontal layouts like Arabic can make use of vertical kerning
adjustments between successive glyphs. A vertical script can have
vertical kerning distances.</p>
</li>
<li>
<p>Kerning distances are expressed in grid units. They are usually
oriented in the <i>X</i>&nbsp;axis, which means that a negative
value indicates that two glyphs must be set closer in a horizontal
layout.</p>
</li>
</ul>
<a name="section-2">
<h3>
2. Applying kerning
</h3>
<p>Applying kerning when rendering text is a rather easy process. It
merely consists in adding the scaled kern distance to the pen position
before writing each next glyph. However, the typographically correct
renderer must take a few more details in consideration.</p>
<p>The "sliding dot" problem is a good example: Many font faces include
a kerning distance between capital letters like "T" or "F" and a
following dot ("."), in order to slide the latter glyph just right to
their main leg:</p>
<center><p>
<img src="twlewis1.png"
height=38 width=314
alt="example for sliding dots">
</p></center>
<p>This sometimes requires additional adjustments between the dot and
the letter following it, depending on the shapes of the enclosing
letters. When applying "standard" kerning adjustments, the previous
sentence would become:</p>
<center><p>
<img src="twlewis2.png"
height=36 width=115
alt="example for too much kerning">
</p></center>
<p>This is clearly too contracted. The solution here, as exhibited in
the first example, is to only slide the dots when possible. Of course,
this requires a certain knowledge of the text's meaning. The above
adjustments would not necessarily be welcome if we were rendering the
final dot of a given paragraph.</p.
<p>This is only one example, and there are many others showing that a
real typographer is needed to layout text properly. If not available,
some kind of user interaction or tagging of the text could be used to
specify some adjustments, but in all cases, this requires some support
in applications and text libraries.</p>
<p>For more mundane and common uses, however, we can have a very simple
algorithm, which avoids the sliding dot problem, and others, though not
producing optimal results. It can be seen as</p>
<ol>
<li>
Place the first glyph on the baseline.
</li>
<li>
Save the location of the pen position/origin in <tt>pen1</tt>.
</li>
<li>
Adjust the pen position with the kerning distance between the first
and second glyph.
</li>
<li>
Place the second glyph and compute the next pen position/origin in
<tt>pen2</tt>.
</li>
<li>
Use <tt>pen1</tt> as the next pen position if it is beyond
<tt>pen2</tt>, use <tt>pen2</tt> otherwise.
</li>
</ol>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-3.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-5.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

484
docs/glyphs/glyphs-5.html
View File

@ -1,484 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType Glyph Conventions</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
FreeType Glyph Conventions
</h1>
<h2 align=center>
Version&nbsp;2.1
</h2>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-4.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-6.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#CCCCFF"
valign=center><td>
<h2>
V. Text processing
</h2>
</td></tr>
</table>
<p>This section demonstrates how to use the concepts previously defined
to render text, whatever the layout you use.</p>
<a name="section-1">
<h3>
1. Writing simple text strings
</h3>
<p>In this first example, we will generate a simple string of Roman
text, i.e. with a horizontal left-to-right layout. Using exclusively
pixel metrics, the process looks like:
<tt>
<ol>
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Translate the glyph so that its 'origin' matches the pen position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Increment the pen position by the glyph's advance width in pixels.
</li>
<li>
Start over at step&nbsp3 for each of the remaining glyphs.
</li>
<li>
When all glyphs are done, set the text cursor to the new pen
position.
</li>
</ol>
</tt>
<p>Note that kerning isn't part of this algorithm.</p>
<a name="section-2">
<h3>
2. Sub-pixel positioning
</h3>
<p>It is somewhat useful to use sub-pixel positioning when rendering
text. This is crucial, for example, to provide semi-WYSIWYG text
layouts. Text rendering is very similar to the algorithm described in
subsection&nbsp;1, with the following few differences:</p>
<ul>
<li>
The pen position is expressed in fractional pixels.
</li>
<li>
Because translating a hinted outline by a non-integer distance will
ruin its grid-fitting, the position of the glyph origin must be
rounded before rendering the character image.
</li>
<li>
The advance width is expressed in fractional pixels, and isn't
necessarily an integer.
</li>
</ol>
<p>Here an improved version of the algorithm:</p>
<tt>
<ol>
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position. This can be a non-integer
point.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Translate the glyph so that its "origin" matches the rounded pen
position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Increment the pen position by the glyph's advance width in
fractional pixels.
</li>
<li>
Start over at step&nbsp;3 for each of the remaining glyphs.
</li>
<li>
When all glyphs are done, set the text cursor to the new pen
position.
</li>
</ol>
</tt>
<p>Note that with fractional pixel positioning, the space between two
given letters isn't fixed, but determined by the accumulation of
previous rounding errors in glyph positioning.</p>
<a name="section-3">
<h3>
3. Simple kerning
</h3>
<p>Adding kerning to the basic text rendering algorithm is easy: When a
kerning pair is found, simply add the scaled kerning distance to the pen
position before step&nbsp;4. Of course, the distance should be rounded
in the case of algorithm&nbsp;1, though it doesn't need to for
algorithm&nbsp;2. This gives us:</p>
<p>Algorithm&nbsp;1 with kerning:</p>
<tt>
<ol>
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Add the rounded scaled kerning distance, if any, to the pen
position.
</li>
<li>
Translate the glyph so that its "origin" matches the pen position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Increment the pen position by the glyph's advance width in pixels.
</li>
<li>
Start over at step&nbsp;3 for each of the remaining glyphs.
</li>
</ol>
</tt>
<p>Algorithm&nbsp;2 with kerning:</p>
<tt>
<ol>
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Add the scaled unrounded kerning distance, if any, to the pen
position.
</li>
<li>
Translate the glyph so that its "origin" matches the rounded pen
position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Increment the pen position by the glyph's advance width in
fractional pixels.
</li>
<li>
Start over at step&nbsp;3 for each of the remaining glyphs.
</li>
</ol>
</tt>
Of course, the algorithm described in section&nbsp;IV can also be
applied to prevent the sliding dot problem if one wants to.
<a name="section-4">
<h3>
4. Right-to-left layout
</h3>
<p>The process of laying out Arabic or Hebrew text is extremely similar.
The only difference is that the pen position must be decremented before
the glyph rendering (remember: the advance width is always positive,
even for Arabic glyphs).</p>
<p>Right-to-left algorithm&nbsp;1:</p>
<tt>
<ol>
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Decrement the pen position by the glyph's advance width in pixels.
</li>
<li>
Translate the glyph so that its "origin" matches the pen position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Start over at step&nbsp;3 for each of the remaining glyphs.
</li>
</ol>
</tt>
<p>The changes to algorithm&nbsp;2, as well as the inclusion of kerning
are left as an exercise to the reader.</p>
<a name="section-5">
<h3>
5. Vertical layouts
</h3>
<p>Laying out vertical text uses exactly the same processes, with the
following significant differences:</p>
<ul>
<li>
<p>The baseline is vertical, and the vertical metrics must be used
instead of the horizontal one.</p>
</li>
<li>
<p>The left bearing is usually negative, but this doesn't change the
fact that the glyph origin must be located on the baseline.</p>
</li>
<li>
The advance height is always positive, so the pen position must be
decremented if one wants to write top to bottom (assuming the
<i>Y</i>&nbsp;axis is oriented upwards).
</li>
</ul>
<p>Here the algorithm:</p>
<tt>
<ol>
<li>
Convert the character string into a series of glyph
indices.
</li>
<li>
Place the pen to the cursor position.
</li>
<li>
Get or load the glyph image.
</li>
<li>
Translate the glyph so that its "origin" matches the pen position.
</li>
<li>
Render the glyph to the target device.
</li>
<li>
Decrement the vertical pen position by the glyph's advance height
in pixels.
</li>
<li>
Start over at step&nbsp;3 for each of the remaining glyphs.
</li>
<li>
When all glyphs are done, set the text cursor to the new pen
position.
</li>
</ol>
</tt>
<a name="section-6">
<h3>
6. WYSIWYG text layouts
</h3>
<p>As you probably know, the acronym WYSIWYG stands for "What You See Is
What You Get". Basically, this means that the output of a document on
the screen should match "perfectly" its printed version. A
<em>true</em> WYSIWYG system requires two things:</p>
<ul>
<li>
<p><em>device-independent text layout</em></p>
<p>This means that the document's formatting is the same on the
screen than on any printed output, including line breaks,
justification, ligatures, fonts, position of inline images, etc.</p>
</li>
<li>
<p><em>matching display and print character sizes</em></p>
<p>The displayed size of a given character should match its
dimensions when printed. For example, a text string which is
exactly 1&nbsp;inch tall when printed should also appear 1&nbsp;inch
tall on the screen (when using a scale of 100%).</p>
</li>
</ul>
<p>It is clear that matching sizes cannot be possible if the computer
has no knowledge of the physical resolutions of the display device(s) it
is using. And of course, this is the most common case! That is not too
unfortunate, however, because most users really don't care about this
feature. Legibility is much more important.</p>
<p>When the Mac appeared, Apple decided to choose a resolution of
72&nbsp;dpi to describe the Macintosh screen to the font sub-system
(whatever the monitor used). This choice was most probably driven by
the fact that, at this resolution, 1&nbsp;point equals exactly
1&nbsp;pixel. However, it neglected one crucial fact: As most users
tend to choose a document character size between 10 and 14&nbsp;points,
the resultant displayed text was rather small and not too legible
without scaling. Microsoft engineers took notice of this problem and
chose a resolution of 96&nbsp;dpi on Windows, which resulted in slightly
larger, and more legible, displayed characters (for the same printed
text size).</p>
<p>These distinct resolutions explain some differences when displaying
text at the same character size on a Mac and a Windows machine.
Moreover, it is not unusual to find some TrueType fonts with enhanced
hinting (technical note: through delta-hinting) for the sizes of 10, 12,
14 and 16&nbsp;points at 96&nbsp;dpi.</p>
<p>The term <em>device-independent text</em> is, unfortunately, often
abused. For example, many word processors, including MS&nbsp;Word, do
not really use device-independent glyph positioning algorithms when
laying out text. Rather, they use the target printer's resolution to
compute <em>hinted</em> glyph metrics for the layout. Though it
guarantees that the printed version is always the "nicest" it can be,
especially for very low resolution printers (like dot-matrix), it has a
very sad effect: Changing the printer can have dramatic effects on the
<em>whole</em> document layout, especially if it makes strong use of
justification, uses few page breaks, etc.</p>
<p>Because glyph metrics vary slightly when the resolution changes (due
to hinting), line breaks can change enormously, when these differences
accumulate over long runs of text. Try for example printing a very long
document (with no page breaks) on a 300&nbsp;dpi ink-jet printer, then
the same one on a 3000&nbsp;dpi laser printer: You will be extremely
lucky if your final page count didn't change between the prints! Of
course, we can still call this WYSIWYG, as long as the printer
resolution is fixed.</p>
<p>Some applications, like Adobe Acrobat, which targeted
device-independent placement from the start, do not suffer from this
problem. There are two ways to achieve this: either use the scaled and
unhinted glyph metrics when laying out text both in the rendering and
printing processes, or simply use whatever metrics you want and store
them with the text in order to get sure they are printed the same on all
devices (the latter being probably the best solution, as it also enables
font substitution without breaking text layouts).</p>
<p>Just like matching sizes, device-independent placement isn't
necessarily a feature that most users want. However, it is pretty clear
that for any kind of professional document processing work, it
<em>is</em> a requirement.</p>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-4.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-6.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

432
docs/glyphs/glyphs-6.html
View File

@ -1,432 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType Glyph Conventions</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
FreeType Glyph Conventions
</h1>
<h2 align=center>
Version&nbsp;2.1
</h2>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-5.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-7.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#CCCCFF"
valign=center><td>
<h2>
VI. FreeType outlines
</h2>
</td></tr>
</table>
<p>The purpose of this section is to present the way FreeType manages
vectorial outlines, as well as the most common operations that can be
applied on them.</p>
<a name="section-1">
<h3>
1. FreeType outline description and structure
</h3>
<h4>
a. Outline curve decomposition
</h4>
<p>An outline is described as a series of closed contours in the 2D
plane. Each contour is made of a series of line segments and
B&eacute;zier arcs. Depending on the file format, these can be
second-order or third-order polynomials. The former are also called
quadratic or conic arcs, and they are used in the TrueType format.
The latter are called cubic arcs and are mostly used in the
Type&nbsp;1 format.</p>
<p>Each arc is described through a series of start, end, and control
points. Each point of the outline has a specific tag which indicates
whether it is used to describe a line segment or an arc. The tags can
take the following values:</p>
<center>
<table cellspacing=5
cellpadding=5
width="80%">
<tr VALIGN=TOP>
<td valign=top>
<tt>FT_Curve_Tag_On</tt>
</td>
<td valign=top>
<p>Used when the point is "on" the curve. This corresponds to
start and end points of segments and arcs. The other tags specify
what is called an "off" point, i.e. a point which isn't located on
the contour itself, but serves as a control point for a
B&eacute;zier arc.</p>
</td>
</tr>
<tr>
<td valign=top>
<tt>FT_Curve_Tag_Conic</tt>
</td>
<td valign=top>
<p>Used for an "off" point used to control a conic B&eacute;zier
arc.</p>
</td>
</tr>
<tr>
<td valign=top>
<tt>FT_Curve_Tag_Cubic</tt>
</td>
<td valign=top>
<p>Used for an "off" point used to control a cubic B&eacute;zier
arc.</p>
</td>
</tr>
</table>
</center>
<p>The following rules are applied to decompose the contour's points
into segments and arcs:</p>
<ul>
<li>
Two successive "on" points indicate a line segment joining them.
</li>
<li>
One conic "off" point amidst two "on" points indicates a conic
B&eacute;zier arc, the "off" point being the control point, and
the "on" ones the start and end points.
</li>
<li>
Two successive cubic "off" points amidst two "on" points indicate
a cubic B&eacute;zier arc. There must be exactly two cubic
control points and two "on" points for each cubic arc (using a
single cubic "off" point between two "on" points is forbidden, for
example).
</li>
<li>
Finally, two successive conic "off" points forces the rasterizer
to create (during the scan-line conversion process exclusively) a
virtual "on" point amidst them, at their exact middle. This
greatly facilitates the definition of successive conic
B&eacute;zier arcs. Moreover, it is the way outlines are
described in the TrueType specification.
</li>
</ul>
<p>Note that it is possible to mix conic and cubic arcs in a single
contour, even though no current font driver produces such
outlines.</p>
<center>
<table>
<tr>
<td>
<img src="points_segment.png"
height=166 width=221
alt="segment example">
</td>
<td>
<img src="points_conic.png"
height=183 width=236
alt="conic arc example">
</td>
</tr>
<tr>
<td>
<img src="points_cubic.png"
height=162 width=214
alt="cubic arc example">
</td>
<td>
<img src="points_conic2.png"
height=204 width=225
alt="cubic arc with virtual 'on' point">
</td>
</tr>
</table>
</center>
<h4>
b. Outline descriptor
</h4>
<p>A FreeType outline is described through a simple structure:</p>
<center>
<table cellspacing=3
cellpadding=3>
<caption>
<b><tt>FT_Outline</tt></b>
</caption>
<tr>
<td>
<tt>n_points</tt>
</td>
<td>
the number of points in the outline
</td>
</tr>
<tr>
<td>
<tt>n_contours</tt>
</td>
<td>
the number of contours in the outline
</td>
</tr>
<tr>
<td>
<tt>points</tt>
</td>
<td>
array of point coordinates
</td>
</tr>
<tr>
<td>
<tt>contours</tt>
</td>
<td>
array of contour end indices
</td>
</tr>
<tr>
<td>
<tt>tags</tt>
</td>
<td>
array of point flags
</td>
</tr>
</table>
</center>
<p>Here, <tt>points</tt> is a pointer to an array of
<tt>FT_Vector</tt> records, used to store the vectorial coordinates of
each outline point. These are expressed in 1/64th of a pixel, which
is also known as the <em>26.6&nbsp;fixed float format</em>.</p>
<p><tt>contours</tt> is an array of point indices used to delimit
contours in the outline. For example, the first contour always starts
at point&nbsp;0, and ends at point <tt>contours[0]</tt>. The second
contour starts at point <tt>contours[0]+1</tt> and ends at
<tt>contours[1]</tt>, etc.</p>
<p>Note that each contour is closed, and that <tt>n_points</tt> should
be equal to <tt>contours[n_contours-1]+1</tt> for a valid outline.</p>
<p>Finally, <tt>tags</tt> is an array of bytes, used to store each
outline point's tag.</p>
<a name="section-2">
<h3>
2. Bounding and control box computations
</h3>
<p>A <em>bounding box</em> (also called <em>bbox</em>) is simply a
rectangle that completely encloses the shape of a given outline. The
interesting case is the smallest bounding box possible, and in the
following we subsume this under the term "bounding box". Because of the
way arcs are defined, B&eacute;zier control points are not necessarily
contained within an outline's (smallest) bounding box.</p>
<p>This situation happens when one B&eacute;zier arc is, for example,
the upper edge of an outline and an "off" point happens to be above the
bbox. However, it is very rare in the case of character outlines
because most font designers and creation tools always place "on" points
at the extrema of each curved edges, as it makes hinting much
easier.</p>
<p>We thus define the <em>control box</em> (also called <em>cbox</em>)
as the smallest possible rectangle that encloses all points of a given
outline (including its "off" points). Clearly, it always includes the
bbox, and equates it in most cases.</p>
<p>Unlike the bbox, the cbox is much faster to compute.</p>
<center>
<table>
<tr>
<td>
<img src="bbox1.png"
height=264 width=228
alt="a glyph with different bbox and cbox">
</td>
<td>
<img src="bbox2.png"
height=229 width=217
alt="a glyph with identical bbox and cbox">
</td>
</tr>
</table>
</center>
<p>Control and bounding boxes can be computed automatically through the
functions <tt>FT_Get_Outline_CBox()</tt> and
<tt>FT_Get_Outline_BBox()</tt>. The former function is always very
fast, while the latter <em>may</em> be slow in the case of "outside"
control points (as it needs to find the extreme of conic and cubic arcs
for "perfect" computations). If this isn't the case, it is as fast as
computing the control box.
<p>Note also that even though most glyph outlines have equal cbox and
bbox to ease hinting, this is not necessary the case anymore when a
transformation like rotation is applied to them.</p>
<a name="section-3">
<h3>
3. Coordinates, scaling and grid-fitting
</h3>
<p>An outline point's vectorial coordinates are expressed in the
26.6&nbsp;format, i.e. in 1/64th of a pixel, hence the coordinates
(1.0,-2.5) are stored as the integer pair (x:64,y:-192).</p>
<p>After a master glyph outline is scaled from the EM grid to the
current character dimensions, the hinter or grid-fitter is in charge of
aligning important outline points (mainly edge delimiters) to the pixel
grid. Even though this process is much too complex to be described in a
few lines, its purpose is mainly to round point positions, while trying
to preserve important properties like widths, stems, etc.</p>
<p>The following operations can be used to round vectorial distances in
the 26.6&nbsp;format to the grid:</p>
<pre>
round( x ) == ( x + 32 ) &amp; -64
floor( x ) == x &amp; -64
ceiling( x ) == ( x + 63 ) &amp; -64</pre>
<p>Once a glyph outline is grid-fitted or transformed, it often is
interesting to compute the glyph image's pixel dimensions before
rendering it. To do so, one has to consider the following:</p>
<p>The scan-line converter draws all the pixels whose <em>centers</em>
fall inside the glyph shape. It can also detect <em>drop-outs</em>,
i.e. discontinuities coming from extremely thin shape fragments, in
order to draw the "missing" pixels. These new pixels are always located
at a distance less than half of a pixel but it is not easy to predict
where they will appear before rendering.</p>
<p>This leads to the following computations:</p>
<ul>
<li>
<p>compute the bbox</p>
</li>
<li>
<p>grid-fit the bounding box with the following:</p>
<pre>
xmin = floor( bbox.xMin )
xmax = ceiling( bbox.xMax )
ymin = floor( bbox.yMin )
ymax = ceiling( bbox.yMax )</pre>
</li>
<li>
return pixel dimensions, i.e.
<pre>
width = (xmax - xmin)/64</pre>
and
<pre>
height = (ymax - ymin)/64</pre>
</li>
</ul>
<p>By grid-fitting the bounding box, it is guaranteed that all the pixel
centers that are to be drawn, <em>including those coming from drop-out
control</em>, will be <em>within</em> the adjusted box. Then the box's
dimensions in pixels can be computed.</p>
<p>Note also that, when translating a grid-fitted outline, one should
<em>always use integer distances</em> to move an outline in the 2D
plane. Otherwise, glyph edges won't be aligned on the pixel grid
anymore, and the hinter's work will be lost, producing <em>very low
quality </em>bitmaps and pixmaps.</p>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-5.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="glyphs-7.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

356
docs/glyphs/glyphs-7.html
View File

@ -1,356 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType Glyph Conventions</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
FreeType Glyph Conventions
</h1>
<h2 align=center>
Version&nbsp;2.1
</h2>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-6.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
&nbsp;
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#CCCCFF"
valign=center><td>
<h2>
VII. FreeType bitmaps
</h2>
</td></tr>
</table>
<p>The purpose of this section is to present the way FreeType manages
bitmaps and pixmaps, and how they relate to the concepts previously
defined. The relationships between vectorial and pixel coordinates is
explained.</p>
<a name="section-1">
<h3>
1. Vectorial versus pixel coordinates
</h3>
<p>This sub-section explains the differences between vectorial and pixel
coordinates. To make things clear, brackets will be used to describe
pixel coordinates, e.g. [3,5], while parentheses will be used for
vectorial ones, e.g. (-2,3.5).</p>
<p>In the pixel case, as we use the <em>Y&nbsp;upwards</em> convention;
the coordinate [0,0] always refers to the <em>lower left pixel</em> of a
bitmap, while coordinate [width-1, rows-1] to its <em>upper right
pixel</em>.</p>
<p>In the vectorial case, point coordinates are expressed in floating
units, like (1.25, -2.3). Such a position doesn't refer to a given
pixel, but simply to an immaterial point in the 2D plane.</p>
<p>The pixels themselves are indeed <em>square boxes</em> of the 2D
plane, whose centers lie in half pixel coordinates. For example, the
lower left pixel of a bitmap is delimited by the square (0,0)-(1,1), its
center being at location (0.5,0.5).</p>
<p>This introduces some differences when computing distances. For
example, the <em>length</em> in pixels of the line [0,0]-[10,0] is 11.
However, the vectorial distance between (0,0)-(10,0) covers exactly
10&nbsp;pixel centers, hence its length is&nbsp;10.</p>
<center>
<img src="grid_1.png"
height=390 width=402
alt="bitmap and vector grid">
</center>
<a name="section-2">
<h3>
2. FreeType bitmap and pixmap descriptor
</h3>
<p>A bitmap or pixmap is described through a single structure, called
<tt>FT_Bitmap</tt>, defined in the file
<tt>&lt;freetype/ftimage.h&gt;</tt>. It is a simple descriptor whose
fields are:</p>
<center>
<table cellspacing=3
cellpadding=5
width="80%">
<caption>
<b><tt>FT_Bitmap</tt></b>
</caption>
<tr>
<td valign=top>
<tt>rows</tt>
</td>
<td valign=top>
the number of rows, i.e. lines, in the bitmap
</td>
</tr>
<tr>
<td valign=top>
<tt>width</tt>
</td>
<td valign=top>
the number of horizontal pixels in the bitmap
</td>
</tr>
<tr>
<td valign=top>
<tt>pitch</tt>
</td>
<td valign=top>
its absolute value is the number of bytes per bitmap line; it can
be either positive or negative depending on the bitmap's vertical
orientation
</td>
</tr>
<tr>
<td valign=top>
<tt>buffer</tt>
</td>
<td valign=top>
a typeless pointer to the bitmap pixel bufer
</td>
</tr>
<tr>
<td valign=top>
<tt>pixel_mode</tt>
</td>
<td valign=top>
an enumeration used to describe the pixel format of the bitmap;
examples are <tt>ft_pixel_mode_mono</tt> for 1-bit monochrome
bitmaps and <tt>ft_pixel_mode_grays</tt> for 8-bit anti-aliased
"gray" values
</td>
</tr>
<tr>
<td valign=top>
<tt>num_grays</tt>
</td>
<td valign=top>
this is only used for "gray" pixel modes; it gives the number of
gray levels used to describe the anti-aliased gray levels --
FreeType&nbsp;2 defaults to 256&nbsp;grays.
</td>
</tr>
</table>
</center>
<p>Note that the sign of the <tt>pitch</tt> fields determines whether
the rows in the pixel buffer are stored in ascending or descending
order.</p>
<p>Remember that FreeType uses the <em>Y&nbsp;upwards</em> convention in
the 2D plane, which means that a coordinate of (0,0) always refer to the
<em>lower-left corner</em> of a bitmap.</p>
<p>If the pitch is positive, the rows are stored in decreasing vertical
position; the first bytes of the pixel buffer are part of the
<em>upper</em> bitmap row.</p>
<p>On the opposite, if the pitch is negative, the first bytes of the
pixel buffer are part of the <em>lower</em> bitmap row.</p>
<p>In all cases, one can see the pitch as the byte increment needed to
skip to the <em>next lower scanline</em> in a given bitmap buffer.</p>
<center>
<table>
<tr>
<td>
<img src="up_flow.png"
height=261 width=275
alt="negative 'pitch'">
</td>
<td>
<img src="down_flow.png"
height=263 width=273
alt="positive 'pitch'">
</td>
</tr>
</table>
</center>
<p>The "positive pitch" convention is very often used, though
some systems might need the other.</p>
<a name="section-3">
<h3>
3. Converting outlines into bitmaps and pixmaps
</h3>
<p>Generating a bitmap or pixmap image from a vectorial image is easy
with FreeType. However, one must understand a few points regarding the
positioning of the outline in the 2D plane before converting it to a
bitmap:</p>
<ul>
<li>
<p>The glyph loader and hinter always places the outline in the 2D
plane so that (0,0) matches its character origin. This means that
the glyph's outline, and corresponding bounding box, can be placed
anywhere in the 2D plane (see the graphics in section&nbsp;III).</p>
</li>
<li>
<p>The target bitmap's area is mapped to the 2D plane, with its
lower left corner at (0,0). This means that a bitmap or pixmap of
dimensions [<tt>w,h</tt>] will be mapped to a 2D rectangle window
delimited by (0,0)-(<tt>w,h</tt>).</p>
</li>
<li>
<p>When scan-converting the outline, everything that falls within
the bitmap window is rendered, the rest is ignored.</p>
</li>
<p>A common mistake made by many developers when they begin using
FreeType is believing that a loaded outline can be directly rendered
in a bitmap of adequate dimensions. The following images illustrate
why this is a problem.</p>
<ul>
<li>
The first image shows a loaded outline in the 2D plane.
</li>
<li>
The second one shows the target window for a bitmap of arbitrary
dimensions [w,h].
</li>
<li>
The third one shows the juxtaposition of the outline and window in
the 2D plane.
</li>
<li>
The last image shows what will really be rendered in the bitmap.
</li>
</ul>
<center>
<img src="clipping.png"
height=151 width=539
alt="clipping algorithm">
</center>
</ul>
<p>Indeed, in nearly all cases, the loaded or transformed outline must
be translated before it is rendered into a target bitmap, in order to
adjust its position relative to the target window.</p>
<p>For example, the correct way of creating a <em>standalone</em> glyph
bitmap is as follows</p>
<ul>
<li>
<p>Compute the size of the glyph bitmap. It can be computed
directly from the glyph metrics, or by computing its bounding box
(this is useful when a transformation has been applied to the
outline after the load, as the glyph metrics are not valid
anymore).</p>
</li>
<li>
<p>Create the bitmap with the computed dimensions. Don't forget to
fill the pixel buffer with the background color.</p>
</li>
<li>
<p>Translate the outline so that its lower left corner matches
(0,0). Don't forget that in order to preserve hinting, one should
use integer, i.e. rounded distances (of course, this isn't required
if preserving hinting information doesn't matter, like with rotated
text). Usually, this means translating with a vector
<tt>(-ROUND(xMin), -ROUND(yMin))</tt>.</p>
</li>
<li>
<p>Call the rendering function (it can be
<tt>FT_Outline_Render()</tt> for example).</p>
</li>
</ul>
<p>In the case where one wants to write glyph images directly into a
large bitmap, the outlines must be translated so that their vectorial
position correspond to the current text cursor/character origin.</p>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="glyphs-6.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
&nbsp;
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

BIN
docs/glyphs/grid_1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.0 KiB

200
docs/glyphs/index.html
View File

@ -1,200 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType Glyph Conventions</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
FreeType Glyph Conventions
</h1>
<h2 align=center>
Version&nbsp;2.1
</h2>
<h3 align=center>
Copyright&nbsp;1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright&nbsp;2000 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="70%">
<tr><td>
<p>This document presents the core conventions used within the FreeType
library to manage font and glyph data. It is a <em>must-read</em> for all
developers who need to understand digital typography, especially if you
want to use the FreeType&nbsp;2 library in your projects.</p>
<table width="100%">
<tr valign=center
bgcolor="#CCCCFF">
<td align=center>
<h2>
Table of Contents
</h2>
</td>
</tr>
</table>
<center>
<table width="80%">
<tr><td>
<h2>
<a href="glyphs-1.html">I. Basic Typographic Concepts</a>
</h2>
<blockquote>
<h3>
<a href="glyphs-1.html#section-1">1. Font files, format and
information</a>
<br>
<a href="glyphs-1.html#section-2">2. Character images and mappings</a>
<br>
<a href="glyphs-1.html#section-3">3. Character and font metrics</a>
<br>
</h3>
</blockquote>
<h2>
<a href="glyphs-2.html">II. Glyph outlines</a>
</h2>
<blockquote>
<h3>
<a href="glyphs-2.html#section-1">1. Pixels, points and device
resolutions</a>
<br>
<a href="glyphs-2.html#section-2">2. Vectorial representation</a>
<br>
<a href="glyphs-2.html#section-3">3. Hinting and bitmap rendering</a>
<br>
</h3>
</blockquote>
<h2>
<a href="glyphs-3.html">III. Glyph metrics</a>
</h2>
<blockquote>
<h3>
<a href="glyphs-3.html#section-1">1. Baseline, pens and layouts</a>
<br>
<a href="glyphs-3.html#section-2">2. Typographic metrics and
bounding boxes</a>
<br>
<a href="glyphs-3.html#section-3">3. Bearings and advances</a>
<br>
<a href="glyphs-3.html#section-4">4. The effects of grid-fitting</a>
<br>
<a href="glyphs-3.html#section-5">5. Text widths and bounding box</a>
<br>
</h3>
</blockquote>
<h2>
<a href="glyphs-4.html">IV. Kerning</a>
</h2>
<blockquote>
<h3>
<a href="glyphs-4.html#section-1">1. Kerning pairs</a>
<br>
<a href="glyphs-4.html#section-2">2. Applying kerning</a>
<br>
</h3>
</blockquote>
<h2>
<a href="glyphs-5.html">V. Text processing</a>
</h2>
<blockquote>
<h3>
<a href="glyphs-5.html#section-1">1. Writing simple text strings</a>
<br>
<a href="glyphs-5.html#section-2">2. Sub-pixel positioning</a>
<br>
<a href="glyphs-5.html#section-3">3. Simple kerning</a>
<br>
<a href="glyphs-5.html#section-4">4. Right-to-left layouts</a>
<br>
<a href="glyphs-5.html#section-5">5. Vertical layouts</a>
<br>
<a href="glyphs-5.html#section-6">6. WYSIWYG text layouts</a>
<br>
</h3>
</blockquote>
<h2>
<a href="glyphs-6.html">VI. FreeType Outlines</a>
</h2>
<blockquote>
<h3>
<a href="glyphs-6.html#section-1">1. FreeType outline description
and structure</a>
<br>
<a href="glyphs-6.html#section-2">2. Bounding and control box
computations</a>
<br>
<a href="glyphs-6.html#section-3">3. Coordinates, scaling, and
grid-fitting</a>
<br>
</h3>
</blockquote>
<h2>
<a href="glyphs-7.html">VII. FreeType bitmaps</a>
</h2>
<blockquote>
<h3>
<a href="glyphs-7.html#section-1">1. Vectorial versus pixel
coordinates</a>
<br>
<a href="glyphs-7.html#section-2">2. FreeType bitmap and pixmap
descriptor</a>
<br>
<a href="glyphs-7.html#section-3">3. Converting outlines into
bitmaps and pixmaps</a>
<br>
</h3>
</blockquote>
</td></tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>

BIN
docs/glyphs/points_conic.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 846 B

BIN
docs/glyphs/points_conic2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.2 KiB

BIN
docs/glyphs/points_cubic.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 919 B

BIN
docs/glyphs/points_segment.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 661 B

BIN
docs/glyphs/twlewis1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.6 KiB

BIN
docs/glyphs/twlewis2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.3 KiB

BIN
docs/glyphs/up_flow.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.2 KiB

BIN
docs/image/freetype.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

BIN
docs/tutorial/metrics.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.2 KiB

BIN
docs/tutorial/metrics2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.8 KiB

948
docs/tutorial/step1.html
View File

@ -1,948 +0,0 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<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&nbsp;2.0 Tutorial<br>
Step&nbsp;1 -- simple glyph loading
</h1>
<h3 align=center>
&copy;&nbsp;2000 David Turner
(<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
&copy;&nbsp;2000 The FreeType Development Team
(<a href="http://www.freetype.org">www.freetype.org</a>)
</h3>
<center>
<table width="550">
<tr><td>
<hr>
<h2>
Introduction
</h2>
<p>This is the first part of the FreeType&nbsp;2 tutorial. It will
teach you to do the following:</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>To include the main FreeType header file, say</p>
<font color="blue">
<pre>
#include &lt;freetype/freetype.h&gt;</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> and other (internal) files. Some of them 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 &lt;freetype/freetype.h&gt;
FT_Library library;
...
{
...
error = FT_Init_FreeType( &amp;library );
if ( error )
{
... an error occurred during library initialization ...
}
}</pre>
</font>
<p>This function is in charge of the following:</p>
<ul>
<li>
Creating a new instance of the FreeType&nbsp;2 library, and set the
handle <tt>library</tt> to it.
</li>
<li>
Load each module that FreeType knows about in the library. This
means that by default, your new <tt>library</tt> object is able to
handle TrueType, Type&nbsp;1, Windows FON, CID-keyed & OpenType/CFF
fonts gracefully.
</li>
</ul>
<p>As you can see, the function returns an error code, like most others
in the FreeType API. An error code of&nbsp;0 <em>always</em> means that
the operation was successful; otherwise, the value describes the error,
and <tt>library</tt> is set to <tt>NULL</tt>.</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( &amp;library );
if ( error ) { ... }
error = FT_New_Face( library,
"/usr/share/fonts/truetype/arial.ttf",
0,
&amp;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 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>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 <tt>NULL</tt> in case of error.</p>
</td>
</tr>
</table>
<p>To know how many faces a given font file contains, load its first
face (use <tt>face_index</tt>=0), 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 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( &amp;library );
if ( error ) { ... }
error = FT_New_Memory_Face( library,
buffer, /* first byte in memory */
size, /* size in bytes */
0, /* face_index */
&amp;face );
if ( error ) { ... }</pre>
</font>
<p>As you can see, <tt>FT_New_Memory_Face()</tt> 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 not sufficient. With FreeType&nbsp;2, it is possible to
provide your own implementation of I/O&nbsp;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&nbsp;2 API reference 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&nbsp;42 wrapper.</p>
<hr>
<h3>
4. Accessing face contents
</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>face->num_glyphs</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>face->flags</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&nbsp;2 API Reference</a>.</p>
</td>
</tr>
<tr valign="top">
<td>
<tt>face->units_per_EM</tt>
</td>
<td>
<p>This field is only valid for scalable formats (it is set
to&nbsp;0 otherwise). It indicates the number of font units
covered by the EM.</p>
</td>
</tr>
<tr valign="top">
<td>
<tt>face->num_fixed_sizes</tt>
</td>
<td>
<p>This field gives the number of embedded bitmap <em>strikes</em>
in the current face. A <em>strike</em> is 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&nbsp;14. Note
that even scalable font formats can have embedded bitmap
strikes!</p>
</td>
</tr>
<tr valign="top">
<td>
<tt>face->fixed_sizes</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&nbsp;2 API Reference</a>.<p>
<hr>
<h3>
5. Setting the current pixel size
</h3>
<p>FreeType&nbsp;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&nbsp;points.</p>
<p>When the <tt>FT_New_Face()</tt> function is called (or one of its
cousins), it <em>automatically</em> creates a new size object for the
returned face. This size object is directly accessible as
<tt>face->size</tt>.</p>
<p><em>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 functions.</em></p>
<p>Before a glyph can be loaded, the size object must be set up. 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&nbsp;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>
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 is not a pixel.
</li>
<li>
Horizontal and vertical device resolutions are expressed in
<em>dots-per-inch</em>, or <em>dpi</em>. You can use 72 or
96&nbsp;dpi for display devices like the screen. The resolution is
used to compute the character pixel size from the character point
size.
</li>
<li>
A value of&nbsp;0 for the character width means <em>same as
character height</em>, a value of&nbsp;0 for the character height
means <em>same as character width</em>. Otherwise, it is possible
to specify different char widths and heights.
</li>
<li>
Using a value of&nbsp;0 for the horizontal or vertical resolution
means 72&nbsp;dpi, which is the default.
</li>
<li>
The first argument is a handle to a face object, not a size object.
This behaviour must be seen as a convenience.
</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&nbsp;pixels.
As previously, a value of&nbsp;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>face->fixed_sizes</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&nbsp;65 in ASCII encoding represents letter `A'.</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 usually). 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 up the glyph index corresponding to the given
<tt>charcode</tt> in the charmap that is currently selected for the
face.
<p>Note that this is one of the rare FreeType functions that do not
return an error code. If a given character code has no glyph image in
the face, the value&nbsp;0 is returned. By convention, it always
corresponds to a special glyph image called the <em>missing
glyph</em>, 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. The latter can be stored in various formats within the font
file. For fixed-size formats like FNT or PCF, each image is a bitmap.
Scalable formats like TrueType or Type&nbsp;1 use vectorial shapes,
named <em>outlines</em>, to describe each glyph. Some formats may have
even more exotic ways of representing glyphs (e.g. MetaFont).
Fortunately, FreeType&nbsp;2 is flexible enough to support any kind of
glyph format through a simple API.</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 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 <tt>face->glyph</tt>.</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&nbsp;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 be loaded into the slot. Embedded bitmaps are
always favored over native image formats, because we assume that
they are higher-quality versions of the same glyph. This can be
changed by using the <tt>FT_LOAD_NO_BITMAP</tt> 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 Type&nbsp;1.</p>
</li>
</ul>
<p>The field <tt>glyph->format</tt> describes the format used to store
the glyph image in the slot. If it is not
<tt>ft_glyph_format_bitmap</tt>, it is possible to immedialy 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> specifies how to render the
glyph image. Set it <tt>ft_render_mode_normal</tt> to render a
high-quality anti-aliased (256&nbsp;gray levels) bitmap. You can
alternatively use <tt>ft_render_mode_mono</tt> if you want to generate
a 1-bit monochrome bitmap.</p>
<p>Once you have a bitmapped glyph image, you can access it directly
through <tt>glyph->bitmap</tt> (a simple bitmap descriptor), and
position it with <tt>glyph->bitmap_left</tt> and
<tt>glyph->bitmap_top</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 second part of the tutorial describes the contents 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 <tt>face->charmap</tt>. This field
is <tt>NULL</tt> if 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&nbsp;2. The easiest is if 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>num_charmaps</tt> and
<tt>charmaps</tt> (notice the final 's') of the face object. As
expected, 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>charmap->platform_id</tt> and
<tt>charmap->encoding_id</tt> which 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 (on the Windows platform). A list
of such pairs is defined in the TrueType specification, but you can
also use the file <tt>&lt;freetype/ttnameid.h&gt;</tt> which defines
several helpful constants to deal with them.</p>
<p>Note that some pid/eid pairs are <em>artificial</em>; such values
have been created by FreeType to identify platforms resp. encodings
not covered by the original TrueType specification.</p>
<p>To look up a specific encoding you need to find a corresponding
value pair in the specification, then look for it in the
<tt>charmaps</tt> list. Bear in mind that some encodings correspond
to several values pairs (yes, it's a real mess, but blame Apple and
Microsoft on such stupidity). Here some code to do it:</p>
<font color="blue">
<pre>
FT_CharMap found = 0;
FT_CharMap charmap;
int n;
for ( n = 0; n &lt; 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 transformations
</h4>
<p>It is possible to specify an affine transformation to be applied to
glyph images when they are 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 */
&amp;matrix, /* pointer to 2x2 matrix */
&amp;delta ); /* pointer to 2d vector */</pre>
</font>
<p>This function will set the current transformation for a given face
object. Its second parameter is a pointer to an <tt>FT_Matrix</tt>
structure that describes a 2x2&nbsp;affine matrix. The third
parameter is a pointer to an <tt>FT_Vector</tt> structure that
describes a simple 2d&nbsp;vector that is used to translate the glyph
image <em>after</em> the 2x2&nbsp;transformation.</p>
<p>Note that the matrix pointer can be set to <tt>NULL</tt>, in which
case the identity transformation will be used. Coefficients of the
matrix are otherwise in 16.16 fixed float units.</p>
<p>The vector pointer can also be set to <tt>NULL</tt> in which case a
delta vector 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>The transformation is applied to every glyph that is loaded
through <tt>FT_Load_Glyph()</tt> and is <b>completely independent of
any hinting process.</b> This means that you won't get the same
results if you load a glyph at the size of 24&nbsp;pixels, or a glyph
at the size at 12&nbsp;pixels scaled by&nbsp;2 through a
transformation, because hints will have been computed differently
(unless hints have been disabled, of course).</em></p>
<p>If you ever need to use a non-orthogonal transformation with
optimal hints, you first need to decompose your transformation into a
scaling part and a rotation/shearing part. Use the scaling part to
compute a new character pixel size, then the other one to call
<tt>FT_Set_Transform()</tt>. This is explained in details in a later
section of this tutorial.</p>
<p>Note also that loading a glyph bitmap with a non-identity
transformation will produce an error.</p>
<hr>
<h3>
7. Simple text rendering
</h3>
<p>We will now present a very simple example used to render a string of
8-bit Latin-1 text, assuming a face that contains a Unicode charmap</p>
<p>The idea is to create a loop that will, on each iteration, load one
glyph image, convert it to an anti-aliased bitmap, draw it on the target
surface, then increment the current pen position.</p>
<h4>
a. basic code
</h4>
<p>The following code performs our simple text rendering with the
functions previously described.</p>
<font color="blue">
<pre>
FT_GlyphSlot slot = face->glyph; /* a small shortcut */
int pen_x, pen_y, n;
.. initialize library ..
.. create face object ..
.. set character size ..
pen_x = 300;
pen_y = 200;
for ( n = 0; n &lt; num_chars; n++ )
{
FT_UInt glyph_index;
/* retrieve glyph index from character code */
glyph_index = FT_Get_Char_Index( face, text[n] );
/* load glyph image into the slot (erase previous one) */
error = FT_Load_Glyph( face, glyph_index, FT_LOAD_DEFAULT );
if ( error ) continue; /* ignore errors */
/* convert to an anti-aliased bitmap */
error = FT_Render_Glyph( face->glyph, ft_render_mode_normal );
if ( error ) continue;
/* now, draw to our target surface */
my_draw_bitmap( &slot->bitmap,
pen_x + slot->bitmap_left,
pen_y - slot->bitmap_top );
/* increment pen position */
pen_x += slot->advance.x >> 6;
pen_y += slot->advance.y >> 6; /* not useful for now */
}</pre>
</font>
<p>This code needs a few explanations:</p>
<ul>
<li>
We define a handle named <tt>slot</tt> that points to the face
object's glyph slot. (The type <tt>FT_GlyphSlot</tt> is a
pointer.) This is a convenience to avoid using
<tt>face->glyph->XXX</tt> every time.
</li>
<li>
We increment the pen position with the vector
<tt>slot->advance</tt>, which corresponds to the glyph's
<em>advance width</em> (also known as its <em>escapement</em>).
The advance vector is expressed in 1/64th of pixels, and is
truncated to integer pixels on each iteration.
</li>
<li>
The function <tt>my_draw_bitmap()</tt> is not part of FreeType but
must be provided by the application to draw the bitmap to the
target surface. In this example, it takes a pointer to an
<tt>FT_Bitmap</tt> descriptor and the position of its top-left
corner as arguments.
</li>
<li>
The value of <tt>slot->bitmap_top</tt> is positive for an
<em>upwards</em> vertical distance. Assuming that the coordinates
taken by <tt>my_draw_bitmap()</tt> use the opposite convention
(increasing Y corresponds to downwards scanlines), we substract it
to <tt>pen_y</tt> instead of adding it.
</li>
</ul>
<h4>b. refined code</h4>
<p>The following code is a refined version of the example above. It
uses features and functions of FreeType&nbsp;2 that have not yet been
introduced, and which will be explained below.</p>
<font color="blue">
<pre>
FT_GlyphSlot slot = face->glyph; /* a small shortcut */
FT_UInt glyph_index;
int pen_x, pen_y, n;
.. initialize library ..
.. create face object ..
.. set character size ..
pen_x = 300;
pen_y = 200;
for ( n = 0; n &lt; num_chars; n++ )
{
/* load glyph image into the slot (erase previous one) */
error = FT_Load_Char( face, text[n], FT_LOAD_RENDER );
if ( error ) continue; /* ignore errors */
/* now, draw to our target surface */
my_draw_bitmap( &amp;slot->bitmap,
pen_x + slot->bitmap_left,
pen_y - slot->bitmap_top );
/* increment pen position */
pen_x += slot->advance.x >> 6;
}</pre>
</font>
<p>We have reduced the size of our code, but it does exactly the same
thing.</p>
<ul>
<li>
<p>We use the function <tt>FT_Load_Char()</tt> instead of
<tt>FT_Load_Glyph()</tt>. As you probably imagine, it is
equivalent to calling <tt>FT_Get_Char_Index()</tt> followed by
<tt>FT_Get_Load_Glyph()</tt>.</p>
</li>
<li>
<p>We do not use <tt>FT_LOAD_DEFAULT</tt> for the loading mode but
the bit flag <tt>FT_LOAD_RENDER</tt>. It indicates that the glyph
image must be immediately converted to an anti-aliased bitmap.
This is of course a shortcut that avoids calling
<tt>FT_Render_Glyph()</tt> explicitly but is strictly
equivalent.</p>
<p>Note that you can also specify that you want a monochrome
bitmap by using the <tt>FT_LOAD_MONOCHROME</tt> load flag
instead.</p>
</li>
</ul>
<h4>c. more advanced rendering</h4>
<p>We now render transformed text (for example through a rotation).
To do that we use <tt>FT_Set_Transform()</tt>:</p>
<font color="blue">
<pre>
FT_GlyphSlot slot = face->glyph; /* a small shortcut */
FT_Matrix matrix; /* transformation matrix */
FT_UInt glyph_index;
FT_Vector pen; /* untransformed origin */
int n;
.. initialize library ..
.. create face object ..
.. set character size ..
/* set up matrix */
matrix.xx = (FT_Fixed)( cos( angle ) * 0x10000L );
matrix.xy = (FT_Fixed)(-sin( angle ) * 0x10000L );
matrix.yx = (FT_Fixed)( sin( angle ) * 0x10000L );
matrix.yy = (FT_Fixed)( cos( angle ) * 0x10000L );
/* the pen position in 26.6 cartesian space coordinates */
pen.x = 300 * 64;
pen.y = ( my_target_height - 200 ) * 64;
for ( n = 0; n &lt; num_chars; n++ )
{
/* set transformation */
FT_Set_Transform( face, &amp;matrix, &pen );
/* load glyph image into the slot (erase previous one) */
error = FT_Load_Char( face, text[n], FT_LOAD_RENDER );
if ( error ) continue; /* ignore errors */
/* now, draw to our target surface (convert position) */
my_draw_bitmap( &amp;slot->bitmap,
slot->bitmap_left,
my_target_height - slot->bitmap_top );
/* increment pen position */
pen.x += slot->advance.x;
pen.y += slot->advance.y;
}</pre>
</font>
<p>Notes:</p>
<ul>
<li>
We now use a vector of type <tt>FT_Vector</tt> to store the pen
position, with coordinates expressed as 1/64th of pixels, hence a
multiplication. The position is expressed in cartesian space.
</li>
<li>
In FreeType, glyph images are always loaded, transformed, and
described in the cartesian coordinate system (which means that
increasing&nbsp;Y corresponds to upper scanlines), unlike the
system typically used for bitmaps (where the top-most scanline has
coordinate&nbsp;0). We must thus convert between the two systems
when we define the pen position, and when we compute the top-left
position of the bitmap.
</li>
<li>
We apply the transformation matrix on each glyph to indicate
rotation as well as a delta vector that will move the transformed
image to the current pen position (in cartesian space, not bitmap
space).
</li>
<li>
The advance width is always returned transformed, which is why it
can be directly added to the current pen position. Note that it
is <em>not</em> rounded this time.
</li>
</ul>
<p>It is important to note that, while this example is a bit more
complex than the previous one, it is strictly equivalent for the case
where the transformation is the identity. Hence it can be used as a
replacement (but a more powerful one).</p>
<p>It has, however, a few shortcomings that we will explain, and
solve, in the next part of this tutorial.</p>
<hr>
<h3>
Conclusion
</h3>
<p>In this first section, you have learned the basics of FreeType&nbsp;2
as well as sufficient knowledge how to render rotated text.</p>
<p>The next part will dive into more details of the API in order to let
you access glyph metrics and images directly, how to deal with scaling,
hinting, kerning, etc.</p>
<p>The third part will discuss issues like modules, caching, and a few
other advanced topics like how to use multiple size objects with a
single face.</p>
</td></tr>
</table>
</center>
</body>
</html>

1607
docs/tutorial/step2.html
View File

File diff suppressed because it is too large Load Diff