From 17d6bdec92ba9d83b33f2d9bfd7bf904c6ca7528 Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 31 Jan 2000 18:18:56 +0000 Subject: [PATCH] removed obsolete documentation files --- docs/BUILD | 375 ---------------------------------------------------- docs/DESIGN | 216 ------------------------------ docs/essai | 173 ------------------------ 3 files changed, 764 deletions(-) delete mode 100644 docs/BUILD delete mode 100644 docs/DESIGN delete mode 100644 docs/essai diff --git a/docs/BUILD b/docs/BUILD deleted file mode 100644 index 34ba3e524..000000000 --- a/docs/BUILD +++ /dev/null @@ -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//config.mk ) - - | - | - v - - Library Rules ( ./config/freetype.mk ) - - | | | - | | | - v v v - - Component(s) Rules ( ./src//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//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//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__driver_chain = - { - FT_INIT_LAST_DRIVER_CHAIN, - &_driver_interface - }; - - #undef FT_INIT_LAST_DRIVER_CHAIN - #define FT_INIT_LAST_DRIVER_CHAIN &ftinit__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 - #include - - 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 - diff --git a/docs/DESIGN b/docs/DESIGN deleted file mode 100644 index b939362cf..000000000 --- a/docs/DESIGN +++ /dev/null @@ -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 - diff --git a/docs/essai b/docs/essai deleted file mode 100644 index fca63380a..000000000 --- a/docs/essai +++ /dev/null @@ -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