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

removed obsolete documentation files

This commit is contained in:
David Turner 2000-01-31 18:18:56 +00:00
parent 442005b736
commit 17d6bdec92
3 changed files with 0 additions and 764 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

375
docs/BUILD
View File

@ -1,375 +0,0 @@
The FreeType Build System Internals
-----------------------------------
Introduction:
This document describes the details of the FreeType build system. The
build system is a set of Makefiles and other configuration files used
to select, compile and link together the various FreeType components
according to the current platform, compiler and requested feature set.
This document also explains how to use the build system to develop
third-party font drivers or extensions to the engine, without altering
the general FreeType hierarchy;
I. Portability issues :
Given that the design of FreeType 2 is much more modular and flexible than
in previous versions, its build system is entirely based on GNU Make. There
are several reasons for this :
- It is by far the most available make tool on the planet, and
has probably been ported to every development environment known
to homo programmaticus.
- It provides useful features (like conditional defines, pattern
and wildcard matching) which are essential when implementing a
flexible configuration system, as described below
Note that you do not need to have a unix-like shell (like "sh" or "csh")
on your system in order to build FreeType.
II. The library design :
FreeType is made of several components, each with a specific role :
- THE BASE LAYER:
It is used to implement generic font services as well as provide
the high-level API used by client applications.
- ONE OR MORE FONT DRIVERS:
Each driver is a small component used to read and process a given
font format. Note that with FreeType 2, it is possible to add,
remove or upgrade a font driver at *runtime*.
- ONE OR MORE RASTERS:
A raster is a module used to render a vectorial glyph outline into
a bitmap or an anti-aliased pixmap. They differ in their output
quality, speed and memory usage.
- A LOW-LEVEL MODULE, CALLED "FTSYSTEM":
It is used to implement memory management and file i/o. Uses the
Ansi C Library by default, though some system-specific replacements
are provided in order to improve performance.
- AN "INIT" LAYER:
A tiny module used to implement the library initialisation routine,
i.e. FT_Init_FreeType. It is in charge of registering the font drivers
and rasters selected at build time.
- AN "OLD API" LAYER:
A simple layer used to link legacy applications using the FreeType
1.x API. Note that it is binary backwards compatible, which means that
applications do not need to be recompiled, only re-linked to this
layer.
For more details, please read the "FreeType Internals" Document.
The FreeType build system is in charge of the following tasks :
- detect (or select) the current platform in order to select the
best version of the "ftsystem" module. By default, it will use
the pure-ANSI version.
- determine which font drivers, and which rasters, should be
statically linked to the library at build time. These will always
be available after the library has been initialised through a call
to FT_Init_FreeType.
- eventually compile other font drivers or rasters in order to later
link them dynamically to the library at runtime, through
FT_Add_Driver / FT_Upgrade_Driver..
- compile the "init" layer, putting code in the implementation of
the FT_Init_FreeType function to register each selected font driver
or raster to the library.
III. General overview :
The FreeType build system uses a hierarchy of included sub-Makefiles
to compile and link the library.
Each included sub-Makefile is called a "rules" file, and has a very
specific purpose. The suffix for rules files is ".mk" as in :
detect.mk
config.mk
rules.mk
etc...
Here's a simple diagram of the build hierarchy, which is then explained
with details :
Makefile ( ./Makefile )
|
|
v
Config Rules ( ./config/<system>/config.mk )
|
|
v
Library Rules ( ./config/freetype.mk )
| | |
| | |
v v v
Component(s) Rules ( ./src/<component>/rules.mk )
1. The "root" Makefile :
This file must be invoked from the "freetype" directory with GNU Make.
a. Host platform auto-detection:
When run for the first time, this Makefile will try to auto-detect
the current host platform, by running the rules file named
`./config/detect.mk'. If the host system cannot be detected,
it will default to the `ansi' system.
It will then copy the rules file `./config/<system>/config.mk' to
the current directory and display the results of the auto-detection.
You can, at any time, re-run the auto-detection routine by invoking
the root Makefile with the "setup" target, as in :
% make setup
Note also that it is possible to use a second argument to indicate
a specific compiler. For example, here are the lignes to be used
in order to configure a build with LCC, Visual C++ and Visual Age
on a Win32 machine
> gmake setup lcc
> gmake setup visualc
> gmake setup visualage
The list of compilers is platform-specific and should be contained
in `config/<system>/detect.mk'.
If the detection results do not correspond to your platform or
settings, refer to chapter VI which describes the auto-detection
system in great details..
b. Building the library:
Once the host platform has been detected, you can run `make' once
again. The root Makefile will then detect the configuration rules
file in the current directory then include it.
Note also that the root Makefile is responsible for defining, if it
is not already part of the current environment, the variable TOP, which
designates the top of the FreeType source hierarchy.
When undefined, it defaults to `.'
2. The Configuration file :
The configuration rules file is used to set many important variables
before including/calling the library rules file (see below).
These variables are mainly used to describe the host environment
and compilers. Indeed, this file defines, among others, the following:
SEP The directory path separator. This can be `/',`\' or ':'
depending on the current platform. Note that all pathnames
are composed with $(SEP) in all rules file (except in
`include' statements which work well with '/' on all
platforms)
CC The compiler to use
CFLAGS The compiler flags used to compile a given source to an
object file. Usually contains flags for optimisation,
debugging and/or ansi-compliance
I The flag to be used to indicate an additionnal include path
to the compiler. This defaults to `-I' for an "ansi" system,
but can be different for others (e.g. `/i=',`-J ', etc..)
D The flag to be used to indicate a macro definition to the
compiler. This defaults to `-D' for an ANSI system.
T The flag to be used to indicate a target object file to the
compiler. This defaults to `-o ' for an ANSI system. Note the
space after the `o'.
O The object file extension to be used on the current platform.
Defaults to `o' for an ANSI system, but can be `obj', `coff'
or others.. There is no dot in the extension !
A The library file extension to be used on the current platform.
Defaults to 'a' for an ANSI system, but can be `lib', `so',
`dll' or others.. There is no dot in the extension !
BUILD The directory where the build system should grab the
configuration header file `ftconfig.h' as well as the
system-specific implementation of `ftsystem'.
OBJ The directory where all object files will be placed
3. The Library Rules files :
Once the variables defined in the configuration rules file, the
library rules file is included. This one contains all rules required
to build the library objects into OBJ
Its structure works as follows:
- provide rules to compile the low-level `ftsystem' module
- include the rules files from each font driver or component
- include the rules file for the "old api" layer
- provide rules to compile the initialisation layer
- provide additional targets like `clean', ..
Note that linking all objects files together into a library is not
performed in this file, though it might seem reasonable at first
glance. The reason for this is that not all linkers have a simple
syntax of the form:
librarian archive_file object1 object2 ....
hence, linking is performed through rules provided in the configuration
rules file, using the phony `library' target, which has been defined for
this very specific purpose.
4. The Components Rules files :
Each font driver has its own rules file, called `rules.mk' located
in its own directory. The library rules file includes these component
rules for each font driver.
These rules must perform the following:
- provide rules to compile the component, either into a single `large'
object, or into multiple small ones
- for font drivers and rasters, update some variables, that are
initially defined in the library rules file, which indicate wether
the component must be registered in the library initialisation code
a. Component Compile Modes :
There are two ways to compile a given component :
i. Single-object compilation:
In this mode, the component is compiled into a single object
file. This is performed easily by defining a single C file whose
sole purpose is to include all other component sources. For
example, the truetype driver is compiled as a single object
named `truetype.o'.
ii. Multiple objects compilation:
In this mode, all source files for a single component are compiled
individually into an object file.
Due to the way the FreeType source code is written, single mode
has the following advantages over multiple mode:
- with many compilers, the resulting object code is smaller than
the concatenation of all individual objects from multiple mode.
this, because all functions internal to the component as a whole
are declared static, allowing more optimisation. It often also
compiles much faster.
- most importantly, the single object only contains the external
symbols it needs to be linked to the base layer (all extern that
are due to inter-source calls within the component are removed).
this can reduce tremendously the size of dynamic libraries on
some platforms
Multiple mode is useful however to check some dependencies problems
that might not appear when compiling in single mode, so it has been
kept as a possibility.
b. Driver initialisation code :
The source file `./src/base/ftinit.c' contains the implementation
of the FT_Init_FreeType function which must, among other things,
register all font drivers that are statically linked to the library.
Controlling which drivers are registered at initialisation time is
performed by exploiting the state of the C-preprocessor in order to
build a linked list (a "chain") of driver interfaces.
More precisely, each font driver interface file (like `ttdriver.h'
or `t1driver.h') has some special lines that look like this :
#ifdef FTINIT_DRIVER_CHAIN
static
const FT_DriverChain ftinit_<FORMAT>_driver_chain =
{
FT_INIT_LAST_DRIVER_CHAIN,
&<FORMAT>_driver_interface
};
#undef FT_INIT_LAST_DRIVER_CHAIN
#define FT_INIT_LAST_DRIVER_CHAIN &ftinit_<FORMAT>_driver_chain
#endif
As one can see, this code is strictly reserved for `ftinit.c' which
defines FTINIT_DRIVER_CHAIN before including all font driver header
files.
When the C-processor parses these headers, it builds a linked list of
FT_DriverChain element. For exemple, the sequence :
#define FTINIT_DRIVER_CHAIN
#include <ttdriver.h>
#include <t1driver.h>
Will really generate something like:
static
*----> const FT_DriverChain ftinit_tt_driver_chain =
| {
| 0,
| &tt_driver_interface
| };
|
| static
| const FT_DriverChain ftinit_t1_driver_chain =
| {
*------ &ftinit_tt_driver_chain,
&t1_driver_interface
};
with the FT_INIT_LAST_DRIVER_CHAIN set to "&ftinit_t1_driver_chain"
Hence, the last included driver will be registered first in the library

216
docs/DESIGN
View File

@ -1,216 +0,0 @@
The Design of FreeType 2.0
==========================
Introduction:
This short document presents the design of version 2 of the FreeType
library. It is a must read for anyone willing to port, debug or hack
the FreeType sources.
I. Goals :
FreeType 2 was designed to provide a unified and universal API to
manage (i.e. read) the content of font files.
Its main features are :
- A FORMAT-INDEPENDENT HIGH-LEVEL API
Used to open, read and manage font files.
- THE USE OF PLUGGABLE "FONT DRIVERS"
Each font driver is used to support a given font format. For
example, the default build of FreeType 2 comes with drivers for the
TrueType and Type 1 font formats.
Font drivers can also be added, removed or upgraded at *runtime*,
in order to support more font formats, or improve the current ones.
Each font driver also provides its own "public interface" to client
applications who would like to use format-specific features.
- THE USE OF PLUGGABLE "RASTERS"
A raster is a tiny module used to render a glyph image
into a bitmap or anti-aliased pixmap. Rasters differ in their
output quality (especially with regards to anti-aliasing), speed
and memory usage.
An application can also provide its own raster if it needs to.
- HIGH PORTABILITY AND PERFORMANCE
The FreeType source code is written in industry-standard ANSI C.
Moreover, it abstracts memory management and i/o operations within
a single module, called "ftsystem". The FreeType build system tries
to auto-detect the host platform in order to select its most
efficient implementation. It defaults otherwise to using the
standard ANSI C Library.
Note that, independently of the host platform and build, an
application is able to provide its own memory and i/o routines.
This make FreeType suitable for use in any kind of environment,
from embedded to distributed systems.
II. Components Layout :
FreeType 2 is made of distinct components which relate directly to the
design described previously:
1. THE BASE LAYER:
The base layer implements the high-level API, as well as provide
generic font services that can be used by each font driver.
2. THE FONT DRIVERS:
Each font driver can be registered in the base layer by providing
an "interface", which really is a table of function pointers.
At build time, the set of default font drivers is selected. These
drivers are then compiled and statically linked to the library.
They will then be available after the library initialisation.
3. THE RASTERS:
FreeType 2 provides the ability to hook various raster modules into
its base layer. This provides several advantages :
- different systems mean different requirements, hence the need for
flexibility.
- for now, FreeType 2 only supports glyph images stored in the
following formats :
* bitmaps
* gray-level pixmaps
* monochrome vectorial outlines (using bezier control points)
should a new "technology" come for glyph images, it is possible
to write a new raster for it, without altering the rest of the
engine. Some examples could be :
* multi-colored vectorial outlines
* on-the-fly rendering of TeX's MetaFonts !!
4. THE SYSTEM MODULE "FTSYSTEM":
The system module is used to implement basic memory and i/o management
services. By default, it uses the ANSI C library, but some replacements
are also provided (and automatically selected by the build system) when
available.
As a simple example, the unix build uses memory-mapped files to read
font files, instead of the slow ANSI "fopen/fseek/fread". This results
in tremendous performance enhancements.
Note that, even if the build system chooses an implementation for
"ftsystem" at compile time, an application is still able to provide
its own memory or i/o routines to the library at runtime.
5. THE "INIT" LAYER:
A tiny module used to implement the function FT_Init_FreeType.
As its name suggests, it is responsible for initialising the library,
which really means the following :
- bind the implementation of "ftsystem" that best matches the
host platform to the library. This choice can be overriden
later by client applications however.
- register the set of default font drivers within the base layer.
these drivers are statically linked to the library. Other drivers
can be added at runtime later through FT_Add_Driver though..
- register the set of default rasters. Client applications are
able to add their own rasters at runtime though.
The details regarding these operations is given in the document
named "FreeType Build Internals"
III. Objects Layout :
Even though it is written in ANSI C, the desing of FreeType 2 is object
oriented, as it's the best way to implement the flexible font format
support that we wanted.
Indeed, the base layer defines a set of base classes that can be derived
by each font driver in order to support a given format. The base layer
also includes many book-keeping routines that need not be included in the
drivers.
The base classes are the following:
1. FACE OBJECTS:
As in FreeType 1.x, a face object models the content of a given font
that isn't dependent on a given size, transformation or glyph index.
This includes, for example, the font name, font style(s), available
charmaps and encodings, and all other kinds of data and tables that
help describe the font as a whole.
2. SIZE OBJECTS: (previously known as INSTANCE OBJECTS in 1.x)
A face object can have one or more associated size objects. A Size
object is used to stored the font data that is dependent on the current
character size or transform used to load glyphs.
Typical data in a size object include scaled metrics, factors, and
various kind of control data related to grid-fitting. The size object
is changed each time the character size is modified.
3. GLYPH SLOT OBJECTS:
Each face object has one "glyph slot", which is a simple container
where individual glyph images can be loaded and processed.
The glyph image can be stored in the following formats in the glyph
slot :
- monochrome bitmaps
- gray-level pixmaps
- vectorial glyph outlines (defined with bezier control points)
Note that a module, called the "raster" is provided to convert vector
outlines into either monochrome or anti-aliased bitmaps. The outline
is also directly accessible and can be walked or processed freely by
client applications.
more glyph images formats can be defined, but they will require
a specific raster module if one wants to display them on a typical
display surface.
4. CHARMAP OBJECTS:
A charmap is used to convert character codes, for a given encoding,
into glyph indices. A given face might contain several charmaps, for
example, most TrueType fonts contain both the "Windows Unicode" and
"
it is not rare to see TrueType fonts with both the
"Windows Unicode" and "Apple Roman" charmap

173
docs/essai
View File

@ -1,173 +0,0 @@
Un apercu du layout des fichiers sources de FreeType 2:
docs/ - documentation
html/ - documentation au format html
txt/ - documentation au format texte
include/ - les headers publiques de la librairie, ce sont ceux
qui sont installes avec le paquet freetype-devel.rpm
config/ - le repertoire de configuration.
ansi/
ft_conf.h - fichier de configuration
ftsys.c - fichier implementation bas-niveau
unix/
os2/
dos/
amiga/
debug/
src/ - sources de la librairie
base/ - couche de base (services generiques + API)
truetype/ - pilote truetype
options/ - options du pilote truetype
extend/ - extensions du pilote truetype
type1/ - pilote type 1
options/ - options du pilote type 1
extend/ - extensions du pilote type 1
type2/ - pilote type 2
speedo/ - pilote speedo
shared/ - sources partagees par plusieurs pilotes
tests/ - programmes de test
data/ - donnees des tests = fichiers de police => copies dans bin
test1/ - source du test numero 1
test2/ - source du test numero 2
test3/ - ...
...
obj/ - emplacement des fichiers objets compiles + librairie ?
bin/ - emplacement des executables (demos+tests)
demos/ - programmes de demonstration
graph/ - sous-systeme graphique des programmes de demo
contrib/ - contributions de toutes sortes..
=============================================================================
Quelques autres idees au hasard :
- virer le controle des threads, on s'en tape magistralement
- separer l'allocation memoire de l'acces disque (+flexible)
- l'api de base doit permettre "d'ouvrir" un fichier de police se trouvant
deja en memoire..
- expliquer les differents types de dictionnaires :
char_code -> glyph_index charmap (truetype)
char_code -> glyph_name encoding (type 1)
glyph_index -> glyph_name repertoire (...)
- plusieurs "raster" possibles (le raster par defaut peut etre déterminé à la compilation,
sinon l'ajout se fait simplement en passant un pointeur d'interface..)
- l'api de base doit etre simplifiee. La plupart des developpeurs ne veulent
pas savoir ce qu'est une "size", un "glyph_slot", etc.., on conseille donc
d'en creer une par defaut, lors de l'appel de :
------------------- initialisation et lecture des polices ------------
FT_Init_FreeType( &library );
FT_Set_Memory_Manager( library, &mem_manager_rec );
FT_Set_IO_Manager( library, &io_manager_rec );
FT_New_Face( library, file_pathname, face_index, &face );
FT_New_Memory_Face( library, first_byte, length, face_index, &face );
ou encore:
FT_New_Face( library, &new_face_rec, &face );
avec new_face_rec ::
face_index
pathname
memory_address
bytes_size
FT_Flush_Face( face ); // ferme le stream correspondant..
------------------------------------------ changement de taille ------
FT_Set_Size( face, &face_size_rec );
face_size_rec ::
char_height
char_width
horz_resolution
vert_resolution
FT_Set_Pixel_Sizes( face, 64, 64 );
----------------------------------------- selection de la charmap ----
FT_Select_Charmap( face, ft_charmap_unicode );
FT_Select_Charmap_Index( face, index );
FT_List_Charmaps( face, buffer, max, first );
face->charmap => pointe vers la charmap actuelle..
-------------------------------------- chargement des glyphes --------
FT_Load_Glyph( face, glyph_index );
FT_Load_Char( face, char_code );
FT_Transform_Glyph( face->glyph, &trans );
---------------------------------------------- rendu final -----------
FT_Get_Outline_Bitmap( library, face->glyph, &bit );
FT_Set_Raster( library, "default" );
FT_Set_Raster_Mode( library, major_mode, minor_mode );
=======================================================================================
Système de configuration automatique
freetype2/
Makefile
config/
ansi/
config.mk
make setup => autodetection du système + copie de fichier include ???
make