docs/DESIGN - third_party/freetype2 - Git at Google

 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
	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