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