ref: 17d6bdec92ba9d83b33f2d9bfd7bf904c6ca7528
parent: 442005b73687a5f139466b907bc91178705ccb15
author: David Turner <[email protected]>
date: Mon Jan 31 13:18:56 EST 2000
removed obsolete documentation files
--- a/docs/BUILD
+++ /dev/null
@@ -1,375 +1,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
-
--- a/docs/DESIGN
+++ /dev/null
@@ -1,216 +1,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
-
--- a/docs/essai
+++ /dev/null
@@ -1,173 +1,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