From 43764232b8ebab1c725bd52d357e9c1087e78c65 Mon Sep 17 00:00:00 2001 From: David Turner Date: Tue, 3 Oct 2000 17:07:28 +0000 Subject: [PATCH] removing obsolete files: the design of FT2 has evolved considerably since these documents were written, and it's better not to include them in order to avoid confusion among users of the library.. --- docs/design/build-system.html | 910 ---------------------------- docs/design/demo-programs.png | Bin 2837 -> 0 bytes docs/design/drivers-list.png | Bin 1792 -> 0 bytes docs/design/index.html | 791 ------------------------ docs/design/io-frames.html | 343 ----------- docs/design/library-compilation.png | Bin 1789 -> 0 bytes docs/design/logo1.png | Bin 870 -> 0 bytes docs/design/objects_diagram.png | Bin 3907 -> 0 bytes docs/design/objects_diagram2.png | Bin 3219 -> 0 bytes docs/design/platform-detection.png | Bin 1695 -> 0 bytes docs/design/system-interface.html | 258 -------- docs/tutorial/index.html | 871 -------------------------- 12 files changed, 3173 deletions(-) delete mode 100644 docs/design/build-system.html delete mode 100644 docs/design/demo-programs.png delete mode 100644 docs/design/drivers-list.png delete mode 100644 docs/design/index.html delete mode 100644 docs/design/io-frames.html delete mode 100644 docs/design/library-compilation.png delete mode 100644 docs/design/logo1.png delete mode 100644 docs/design/objects_diagram.png delete mode 100644 docs/design/objects_diagram2.png delete mode 100644 docs/design/platform-detection.png delete mode 100644 docs/design/system-interface.html delete mode 100644 docs/tutorial/index.html diff --git a/docs/design/build-system.html b/docs/design/build-system.html deleted file mode 100644 index b548b4566..000000000 --- a/docs/design/build-system.html +++ /dev/null @@ -1,910 +0,0 @@ - - - - - - - FreeType 2 Internals - I/O Frames - - - - - - -
-

FreeType 2.0 Build System

- -
-

-© 2000 David Turner (david@freetype.org)
-© 2000 The FreeType Development Team -(devel@freetype.org) -

- -
- -

- -

Table of Content

- -
-

Introduction

-

I. Features & Background

- -

II. Overview of the build process

- -

III. Build setup details

-

IV. Library compilation details

- - -
- -
-

Introduction:

- -

This document describes the new build system that was introduced - with FreeType 2.

- -

- -

I. Features and Background:

- -

The FreeType 2 build system is a set of Makefiles and sub-Makefiles that - are used to build the library on a very large variety of systems easily. - One of its main features are the following:

- - -

1. Convenience, not Requirement

-
    -

    Even though the build system is rather sophisticated, it simply is a - convenience that was written simply to allow the compilation of the - FreeType 2 library on as many platforms as possible, as easily as - possible. However, it is not a requirement and the library can be - compiled manually or in a graphical IDE without using it, with minimal - efforts

    - -

    (for more information on this topic, see the BUILD - document that comes with your release of FreeType, in its Detailed - Compilation Guide section).

    -
- - -

2. Compiler and platform independence

-
    -

    The FreeType 2 build system can be used with any compiler, on any platform. - It is independent of object file suffix, executable file suffix, directory - separator convention (i.e. "/" or "\"), and compiler flags for path - inclusion, macro definition, output naming, ansi compliance, etc..

    - -

    Supporting a new compiler is trivial and only requires writing a minimal - configuration sub-makefile that contains several Makefile variables - definitions that are later used by the rest of the build system. This is - described in details later in the document.

    -
- - -

3. Uses GNU Make

-
    -

    The build system works exclusively with GNU Make. Reason - is that it is the only make utility that has all the features required to - implement the build system as described below. Moreover, it is already - ported to hundreds of various distinct platforms and is widely and - freely available.

    - -

    It also uses the native command line shell. You thus - don't need a Unix-like shell on your platform. - For example, FreeType 2 already compiles on Unix, Dos, Windows - and OS/2 right "out of the box" (assuming you have GNU Make - installed).

    - -

    Finally, note that the build system is specifically designed - for gnu make and will fail with any other make tool. We have - no plans to support a different tools, as you'll rapidly - understand by reading this document or looking at the sub-makefiles - themselves.

    -
- - -

4. Automatic host platform detection

-
    -

    When you launch the build system for the first time, by simply invoking - GNU make in the top-level directory, it automatically tries to detect - your current platform in order to choose the best configuration - sub-makefile available. It then displays what it found. If everything - is ok, you can then launch compilation of the library, by invoking make - a second time.

    - -

    The following platforms are currently automatically detected:

    -
      -
    • Dos (plain-dos, windows in Dos mode, or Dos session under OS/2) -
    • Windows 95, 98 + Windows NT (a.k.a win32) -
    • OS/2 -
    • Unix (uses Autoconf/Automake) -
    - -

    Note that adding support for a new platform requires writing a minimal - number of very small files, and simply putting them in a new sub-directory - of freetype2/config.

    -
- - -

5. User-selectable builds

-
    -

    The platform auto-detection rules try to setup the build for a default - compiler (gcc for most platforms), with default build options - for the library (which normally is - "all features enable, no debugging"), as well as the default - list of modules (which is "all modules in freetype2/src")

    - -

    There are cases where it is important to specify a different compiler, - different build options or simply a different module list. The FreeType 2 - build system is designed in such a way that all of this is easily possible - from the command line, without having to touch a single file. - The latter is crucial when dealing with projects that need specific - builds of the library without modifying a single file from the FreeType - distribution.

    - -

    The exact mechanism and implementation to do this is described later in - this document. It allows, for example, to compile FreeType with any of - the following compilers on Win32: gcc, Visual C++, Win32-LCC.

    -
- - -

6. Robustness

- - - -

7. Simple Module Management

-
    -

    FreeType 2 has a very modular design, and is made of a core - base layer that provides its high-level API as well as - generic services used by one or more modules. - - Most modules are used to support a specific font format (like TrueType - or Type 1), and they are called font drivers. However, some of - them do not support font files directly, but rather provide helper - services to the font drivers.

    - -

    FreeType 2 is designed so that adding modules at run-time is possible - and easy. Similarly, we expect many more modules to come in the near - future and wanted a build system that makes such additions to the - source package itself dead easy. - - Indeed, all source code (base + modules) is located in the - freetype2/src directory hierarchy. And the build system is - capable of re-generating automatically the list of known modules - from the contents of this directory. Hence, adding a new font driver - to the FreeType sources simply requires to:

    - -
      -

    • Add a new sub-directory to freetype2/src -

    • Re-launch the build system

      -
    - -

    There is thus no need to edit a source file

    -
- -

- -

II. Overview of the build process(es):

- -

Before describing in details how the build system works, it is essential - to give a few examples of how it's used. This section presents - what's the build process is to the typical developer:

- -

Compiling the library is normally done in two steps: the first one - configures the build according to the current platform and possible - additional parameters, while the second simply compiles the library with - the information gathered in the configuration step.

- - -

1. Build Setup

- - -

a. Default build setup

-
    -

    To configure the build, simply invoke gnu make from the top-level FreeType - directory. This will launch a series of rules that will detect your current - host platform, and choose a configuration file for you. It will then display - what it found. For example, here's the output of typing the command "make" - on a win32 platform (assuming this calls GNU make):

    - -
    
-    C:\FreeType> make
-
-    FreeType build system -- automatic system detection
-
-    The following settings are used:
-
-      platform                     win32
-      compiler                     gcc
-      configuration directory      ./config/win32
-      configuration rules          ./config/win32/w32-gcc.mk
-
-    If this does not correspond to your system or settings please remove the file
-    'config.mk' from this directory then read the INSTALL file for help.
-
-    Otherwise, simply type 'make' again to build the library.
-
-    C:\FreeType>
-
    - -

    Note that this step copies the selected configuration file (here - ./config/win32/w32-gcc.mk) to the current directory, under - the name config.mk. This file contains data that is used - to drive the library compilation of the second step. It correspond to - the platform and compiler selected by the auto-detection phase.

    - -

    Note that you can re-generate the config.mk file anytime - by invoking make setup whenever you need it, even when the file is - already present in the current directory.

    - -

    Finally, if your platform is not correctly detected, the build system will - display and use configuration information for the virtual "ansi" platform. -

    -
- -

b. Selecting another build configuration

-
    -

    You may not be really satisfied by the configuration file selected by the - auto-detection routines. Typically, you might be using a compiler that is - not the default one for your platform. It is however possible to re-launch - the build setup phase with an additional argument, used to specify a - different compiler/config file. For example, you can type the following - commands on Win32 systems:

    - -

    -

    make setup

    -     		-

    re-run the platform detection phase, and select the default compiler for it. - On Win32, this is gcc.

    -
    -

    make setup visualc

    -     		-

    re-run the platform detection phase, and select a config file that - corresponds to the Visual C++ compiler

    -
    -

    make setup lcc

    -     		-

    re-run the platform detection phase, and select a config file that - corresponds to the Win32-LCC compiler

    -
    -

    - -

    Note that a specific configuration is selected with a command that - looks like : make setup compiler, - where the compiler keywords depends on the platform. - Moreover, each one of them corresponds to a specific configuration - sub-makefile that is copied as config.mk in the current - directory.

    -
- - - -

2. Library compilation

- -

Once you're satisfied with the version of config.mk that - has been copied to your current directory, you can simply re-invoke - gnu make with no arguments. The top-level Makefile will - automatically detect the config sub-makefile in the current directory, - and use it to drive the library compilation. The latter can be seen - as a series of different steps decribed here:

- -
    -

  • Compiling the ftsystem component

      - It encapsulates all low-level operations (memory management + - i/o access) for the library. Its default version, located in - ./src/base/ftsystem.c uses the ANSI C library but - system-specific implementations are also available to - improve performance (e.g. memory-mapped files on Unix). -

    - -

  • Compiling the base layer and optional components

      - They provide the library's high-level API as well as various useful - routines for client applications. Many features of the base layer can - be activated or not depending on a configuration file named - ftoption.h -

    - -

  • Compiling the modules

      - Each module is used to support a specific font format (it is then - called a font driver), or to provide helper services to - the drivers (e.g. the auto-hinter). They are all located in - sub-directories of ./src, like ./src/truetype, - ./src/type1. -

    - -

  • Compiling the ftinit component

      - This one is in charge of implementing FT_Init_FreeType, - the library initialisation routine. It also selects what modules - are activated when a new library instance is created. -

    -
-

- -

II. Details of the build setup.

- -

When the top-level Makefile is invoked, it looks for a - file named config.mk in the current directory. - If this file is found, it is used directly to build the library - (skip to Section III for details then).

- -

Otherwise, the file ./config/detect.mk is included - by the top-level Makefile and parsed. Its purpose is to drive the - platform-detection phase, by:

- -
    -

  • Defining the PLATFORM variable, which indicates - what the currently detected platform is. It is initially - set to the default value "ansi". -

    - -

  • Searching for a detect.mk file in all - subdirectories of ./config. - Each such file is included and parsed. Each of these files must - try to detect if the host platform is a system it knows - about. If so, it changes the value of the PLATFORM variable - accordingly.

    - -

  • Copying the selected configuration submakefile to the current directory - under the name config.mk.

    -
-

This is illustrated by the following graphics :

-

- -

- -

Each system-specific detect.mk works as follows:

-
    -

  • It checks that the value of PLATFORM is currently set - to ansi, which indicates that no platform was detected - for now. If this isn't true, it doesn't do anything

    - -

  • Otherwise, it runs a series of test to see wether it is on a - system it knows about. Here are a few examples of tests:

    - -

    - Unix - -

    checks for a file named /sbin/init, and runs, when it found - it, a 'configure' script to generate the relevant config sub-makefile

    -
    - Dos - -

    checks for the COMSPEC environment variable, then tries to - run the "ver" command on the current shell to check that there - is a "Dos" substring in its output; if not, it tries to find the - substring "MDOS\COMMAND" in COMSPEC, which indicates - a Dos session under OS/2.

    -
    - Win32 - -

    if the environment variable OS is defined and has the value - Windows_NT, or if COMSPEC is defined and the - "ver" returns a string that contains Windows in it, - we're on a Win32 system.

    -
    -

    - -

  • It sets the value of PLATFORM to a new value corresponding - to its platform.

    - -

  • It then tries to select a configuration - sub-makefile, depending on the current platform and any optional - make target (like "visualc" or "devel", etc..). Note that it can - even generate the file, as on Unix through Autoconf/Automake.

    - -

  • It copies the selected configuration sub-makefile to the current - directory, under the name config.mk -

- -

If one wants to support a new platform in the build system, it simply needs - to provide:

- -
    -
  • A new subdirectory, in ./config, with a file named - detect.mk in it, containing relevant checks for the system. - -
  • One or more configuration sub-makefiles that will get copied to - config.mk at build setup time. You can use the one in - ./config/ansi/config.mk as a template. -
- -

Similary, supporting a new compiler on an existing system simply means:

-
    -
  • Writing a new config sub-makefile that contains definitions used to - specify the compiler and flags for the build. - -
  • Change your ./config/system/detect.mk to recognize - a new optional build target that will copy your new config sub-makefile - instead of the default one. -
- - -

-

III. Details of the library compilation.

- -

When the top-level Makefile is invoked, it looks for a file named - config.mk in the current directory. If one is found, it - defines the BUILD_FREETYPE variable, then includes and parses it. - The structure of this file is the following: -

- -
    -

  • First, it defines a series of Make variables that describe - the host environment, like the compiler, compilation flags, - object file suffix, the directory where all object files are - placed, etc..

    - -

  • If BUILD_FREETYPE is defined, it includes the file - ./config/freetype.mk, which is in charge of - defining all the rules used to build the library object files. - (The test is useful to use the config.mk file to - compile other projects that rely on FreeType 2, like its - demonstration programs).

    - -

  • Finally, it defines the rule(s) used to link FreeType 2 object files - into a library file (e.g. libfreetype.a, freetype.lib, - freetype.dll, ...). Unfortunately, the command line interface of link tools is - a lot less standardized than those of compilers, which - explains why this rule must be defined in the system-specific - config.mk.

    -
- -

The following is an explanation of what ./config/freetype.mk - does to build the library objects: -

- -

a. Include paths

-
    -

    To avoid namespace pollution, the freetype directory prefix - is used to include all public header files of the library. This means - that a client application will typically use lines like:

    - -
    
-    #include <freetype/freetype.h>
-    #include <freetype/ftglyph.h>
-
    - -

    to include one the FreeType 2 public header files. freetype.mk - uses a variable named INCLUDES to hold the inclusion - paths list, and thus starts by adding ./include to it. However, - nothing prevents - -

    freetype.mk uses a variable named INCLUDES - to hold directory inclusion-path to be used when compiling the library. - It always add ./include to this variable, which means - -

- -

b. Configuration header files:

-
    -

    Three header files used to configure the compilation of the - FreeType 2 library. Their default versions are all located in the - directory ./include/freetype/config/, even though - project specific versions can be provided on a given build, as - described later:

    - -
      -

      #include <freetype/config/ftoption.h>

        - This file contains a set of configuration macro definitions that - can be toggled to activate or deactivate certain features of the - library. By changing one of these definitions, it is possible to - compile only the features that are needed for a specific - project. Note that by default, all options are enabled. -

        - You might need to provide an alternative version of ftoption.h - for one of your own projects. -

      - -

      #include <freetype/config/ftconfig.h>

        - This file includes ftoption.h but also contains some automatic - macro definitions used to indicate some important system-specific - features (e.g: word size in bytes, DLL export prefix macros, etc..). -

        - You shouldn't normally need to change or provide an alternative - version of this file. -

      - - -

      #include <freetype/config/ftmodule.h>

        - This file is very special, as it is normally machine-generated, and - used by the ftinit component that is described below. To - understand it, one must reminds that FreeType 2 has an extremely - modular design and that it's possible to change, at run-time, - the modules it's using. The ftmodule.h file simply contains - the list of modules that are registered with each new instance of - the library. -

        - Note that the file can be re-generated automatically by invoking - make setup from the top-level directory. The re-generated - list contains all the modules that were found in subdirectories of - ./src. -

      -
    - -

    Note that we strongly advise you to avoid modifying the config files - within the FreeType 2 source directory hierarchy. Rather, it's possible - to specify alternative versions through the help of a build-specific - include path that is include before ./include in the inclusion - path.

    - -

    For example, imagine that your platform, named foo, needs a - specific version of ftoption.h -

- -

a. Compiling the ftsystem component:

-
    -

    FreeType 2 encapsulates all low-level operations (i.e. memory management - and i/o access) within a single component called ftsystem. - Its default implementation uses the ANSI C Library and is located - in ./src/base/ftsystem.c.

    - -

    However, some alternate, system-specific, implementations of - ftsystem are provided with the library in order to support more - efficient and advanced features. As an example, the file - ./config/unix/ftsystem.c is an implementation that - uses memory-mapped files rather than the slow ANSI fopen, - fread and fseek, boosting performance significantly.

    - -

    The build system is thus capable of managing alternate implementations - of ftsystem

    -
- -

b. Compiling the base layer and optional components:

-
    -

    The high-level API of the library is provided by a component called the - base layer, whose source is located in ./src/base. This - directory also contains one or more components that are optional, i.e. - that are not required by the library but provide valuable routines to - client applications.

    - -

    The features of the base library and other components are selected through - a single configuration file named - ./include/freetype/config/ftoption.h. It contains a list - of commented configuration macro definitions, that can be toggled to - activate or de-activate a certain feature or component at build time.

    - -

    For example, the code in ./src/base/ftdebug.c will be compiled - only if one of these two macros are defined in ftoption.h: - FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE

    -
- -

c. Compiling the modules:

-
    -

    Once the base layer is completed, the build system starts to compile each - additional module independently. These are simply defined as all source - code located in a sub-directory of ./src that contains a file - named rules., for example: - src/sfnt, src/truetype, src/type1, ...

    - -

    The rules. file simply contains directives used by the - build system to compile the corresponding module into a single object - file.

    -
- -

d. Compiling the ftinit component:

-
    -

    The file ./src/base/ftinit.c is special because it is used - to implement the library initialisation function FT_Init_FreeType. -

    -
- -

Typically, you will end up with all object files, as well as the - corresponding library file, residing in the freetype2/obj - directory.

- - -

1. Purpose of the configuration sub-makefile

- -

2. Managing module dependencies

- -

3.

- -

- -

IV. Managing the modules list

- -

- The build system features some important points, which are all detailed - in the following sections:

-

    -
  • Automatic host platform detection
    - The first time the top Makefile is invoked, it will - run a series of rules to detect your platform. It will then - create a system-specific configuration sub-Makefile in the - current directory, called config.mk. You can now - invoke the top Makefile a second time to compile the - library directly. -

    - The configuration sub-makefile can be regenerated any time - by invoking "make setup", which will re-run the - detection rules even if a config.mk is already present. -

    - - -

  • User-selectable builds
    -

    - - - -

  • Automatic detection of font drivers
    - FreeType is made of a "base" layer that invokes several - separately-compiled modules. Each module is a given - font driver, in charge of supporting a given font format. -

    - The list of font drivers is located in the file - "freetype2/config/system/ftmodule.h", however - it can be regenerated on-demand. Adding a new module to the - FreeType source tree is thus as easy as:

    -

      -
    • create a new directory in "freetype2/src" and - put the new driver's source code and sub-makefiles there. -

      - -

    • invoke the top Makefile with target - "modules" (as in "make modules"), - as this will automatically regenerate the list of - available drivers by detecting the new directory and - its content. -
    -

    -

- - -

- -

II. Host Platform Detection

-
    - When the top-level Makefile is invoked, it looks for a - file named config.mk in the current directory. If this - file is found, it is used to build the library - (see Section III). -

    - Otherwise, the file freetype2/config/detect.mk is included - and parsed. Its purpose is to:

    -

      -
    • Define the PLATFORM variable, which indicates - what is the currently detected platform. It is initially - set to the default value "ansi". -

      - -

    • It searches for a detect.mk file in all - subdirectories of freetype2/config. Each such - file is included and parsed. Each of these files must - try to detect if the host platform is a system it knows - about. If so, it changes the value of the PLATFORM - accordingly. -
    -

    - This is illustrated by the following graphics :

    -

    - -
    -

    - Note that each system-specific detect.mk is in charge - of copying a valid configuration makefile to the current directory - (i.e. the one where make was invoked), depending on the - current targets. For example, the Win32 detect.mk will - be able to detect a "visualc" or "lcc" target, - as described in section I. Similarly, the OS/2 detect.mk - can detect targets like "borlandc", "watcom" - or "visualage", etc.. -

- -

- -

III. Building the library

-
    - When the top-level Makefile is invoked and that it finds - a config.mk file in the current directory, it defines - the variable BUILD_FREETYPE, then includes and parses the - configuration sub-makefile. -

    - The latter defines a number of important variables that describe - the compilation process to the build system. Among other things:

    -

      -
    • the extension to be used for object files and library files - (i.e. .o and .a on Unix, .obj - and .lib on Dos-Windows-OS/2, etc..). -

      - -

    • the directory where all object files will be stored - (usually freetype2/obj), as well as the one - containing the library file (usually the same as for - objects). -

      - -

    • the command line compiler, and its compilation flags for - indicating a new include path (usually "-I"), - a new macro declaration (usually "-D") or - the target object file (usually "-o ") -
    -

    - Once these variable are defined, config.mk test for the - definition of the BUILD_FREETYPE variable. If it exists, - the makefile then includes "freetype2/config/freetype.mk" - which contains the rules required to compile the library. -

    - Note that freetype.mk also scans the subdirectories of - "freetype2/src" for a file called "rules.mk". - Each rules.mk contains, as it names suggests, the rules - required to compile a given font driver or module. -

    - Once all this parsing is done, the library can be compiled. Usually, - each font driver is compiled as a standalone object file (e.g. - sfnt.o, truetype.o and type1.o). -

    - This process can be illustrated by the following graphics:

    -

    - -
    -

    -

- -

- -

IIV. Managing the list of modules

-
    - The makefile freetype.mk only determines how to compile - each one of the modules that are located in the sub-directories of - freetype2/src. -

    - However, when the function FT_Init_FreeType is invoked at - the start of an application, it must create a new FT_Library - object, and registers all known font drivers to it by - repeatly calling FT_Add_Driver. -

    - The list of known drivers is located in the file - "freetype2/config/system/ftmodule.h", and is used - exclusively by the internal function FT_Default_Drivers. The - list in ftmodule.h must be re-generated each time you add - or remove a module from freetype2/src. -

    - This is normally performed by invoking the top-level Makefile - with the modules target, as in:

    -

      - make modules -
    -

    - This will trigger a special rule that will re-generate - ftmodule.h. To do so, the Makefile will parse all module - directories for a file called "module.mk". Each - module.mk is a tiny sub-Makefile used to add a single - module to the driver list. -

    - This is illustrated by the following graphics:

    -

    - -
    -

    - Note that the new list of modules is displayed in a very human-friendly - way after a "make modules". Here's an example with the current - source tree (on 11 Jan 2000):

    - 

      -Regenerating the font drivers list in ./config/unix/ftmodule.h
-* driver:  sfnt      ( pseudo-driver for TrueType & OpenType formats )
-* driver:  truetype  ( Windows/Mac font files with extension *.ttf or *.ttc )
-* driver:  type1     ( Postscript font files with extension *.pfa or *.pfb )
--- done --
-
    - -
- -

- -

V. Building the demonstration programs

-
    - Several demonstration programs are located in the - "freetype2/demos" directory hierarchy. This directory also - includes a tiny graphics sub-system that is able to blit glyphs to - a great variety of surfaces, as well as display these in various - graphics libraries or windowed environments. -

    - This section describes how the demonstration programs are compiled, - using the configuration freetype2/config.mk and their own - freetype2/demos/Makefile. -

    - To compile the demonstration programs, after the library, - simply go to freetype2/demos then invoke GNU make with no - arguments. -

    - The top-level Makefile will detect the config.mk in the - upper directory and include it. Because it doesn't define - the BUILD_FREETYPE variable, this will not force the - inclusion of freetype2/config/freetype.mk as described in - the previous section. -

    - the Makefile will then include the makefile called - "freetype2/demos/graph/rules.mk". The graphics rules.mk - defines the rules required to compile the graphics sub-system. -

    - Because the graphics syb-system is also designed modularly, it is able - to use any number of "modules" to display surfaces on the screen. - The graphics modules are located in the subdirectories of - freetype2/demos/config. Each such directory contains a file - named rules.mk which is in charge of:

    -

      -
    • detecting wether the corresponding graphics library is - available at the time of compilation. -

      -

    • if it is, alter the compilation rules to include the graphics - module in the build of the graph library. -
    -

    - When the graph library is built in demos/obj, the - demonstration programs executables are generated by the top-level - Makefile. -

    - This is illustrated by the following graphics:

    -

    - -
    -
- -

-
- - - diff --git a/docs/design/demo-programs.png b/docs/design/demo-programs.png deleted file mode 100644 index f796396973e0df18b9d9ce59a857d9534106fd06..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2837 zcmV+w3+nWVP)Wgi<$K686$}Zuc2LL91#>GysEEZyneE!9 zN+w%O+WH|`Q1AUJl|F8K)vB=BK{~*!S6%5!S6^$z3D3WR${s2nmBA?}P&Quurm7Rg zg{X0PHNHV!RmiFZd9|RRish9_RxQh`Wd&6stKy)niWj69ldNL+FG|JNJ4b1L&SpJf+)hf5Ye%lq7S7Di9X_jJ4!pY7Iajv|Q*u1v*-5y)j_(Ye)%#c{M31iGl>q|0?ViqOzV zmZFl%pP`nXLVN8%SHGbC@%(z4hMc+TDwR_fi}uFiBygMrTm(($l*L6L2%=`ttajlj zWT8pGLR!UkU4UHK*YJp;1o-&$>5OZ*q2#o;DBgPN$yQrw_n`5t!I0YzsgZpBkfmTA zy3(lNRJ2T~RnC-}NUAWO44~IgSV}=jMWsS?H3}4=6a=rW`~|5A;S{dCro&!* z#9RISQ@1Ws|EU5>jgBQnH7+O?y>r1r5YUAy0QA0h-erk++Hqx7Cq(!NGWK6C&86asfUXm;W(Z# zmdGotAjM~>ceE;f+$dZXHqPsFr5*$5&)1i)xO5<(HU>ziE%3!jCC)+ zCD0AmTGpJ+lW7abVgw!_o$df-iSocveyy^SX$!rQ`U@?n$3UQa&2}Zz76e5!lJ2mF zvheU)Wl`z0g)xF4SZW{Ui2>bL0E?muQt7k>Z)tN&S$yK;wPVkoeskM4laeCS-A)YB z*ofA7xp2j8(PIET2GErr1L*2&qF9y6nW1Qvsy{<*@~TrOS1S&2sZ%F_)y;xHHA;9K zo>}#lv4Vw^HP@xRU9`Ej3{s^|6?B*F1u0m6QuG)=SNd$Os|-ayTGex^R3fFMZBc==am$|yJ2X=gG$LU^l$0_z~v!eO1Z2RN@y44G6$sO z7|25b0N|NLE&CMPMN#}h&``37Ny#z&o|0`lsEW!riZ-6ME2wlogn22=g(X+zV||$_ z-ol>^J7_s?+W(QsAN>{ql)mNxO9m4d_bEed;fl75>P#;OT&|*f#l1e3h zH1tT3DpdT9Gh3&c+sZfZWOhytzy8{HcAoG)ef`Yf#

>ZL;dqJ>xa)?N6BMD-)Fq zn|JIz|DJE?ROp|T!_5m%%d6=0w4nBw8n!03h8#7m4#qb$6!KRNGoiEm8mbL!s7_Q1 z>WE`mQdP#~&@d>k_K50bzM(2nC8%FHLX!F+6AHa6U&DCt%%<^mFPIDl#xObX`uY>g zFSHsK`v*!6H=kgXu6#7->k?s}DPHS-35v$D6icq97IVHXF(CzB-=^n_d7OXrRfF^u zBgBiq(mW^T%FwLv)MY95Lq3&3<%fAcnS?ByTx>DoGK@+{IJ1VHhh@Ry_pr%_TcP4d zoYI1b<;Yxhsc&F@<^B=>_EPXUudy{8e8u>?SNpyKDU{ZrjkO5UFICB{Qui59FsnZq(B@Ewo=@NtK!CX#ZsaBz4Zv>N@MIe~9ar97$ zXS38JB~1+=nNrDjxk{)Rm`JsO*%EI~58JAMv3xe&v2B zC1J$G?IAY*x-_pM#XE~jn@Xv-Dpi6n6Gz*y2BpV`y3*C>Qk1OXKyGs$5LHsapfGTw zc~r(&uu2J2m6wl(1;wVOOOx;q16D{s=T|W6=ljBZbdKX`=?qv@you}EFVxJGtQ;nz zA|pk!J9c~16Qs~cF_ITl|A1p9n5E84l`IdvUBAbRUnWolg3fF^P+o3qMh08zdtNRX zy76-pU}+~Fj=m{%edx!DQ&qO>f5kfq2!X8QHG7-(HXZnL)!rK0TW#y_Kh+eA5dkbq zP1jZ?&b8a7tLM=`&u-U->6+H2JxvGy)xNos@%e`C?`a~6h(I_?4b{9Bt!hpT6{9F> zr2z2U!GGI6woOm9Z#tOpO;`KQ_Yo`_pusFv)gG;COAOVa=tal{0Ot;VU~^oXo^6|c zFEQ+>_BlMWIEq49>g?bTR<=FXbGFz%xYq~N+Rtr$+*ogW2`l~hz_CjW&rY5OtIOtt zQ%e0Xa}G(Y>TF6Xb2hm7=tovbIWyjQRjP0B2rww!PlnN^Wr-X4p3r^4-&_9KKqg@1Djh&p3uZX>$alQEh7DaQ#$6SffgB n0Tj}sMha3+eTLPQuF~p%6(AvR<`k5600000NkvXXu0mjfV{~r_ diff --git a/docs/design/drivers-list.png b/docs/design/drivers-list.png deleted file mode 100644 index 0cf79fa689d49ce513231b5b02b4c03f0e3092a9..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1792 zcmV+b2mknqP)$Ug1U)$`DYtLi}W8D3- zzV_4az1_Wj-?#6z2iZr)l>;xDlRWI+}PQ9W5xJXZ+N`-s;hS@ zTUn$g`jQVl1jd?3l0^MYbhav%ni%k50E{tyAL;co_cN53CzeUg07wN?^<6C!(TK$Z zUYxo8ax5V$)?B}wC@LwE97QiNIr?Rln(i8>yR`ah-M)JhB_Gw*Az4aoX5IHR#p_b= zf2pPY>Cl%ajJ#@O@Rg(t)$ixg69N_j3R@sBdg6ZPTJ(z2X6T3*Ja5I+CimKCN)37uBn$k9f|G;;Lgr4s*DoR(5^ zv~sYT$}+E#uUfQJ@x0>gR8BQpM=QtQG}IAmhSt+BZjaW?r_|B%L0=wmuo_C&RppKG zW#nihuP!>p!i+cMRo0lg0hCu^yt+k~rjlxtfXb^H%BoA5#Af^r&(CX3p3dO;nu;AB zY5O5lEti&PJ^&~R4tGqp5aQoSIlZRmRq5t)42PoaTnBSMf(~-hmO+|=N~|~o(NKG_ zqKc*MhfF2)3)-PG)DE4pg1KTz*_UetP8I+sLlfu@hqV2WsiYZZI^c1!rV|@(zE)H6 zS&y{+kfBmaQ-Ca@xf(Us6vX;ikE*p6R(Z$Qqpu3*38*XQ7|KwFGSre+$tpyy4Fs!D zAwC(G9!0X0ApN{gRJ;{d2rzmO5ulcWva$*=789o=YxWt1Q{m%1D~}%=f5BR|vTc04 zq~5hZ#CZJ8<&oH!fY6f3uEt&!BuMD^rb zHcQ4CN5+HhnxH3E4l7Q~s@;)5rV0k1PX>`#Ikj~}Rgnr?Q~DW`^?SRIKC`lTy0o^a zMCyH=Ywb|g(33!R0PV1ZqWY2;jMRhQ(X8joXPSbUU{Yf6e!ms3SW z?2>lSq)Q=IgArUT4!NXKZ}vwZlIm9!&(6l;!@UL^F@lO}Ll5E zF+&XPMjUN+9-VQp0g~`CWN0-xKobKN&_Q;oiehN2AM`O|EC=gVREMmfs4!I#%nt)p zBhlQB(v1O8eLuB_ZSf7zpFT~!)3HZ606(&%a(h~St1+$bD_FLu1SW^8a z!>dIhJ3k7=_o%Tjaa<+$hgp88ym$Cbc(8$~N>q%h>O#}+*mj($IaCtmck!18B!JMAg~QxG%<78&VwX} zjX~f?ixGw=?^dTsd|vqpj3#K5;Q?&LFmddmop2*Z5(1B2oK=m4nUK!-O|uhlttb|; zb$A`g6gNtIdkgidDsXBQwhSMxnLZnxE{n4Pgg@!Rdw8Ck7&&n3$`y@kkEGvDnDooe%ac#~30000 - - - - - - FreeType 2 Internals - - - - - -

-

-FreeType 2.0 Internals

- -
-

-Version 1.2

- -
-

-© 1999-2000 David Turner (david@freetype.org)
-© 1999-2000 The FreeType Development Team (devel@freetype.org)

- -


-

-
  -

Introduction:

- -

This document describes in great deatils the internals of FreeType 2. - It is a must read for porters and developers alike. Its purpose is to - - present the -

This document describes in great details the internals of the -FreeType 2.0 library. It is a must read for porters and developers alike. -Its purpose is to present the engine's objects, their roles and interactions. -It is assumed that the FreeType Glyph Conventions document -has been read. -

We advise porters to also read the FreeType Porting Guide -after this document. Would-be hackers and maintainers are of course encouraged -to read the FreeType Coding Conventions document too. The -development of a new driver is described in more details in the FreeType -Driver HowTo document.

- -


-

-

-I. Overview :

- -
-

-1. Features (and what's new) :

- -
FreeType 2.0 has a number of important new features that were -not found in the 1.x releases : -
  -
font-format independent API -
FreeType 2.0 is able to support any kind of font format, be it fixed -or scalable, through the use of pluggable "font drivers". These drivers -can be added or replaced at run time, while applications use a new font -format-independent API. -

advanced stream caching -
2.0 is able to control the number of concurrently opened streams when -using fonts. It is thus possible to open dozens or hundreds of font faces -without running out of system resources. -

real reentrancy support -
It is now possible to use FreeType as a shared library with no static -data in a multi-threaded environment. The synchronization model has also -been simplified in order to make font driver writing easier. Of course, -you can build FreeType with no thread support to get a smaller library. -

support for cubic beziers and 17-levels anti-aliasing -
The FreeType scan-line converter (a.k.a. raster) now supports cubic -bezier arcs seamlessly. It also provides a new anti-aliasing mode which -uses a palette of 17 levels of grays. -
 

-It also features the following : -
performance improvements : -
The FreeType raster has been optimized, and the generation of anti-aliased -pixmaps is now 60% faster than in the 1.x release. Moreover, the TrueType -bytecode interpreter has been profiled and greatly optimised. -

easier portability -
Porting and configuring FreeType is now much easier. A single file -must be provided for system-specific operations (like memory, i/o, thread -management), and a single configuration header is used to select the build -you need. -
 

-
- -

-2. Architecture :

- -
The engine is now split in several parts, which are : -

-a. The base layer :

- -
This part contains all the font-format independent features -of the engine which are : -
    -
  • -computations/scaling
    • - -
  • -list processing
    • - -
  • -outline processing
    • - -
  • -scan-line converter
    • - -
  • -stream manager
    • - -
  • -base object classes
    • - -
  • -debugging & traces
    • - -
  • -high-level API functions
    • - -
  • -low-level system object (memory, i/o, threads)
    • -
-
- -

-b. The font drivers :

- -
Each font format is managed with the use of a single font driver -object. The base layer is able to manage several drivers, and these can -be easily added, removed or upgraded at runtime. Each driver has the following -features and functions : -
    -
  • -auto-check font format when opening a font resource (i.e. file)
    • - -
  • -access, load and/or extract all tables and data from the font file
    • - -
  • -grid-fit/hint the glyph outlines (in the case of scalable formats like -TrueType or Type1)
    • - -
  • -provide extensions to access font format-specific data and tables from -the font file
    • -
-Note that FreeType 2.0 is a font service. Its purpose is to provide a unified -API for all kinds of fonts and extract individual glyph images and metrics. -However, it does not render text itself, as this operation is left to the -developer, or to higher-level libraries built on top of FreeType. Here -are a few features that are thus not implemented : -
1) Text string rendering -
2) Glyph bitmap/outline caching for improved performance -
3) Synthetic fonts (i.e. italicising, emboldening, underlining) -
4) Contextual glyph substitution and other advanced layout processes
-Note that features 1 through 3 should be provided by the SemTex library, -which may soon become part of the standard FreeType distribution.
-
-
- -


-

-

-II. Design :

- -
-

-1. Objects :

- -
They are several kinds of objects in FreeType, which can be -described as follows : -
Base objects -
These objects do not relate directly to font data, but to the way it -is organised and managed. It is the basic core and provides functions that -are heavily used by each font driver. Examples are the resource objects, -used to describe font files, the system object used to manage low-level -system operations, or the raster object, used to convert vector outlines -into bitmaps or anti-aliased pixmaps. Most of the base objects are not -directly visible for client applications of FreeType. -

Font objects -
The font objects directly model the data as it is found in font files. -The root classes implemented in the base layer like FT_Face, FT_Size, -FT_GlyphSlot, -must be derived in each font driver.

-Objects are defined in the files "base/freetype.h" and "base/ftobjs.h". -The former contains all the public object definitions usable by client -applications. The latter contains private definitions used by the rest -of the base layer and each font driver.
- -

-2. List management

- -
The "base/ftlist.c" component a very simple doubly-linked -list facility which is used by the rest of the engine to create and process -lists, including iteration and finalisation. The definition of the list -node and functions are placed in the "base/freetype.h" to let -client applications access listed objects as they like. -

The base list type is FT_List, which links nodes of type FT_ListNode -together. -
 

- -

-3. Limited encapsulation

- -
Unlike what happened in the 1.x releases, the FT_Face, -FT_Size, -FT_GlyphSlot and FT_CharMap types are no longer blind -pointers to opaque types. Rather, the corresponding structures are now -public (and defined in "base/freetype.h", see FT_FaceRec, -FT_SizeRec, -etc..) in order to let client applications read directly the various object -attributes they're interested in. -

This breaks encapsulation of implementation, famed by OOP, but was chosen -because: -
  -

    -
  • -it simplifies a lot the work of client applications and libraries which -don't need to perform a function call everytime they want to read one important -object attribute (nor does it force them to cache these attributes in their -own structures).
    • -
- -
    -
  • -It reduces greatly the API, as many FT_Get_XXX functions are avoided.
    • -
- -
    -
  • -Higher-level libraries are able to  access data directly. When it -is used frequently, they don't need to cache it in their own structures.
    • -
- -
    -
  • -It is possible to tightly link FreeType objects with higher-level ones, -in a clearer and more efficient way. This is very important when one wants -to write a C++ wrapper or a text rendering library on top of FreeType (actually, -both projects were performed in an earlier version of FreeType 2.0 which -featured classic encapsulation through get/set methods. The resulting code -was ugly and slow. Moving to a limited encapsulation approach simplified -so many things that the compiled code size was reduced by a factor of two -!).
    • -
- -
    -
  • -Finally, the API and font object structures were designed after the creation -of two scalable font drivers and one bitmap font driver. They are now very -stable and the public (visible) attributes are not going to change.
    • -
-
-
- -


-

-

-III. Base objects :

- -
This section describes the FreeType base object classes : -
  -

-1. System objects :

- -
The system class is in charge of managing all low-level and -system-specific operations. This means simply memory management, i/o access -and thread synchronisation. It is implemented by the "ftsys.c" -component, whose source must be located in the configuration directory -when building FreeType. (e.g. "lib/arch/ansi/ftsys.c" for an ANSI -build, "lib/arch/unix/ftsys.c" for a Unix one, etc..). -

Porting FreeType 2.0 really means providing a new implementation of -ftsys -(along with a few configuration file changes). Note however that its interface -is common to all ports, and located in "base/ftsys.h".

- -

-2. Resources and Streams:

- -
The concepts of files as storages, and files as streams has -been separated for FreeType 2.0. The "resource" concept was -introduced while the "stream" one has been redefined. Here -is how they work together : -
    -
  • -a "resource" is an object which models a file, seen as a storage. -There are several classes of resources, which differ usually in two ways -: the way their data is accessed by applications, and the way they're named -within the system.
    • -
- -
    For example, when parsing files with the ANSI C library, data has to -be read (through fseek/fread) into intermediate buffers before it can be -decoded. This scheme is highly portable, but rather inefficient; when using -it, we'll describe the file as a disk-based resource. -

    As most modern operating systems now provide memory-mapped files, which -allow direct access while improving performance and reducing memory usage. -Because data can be read directly in memory, we'll speak of a memory-based -resource in this case. For embedded systems (like printers, PDAs, etc..), -ROM-fonts fit into this category as well. -

    Regarding naming, most systems use a string to name files in their storage -hierarchy. Though a typical pathname is an ASCII string ('c:\windows\fonts\times.ttf' -on Windows, '/home/fonts/times.ttf' on Unix), some OSes use different -schemes, varying from Unicode character strings to file i-node numbers. -These details are platform-specific and must be hidden to the rest of the -library in resource objects. -

    A resource encapsulates the lowest details regarding a file, though -it should have NO STATE. Note that the nature or type of a resource (i.e. -disk or memory based) is important to the "stream" component only. The -rest of the library and font drivers work transparently from their implementation. -

    Note also that it is perfectly possible to mix resources of distinct -natures in a single build

- -
    -
  • -a "stream" is an object which is used to extract bytes from a resource. -Only resource objects can create streams, through its Open_Stream() -method. A stream has state, which typically consist of a file "cursor", -some intermediate buffers, a "current frame" and, of course, methods used -to extract the data from streams, resolving endianess and alignement issues.
    • -
-Data can be extracted from streams through direct reads, or through the -use of frames. A frame models a run of contiguous bytes starting -from the current stream position, and of liberal size. -

Methods exist to extract successive integers of any sizes, while resolving -endianess and alignement issues. Rather than a long rethorical explanation, -here's how frames are typically used : -

{ -
  … -
  FT_Error  error; -

  error = FT_Access_Frame( stream, 14 ); -
  if (error) goto Fail; -

  val1 = FT_Get_Short(stream); -
  val2 = FT_Get_Long(stream); -
  val3 = FT_Get_Long(stream); -
  val4 = FT_Get_Long(stream); -

  FT_Forget_Frame(stream); -
  … -
}

-This code does the following : -
-
    -
  1. - first, it "loads" the next 14 bytes from the current cursor position -into the stream's frame, using the FT_Access_Frame API. An error -is returned if, for example, less than 14 bytes are left in the stream -when the call occurs..
    2. -
- -
    -
  1. - it extract four integers (one 16-bit short, three 32-bit longs) from -the frame using FT_Get_Short and FT_Get_Long. These function -increment the frame's cursor finally, it "releases" the stream's frame.
    2. -
- -
    -
  1. - Each stream has its own frame which can be accessed independently, -however, nested frame accesses are not allowed. Note also that the bytes -are effectively read from the stream on the call to FT_Access_Frame. -Any subsequent read will occur after these 14 bytes, even if less are extracted -through FT_Get_xxxx functions.
    2. -
-
-The implementation of the resource class is located in the system component -(i.e. "arch/<system>/ftsys.c") and can thus be tailored -for a specific port of the engine. -

A resource can be created through the FT_New_Resource API; -however this function only accepts an 8-bit pathname to name the target -font file, which may be inappropriate for systems using a different naming -scheme (e.g. UTF-16 pathname, i-node number, etc..). It's up to the porter -then to provide its own resource creation function (like. FT_New_UTF16_Resource, -for example) in its version of "ftsys.c". -

Note that FT_New_Resource will fail and return an error code -if the font file cannot be found, or when its font format isn't recognized -by one of the drivers installed in the library. The list or resources created -for a given library instance is thus the list of "installed font files". -
 

- -

-3. Stream Manager :

- -
As said before, resources do not bear states, while streams -do. Stream creation is also a very lengthy process, depending on the target -operating system (e.g. "fopen" is usually very slow). -

Because a typical font driver will want to use a new stream on each -access to individual glyphs, being able to cache the most recently used -streams is a requirement in order to avoid considerable performance penalties. -

Stream caching is thus implemented in the "ftstream" component. -It maintains a simple LRU list of the least recently used streams. Each -stream in the cache is still opened and available for immediate processing. -When a resource is destroyed, the stream cache is parsed to remove all -related cached streams. -

Stream caching can also be disabled with a configuration macro when -using only ROM based resources (where stream opening is really quick). -It is implemented through a Stream Manager object (see ftstream.c). -
 

- -

-4. Raster :

- -
The raster is the component is charge of generating bitmaps -and anti-aliased pixmaps from vectorial outline definitions. It is also -sometimes called the scan-line converter. It has been completely rewritten -for FreeType 2.0 in order to support third-order bezier arcs, 17-levels -anti-aliasing (through 4x4 sub-sampling), improved performance, as well -as stand-alone compilation (in order to include it in other graphics package -without requiring the rest of the FreeType engine). -

Because it was designed for easy re-use and embedded systems, the raster -is a rtaher 'unusual' piece of code, because it doesn't perform a single -memory allocation, nor contain any static or global variable. Rather, it -is up to client applications to allocate a raster object in their own heap -or memory space. -

Each raster object also needs a rather large block of memory called -its render pool. The pool is used during rendering (and only during it) -in order to perform the scan-line conversion. Because it accesses and manages -data directly within the pool, the raster yelds impressive performance -as well as bounded memory consumption. It can also automatically decompose -large requests into smaller individual sub-tasks. -

Finally, it never creates bitmaps or pixmaps, but simply renders into -them (providing clipping too). These must be described to the raster with -the help of a FT_Raster_Map structure (a very simple bitmap/pixmap -descriptor). -

Note that when rendering anti-aliased pixmaps, the raster doesn't use -an intermediate bitmap buffer, as filtering is part of the scan-line conversion -process. -
 

- -

-5. Library objects :

- -
A library object models a single instance of the FreeType engine. -This is useful when FreeType is compiled as a shared object (DLL), as it -can then be used by several applications, each with its own resources and -objects. -

The FT_Library type is an opaque handle to a library object. -Such an object is created through a call  to FT_Init_FreeType. -Once you don't need it anymore, one can destroy a library object through -FT_Done_FreeType. -

Note that in reentrant builds, several threads can access a single library -object concurrently. Such a build can be chosen by switching one configuration -macro in the file 'arch/<system>/ftconfig.h'

- -

-6. Driver objects :

- -
A driver object models an instance of a given font driver, -i.e. an element of FreeType code in charge of handling a given font format, -like TrueType, Type1, FNT, PCF, etc.. -

Each library object contains a given set of driver objects when it is -created through FT_Init_FreeType, this set being determined at compile -time (see the file 'base/ftapi.c'). However, removing or adding drivers -is possible at run-time, in order to make upgrades easy.

- -

-7. Diagram

- -
This diagram show the object relationships for the sole base -layer. The library object is the root of the object graph : -
-

- -

It can be read as follows : -
  -

    -
  • -Each library object has one system, one raster and one stream manager objects. -These objects can only belong to one given library.
    • -
- -
    -
  • -Each library contains one list of 0 or more resources, as well as one list -of 0 or more driver objects.
    • -
- -
    -
  • -Each stream manager holds a bounded list ("0..n" where 'n' is the stream -cache's size) of stream objects. Each stream is related to one given resource -object. Each resource may be related to zero or one stream.
    • -
- -
    -
  • -Each resource is related to one driver object. A driver is related to 0 -or more resources.
    • -
-
-
- -


-

-

-IV. Font objects :

- -
Font objects are used to directly map the information found -in font files into several categories : -
  -

-1. Face objects :

- -
Face objects are used to model individual font faces. They -encapsulate data which isn't related to a specific character size, or a -specific glyph or glyph set. Usually, this means : -
    -
  • -the font face's family and style names (e.g. "Palatino" + "Regular")
    • - -
  • -some flags indicating which kind of font this is (scalable or fixed ? fixed-width -or proportional ? horizontal or vertical ? etc…)
    • - -
  • -the number of glyphs, charmaps and eventually fixed character sizes (for -bitmap formats) found in the font face.
    • - -
  • -for scalable formats, some important metrics like the ascender, descender, -global font bounding box, maximum advance width, etc.. expressed in notional -font/grid units (as well as the number of units on the EM grid).
    • -
-A face is created from a resource object, with the FT_New_Face -API. Each driver contains a list of opened face objects for the resources -it manages. When a driver is removed or destroyed, all its child faces -are discarded automatically with it.
- -

-2. Size objects :

- -
Size objects are used to model a given character dimension -for a given device resolution (which really means a given character pixel -dimensions). -

Each size object is created from a parent face object. The object can -be reset to new dimensions at any time. Each face object holds a list of -all its child sizes, these are destroyed automatically when the face object -is discarded. -

The metrics contains metrics, expressed in pixels, for the ascender, -descender, maximum advance width, etc.. -
 

- -

-3. Glyph Slot objects :

- -
A glyph slot is a container where one can load individual glyphs, -be they in vector of bitmap format. Each slot also contains metrics for -the glyph it contains. -

Each face object contains one or more glyph slot object : the first -glyph slot is created automatically with its parent face, and it is possible -to add new glyph slots (this is rarely used outside of debugging purposes). -
 

- -

-4. CharMap objects :

- -
A charmap object is a sort of dictionary whose task is to translate -character codes in a given character encoding (like ShiftJIS, Unicode, -ANSI, etc..) into glyph indexes in a given font face. -

A face object contains one or more charmap objects. All charmap objects -are created when the parent face is created, though they're not directly -visible to client applications (rather, they can be enumerated through -FT_Get_First_CharMap and FT_Get_Next_CharMap, or more simply picked adequately -with FT_Find_CharMap for a set of given encodings). -
 

- -

-5. Diagram

- -
The following diagram illustrates the relationships between -font objects : -
-

- -

Which can be read as : -
  -

    -
  • -each resource may have zero or more child face objects "opened" for it. -The number of faces is bounded by the number of font faces within the font -resource.
    • -
- -
    -
  • -each driver holds a list of all the faces opened for the resources it manages. -When the driver is removed, its child faces are discarded automatically.
    • -
- -
    -
  • -each face object has one single parent resource, and one single driver.
    • -
- -
    -
  • -each face has one or more charmaps, and one or more glyph slots
    • -
- -
    -
  • -each face holds a list of zero or more child size objects
    • -
- -
    -
  • -each charmap, glyph slot and size is related to one given parent face. -These objects are destroyed automatically when the parent face is discarded.
    • -
-
-
- -


-

-

-V. Driver Interface :

- -
A font driver is added to a given library object through the -FT_Add_Driver -API. This function receives a structure known as a FT_DriverInterface, -which describes the driver's basic properties. -

The FT_DriverInterface contains a set of function pointers -used for the base FreeType functionalities. However, each driver can also -provide a font-format-specific extended interface to allow client applications -to use more advanced features. -
  -

-1. Common Interface

- -
The structure of FT_DriverInterface is rather simple, -and defined in "base/ftdriver.h". It must be well known by any -developer who wants to write a new driver for the engine. We advise reading -the FreeType Driver HowTo as well as the source code of existing -drivers. Source comments.
- -

-2. Driver-specific extensions

- -
The field of the FT_DriverInterface structure is a -typeless pointer to a format-specific interface. This extended interface -is usually a structure containing function pointers as well as other kind -of information related to the driver. -

It is assumed that client applications that wish to use the driver-specific -extensions are able to #include the relevant header files to understand -the format-specific interface structure.

-
- -
-

-VI. Configuration:

- -
This section relates to the configuration of the FreeType library. -By configuration, we mean selection of build options as well as the choice -of font drivers to be used for each new library object. -
  -

-1. Configuration files :

- -
A single file is used to configure the FreeType base engine. -As it is considered system-specific, it is located in the architecture -directories of the library, under the name "arch/<system>/ftconfig.h". -Note that the same directory should also contain a platform-specific implementation -of "ftsys.c". -

The configuration files is a simple C header which is included by the -engine's sources during compilation. It is not included in "freetype.h", -and hence doesn't need to be copied when installing the FreeType headers -on your system. -

It is made of a series of #define or #undef statements, which are used -to select or turn off a specific option. Each option is documented with -heavy comments, and some of them are explained below.

- -

-2. Building and Makefiles :

- -
FreeType 2.0 is more complex than its 1.x release. In order -to facilitate maintenance, as well as ease considerably the writing of -new font drivers, only GNU Make is supported with FreeType 2.0. -However, it is possible to use any compiler, as well as any object or library -prefix (.o, .obj, .a, .lib etc..) with them. -

To build FreeType 2.0, one has to be in the library directory, then -invoke its platform-specific makefile. For a Unix system, this would be -: -

-
% cd freetype2/lib -
% make -f arch/unix/Makefile -

where 'make' is really GNU Make !

-
-The system-specific Makefile located in 'arch/<system>' -is a tiny file used to define several variables. It then includes the file -freetype2/lib/Makefile.lib, -which contains all the gory details about library compilation. The system-specific -Makefile can be very easily modified to accomodate a new compiler/platform -(see the comments within one of these files). -

Each font driver is located in a directory like "freetype2/lib/drivers/<formatdir>". -For example, the TrueType driver is located in "drivers/truetype". -Each driver directory must contain a Makefile which will be included -by Makefile.lib. The former is used to define and build driver -object files. -
  -


-

-

-
- -

-3. Make options :

- -
The base layer, as well as each font driver, are made up of -several C sources. Traditionally, one compiles each source (i.e. '.c' -file) into an object ('.o' or '.obj') file, and all of -them are grouped into a library file (i.e. '.a' or '.lib'). -

By default, FreeType takes a slightly different approach when it comes -to compiling each part of the engine. Usually, a single tiny source is -compiled, which includes all other component sources. This results in a -single object files, with the benefits or reduced code size, usually better -compilation as well as a drastic reduction of the number of symbols exported -by the library. Of course, it is made possible through the use of specific -declaration macros in the FreeType source (see the definition of LOCAL_DEF -and LOCAL_FUNC in ftconfig.h for details). -

For a concrete example, see the source code in "base/ftbase.c" -which generates the whole base layer in a single object file. The same -build process is applied to font drivers, in order to generate one single -object file per given font format (e.g. truetype.o, type1.o, -etc..). -

Compiling the library and drivers in "normal" mode is possible, through -the use of the 'multi' target (which really means « multiple -objects »). For example, calling : -

% make -f arch/ansi/Makefile multi
-Will build the FreeType library by compiling each source file to an individual -object, then linking them together. You'll notice that the library is significantly -bigger in this case. Creating a shared dll from a 'multi' build is certainly -a very poor idea, as this will export a huge quantity of symbols that aren't -useful to any client application.
- -

-4. Adding a driver at compile time

- -
A driver can be included very easily in the build process by -including its Makefile in Makefile.lib. For example, -the TrueType driver is simply included with the following lines (see Makefile.lib): -
# TrueType driver rules -
# -
include $(DRIVERS_DIR)/truetype/Makefile
- -


Where DRIVERS_DIR really is "freetype2/lib/drivers", -though this can be redefined. You can, of course specify a different path -if you want to place your driver sources in another location. -

Note that this only adds the driver's object files to the generated -library file. A few more steps are needed to make your FT_Library -objects use the driver. They consist in modifying the file "base/ftinit.c", -whose sole purpose is to define the set of driver objects that are to be -created with each new library object. -
 

- -

-5. Adding a driver at run time

- -
New driver objects can be added at run-time through the FT_Add_Driver -API. This function takes a handle to an existing library object, as well -as a pointer to a given driver interface. This interface is used to create -a new driver object and register it within the library. -

Similarly, a single driver can be removed from a library anytime through -FT_Remove_Driver. -This will automatically discard the resources and face objects managed -by the driver.

- -

-6. Custom library objects :

- -
Finally, it is possible to build custom library objects. You -need to pass a handle to a valid FT_System object to the FT_Build_Library -API. The function will return a handle to the new fresh library object. -Note that the library has no registered drivers after the call, developers -have to add them by hand with FT_Add_Driver. -

It is thus possible to create two distinct library objects with distinct -FT_System -implementations in the same session, which can be useful for debugging -purpose.

- -
 
- - - diff --git a/docs/design/io-frames.html b/docs/design/io-frames.html deleted file mode 100644 index a5c6de7cd..000000000 --- a/docs/design/io-frames.html +++ /dev/null @@ -1,343 +0,0 @@ - - - - - - FreeType 2 Internals - I/O Frames - - - - -

- FreeType 2.0 I/O Frames -

- -

- © 2000 David Turner - (david@freetype.org)
- © 2000 The FreeType Development Team - (www.freetype.org) -

- -
- - -
- -
- -

- Introduction -

- -

This document explains the concept of I/O frames as used in the - FreeType 2 source code. It also enumerates the various functions and - macros that can be used to read them.

- -

It is targeted to FreeType hackers, or more simply to developers who - would like a better understanding of the library's source code.

- -
- -

- I. What frames are -

- -

Simply speaking, a frame is an array of bytes in a font file that is - `preloaded' into memory in order to be rapidly parsed. Frames are useful - to ensure that every `load' is checked against end-of-file overruns, and - provides nice functions to extract data in a variety of distinct - formats.

- -

But an example is certainly more meaningful than anything else. The - following code

- - - 
-    error = read_short( stream, &str.value1 );
-    if ( error ) goto ...
-
-    error = read_ulong( stream, &str.value2 );
-    if ( error ) goto ...
-
-    error = read_ulong( stream, &str.value3 );
-    if ( error ) goto ...
- - -

can easily be replaced with

- - - 
-    error = FT_Access_Frame( stream, 2 + 4 + 4 );
-    if ( error ) goto ...
-
-    str.value1 = FT_Get_Short( stream );
-    str.value2 = FT_Get_ULong( stream );
-    str.value3 = FT_Get_ULong( stream );
-
-    FT_Forget_Frame( stream );
- - -

Here, the call to FT_Access_Frame() will

- -
    -
  • -

    Ensure that there are at least 2+4+4=10 bytes left in the - stream.

    -
    • -
  • -

    `Preload' (for disk-based streams) 10 bytes from the current - stream position.

    -
    • -
  • -

    Set the frame `cursor' to the first byte in the frame.

    -
    • -
- -

Each FT_Get_Short() or FT_Get_ULong() call - will read a big-endian integer from the stream (2 bytes for - FT_Get_Short(), 4 bytes for FT_Get_ULong) - and advance the frame cursor accordingly.

- -

FT_Forget_Frame() `releases' the frame from memory.

- -

There are several advantages to using frames:

- -
    -
  • -

    Single-check when loading tables.

    -
    • -
  • -

    Making code clearer by providing simple parsing functions - while keeping code safe from file over-runs and invalid - offsets.

    -
    • -
- -
- -

- II. Accessing and reading a frame with macros -

- -

By convention in the FreeType source code, macros are able to use two - implicit variables named error and stream. This is - useful because these two variables are extremely often used in the - library, and doing this only reduces our typing requirements and make the - source code much clearer.

- -

Note that error must be a local variable of type - FT_Error, while stream must be a local variable or - argument of type FT_Stream.

- -

The macro used to access a frame is ACCESS_Frame(_size_), it will - translate to

- - - 
-    ( error = FT_Access_Frame( stream, _size_ ) )
-        != FT_Err_Ok
- - -

Similarly, the macro FORGET_Frame() translates to

- - - 
-    FT_Forget_Frame( stream )
- - -

Extracting integers can be performed with the GET_xxx() - macros, like

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Macro name - - Translation - - Description -
- GET_Byte() - - FT_Get_Byte(stream) - -

Reads an 8-bit unsigned byte.

-
- GET_Char() - - (FT_Char)
- FT_Get_Byte(stream) - 		-

Reads an 8-bit signed byte.

-
- GET_Short() - - FT_Get_Short(stream) - - Reads a 16-bit signed big-endian integer. -
- GET_UShort() - - (FT_UShort)
- FT_Get_Short(stream) - 		- Reads a 16-bit unsigned big-endian integer. -
- GET_Offset() - - FT_Get_Offset(stream) - - Reads a 24-bit signed big-endian integer. -
- GET_UOffset() - - (FT_UOffset)
- FT_Get_Offset(stream) - 		- Reads a 24-bit unsigned big-endian integer. -
- GET_Long() - - FT_Get_Long(stream) - - Reads a 32-bit signed big-endian integer. -
- GET_ULong() - - (FT_ULong)
- FT_Get_Long(stream) - 		- Reads a 32-bit unsigned big-endian integer. -
- -

(Note that an Offset is an integer stored with 3 bytes on - the file.)

- -

All this means that the following code

- - - 
-    error = FT_Access_Frame( stream, 2 + 4 + 4 );
-    if ( error ) goto ...
-
-    str.value1 = FT_Get_Short( stream );
-    str.value2 = FT_Get_ULong( stream );
-    str.value3 = FT_Get_ULong( stream );
-
-    FT_Forget_Frame( stream );
- - -

can be simplified with macros:

- - - 
-    if ( ACCESS_Frame( 2 +4 + 4 ) ) goto ...
-
-    str.value1 = GET_Short();
-    str.value2 = GET_ULong();
-    str.value3 = GET_ULong();
-
-    FORGET_Frame();
- - -

Which is clearer. Notice that error and stream - must be defined locally though for this code to work!

- -
- -

- III. Alternatives -

- -

It is sometimes useful to read small integers from a font file without - using a frame. Some functions have been introduced in FreeType 2 to - do just that, and they are of the form FT_Read_xxxx.

- -

For example, FT_Read_Short(stream, - &error) reads and returns a 2-byte big-endian integer from a - stream, and places an error code in the error - variable.

- -

Thus, reading a single big-endian integer is shorter than using a frame - for it.

- -

Note that there are also macros READ_xxx() which translate to

- - - 
-    FT_Read_xxx( stream, &error ), error != FT_Err_Ok
- - -

and can be used as in

- - - 
-    if ( READ_UShort( variable1 ) ||
-         READ_ULong ( variable2 ) )
-      goto Fail;
- - -

if error and stream are already defined - locally.

- -
-
- - - diff --git a/docs/design/library-compilation.png b/docs/design/library-compilation.png deleted file mode 100644 index 7aedcb196685b1d904f06001f068e51cda39bcfb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1789 zcmV#V>I=(+<#;?%JT zM#13L7>s^$0~c1vqr2f2=NN1n6U#hqw`GJzOYe1Cve)L?dtR^CuG{WPN9-Rv0r>eeL%Ny+(=y9g@HsD{s9Z7+%#21s46(^BAi1 z!!fIZxl%Fb;LqdHlF{r+?6`h|i(O{3E97wqT%7Y8C|*$`#%j_qme?T(@G{35eaHTa z?Y}lP8IR)_(P)#Yi6uE#$?k3S4WiYFsZ3?6yICEulBixXWg}7JWXevW!bB=U=T61& z|5m*g&BHoh@!F*xyd#xFpkj7uQUxA;B{CA9xs=vXI4-|pa-fPn{NU`ygJqL>mMOJT z(@;|I94K{N^;QC}L#@;_R6M`}uZx2lfwx_)uCx?V)OencI-pi+I_fOqAmgJv`mv-S z0042QvIjZTN=@@SItvP^rpV-QcuK9*bjA^NCf-B_qphg8k&4tMmPC_FY(|sa+gNAw z$5cy5g|$X_kwQdkcT+6|rG0O!%doVfwWHjLN?NdV)l)WEC7x6x*_4!s1=A6=Rb0Z5 z*Hcj<6`_^pq2uvG5A=<$tt;B_^$iVWQ=0W}xazON^Ik`=XGcgwEmN9}(A6kFAF2&X zLU5sy^F*G~Y=L4+Lha0N6au=jW+9ptpc~cVp2e}|&I?iXvYK@SzZbO5%dRx@_oDoY zU3;U;3acwB=*22^z2JfhY@QN{6#j4Oj=np{@`RaJ%}jo~D7Cm{2vuU$Z8ubm8c{Px zds83LRBDbkQi)s`{=)X{C()r!bM1Z$@%4^ISoKt^n_P4M?(%$ zKGsj|6AOYfwmLCtC^!GT31C^z5E<+eQa{DX!DVR0-YQkSFS%TW*==uF(gWAw2NkrHZ!J~ zqwgve%~VKFrE+xUHi&M$n%u$LY|~TA=9K8*HC4KfR*u;aCWti^A~`Qq$>=G2T7}MD zs)ss?=&Fk5{4#U2nOAQ=1@Zh(WK$BI`f(>~EIPFao~L3d#U}Sobd;S)Srg63ORc{> zWNmFcTI1{+Y#&*y?nyM!dlUfFZub!70N0b*b$(t|1|P{qFW8UVJoOGE2+RV7)mRY$ z1ONVIvU*`a5a`89IWO$MF8_Y);;C(-W-KN9qB_b2DaysyIKVoAU#yfTOn9KR0a}|^ zwjM41_}+>a7pZuvi6O1`w9078^)ZRsWH(mX=GW3!#(4r0EAKC7>AN?|+F?J*YVd${nUhT{IutIB$vpUmj>IQZ$-SEEmkuP9l+qxyoL zx-savG#$Nm?dy_FJE{k8k;c53sebUBEZwm0n_WW#wqKsFEI${MmKU^bD*U^3==CjoX8xp;>O|ej zZr07#b_wvz@6Y_vExJd+`#iOU|7mULWau!HRKN#R`<_N?4ga`sckd2^> z0(egGhx;g&3HT(0T%jxFm>Lrq+Nx&m@`!$B${0?aaYT6GM*qz# f^I2=ET&jNoGG#ph9gzH?00000NkvXXu0mjft$S|( diff --git a/docs/design/logo1.png b/docs/design/logo1.png deleted file mode 100644 index d78d05d2cbbdf120bfde874a36b5079dd3bee22d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 870 zcmV-s1DX7ZP)v#?Y?ObCa_U1()zp|k%ZeTrXxZJ= z-_z#KkJ%F_ODW<9>z~!OzgXagBzzJ=>99EMOt6*(`9ixQs{CW7fa+LgeXQT-AjGLp z6J)x@?2XEC0Sc8-Dj{q$_E$4XjapQ(JOZj<0iu*cYIjU3U)0nq6l9|j&8~b6lP5&S z?dNE_NjaryBLfX&pvgQR=p;`?%5UGhnW!^UvR;U6t-wbphuO3y#Qq}yj zLTP)tcCkY$8QSb2`Ybr#2*(%2^z=xSm888x(Q?AZs(Z>d5uz!wnBgWE=wi#oI)2ezw7EhnJFGV@V z-nB39p`79>eIKR!eoP^xN|vxfnDWbCG-Z<5>xd6P_Q(Ow*iZ<5(P!uM11_hr^) zweh~(Ny*=rQ1n6Gmoq*j3-8Nod0&zo!A7nirgBue$BeaHLB%8$pqMM@i#|xM;5hjE z2(!PCbV6)vN?8Dz{g(1R=o%zLnxdBXshB|FI#rV;A1v>4aTkYT-sj34?#xuG2NG#_ wCgon7!)saRM%gGEWut7Ajj~ZT%HK`-19d=`aSN)m%K!iX07*qoM6N<$f(Qkib^rhX diff --git a/docs/design/objects_diagram.png b/docs/design/objects_diagram.png deleted file mode 100644 index 893bf694898610050eb381592552901ab80643d5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3907 zcmeHKX;2f{7DiA|45A`RSQG(60=UpI$|`FjXas@*Mnq7PumlLoo{>dGK_%=7(#oP_ zh$bM5Aj&4-0EQ4z*_TlSG!R6CEGqkp&MV8Q_kO&pshVG}>#MHs_BnmdJ-5&Ks`{#f z-9b57WmyRc2{~IEYexwQNkBqkh2Cl@@g3X_#!E;@NjPBfXtBfpufKl+{{Bw>{+z!b z=YNTin(CCA`VZw2@29-{pUc(X|Ig(Tm$tmTY$EyOsf5JZC0lC?e0bl7thMO{cQ>M+ zU&mX^cRG511qik5h|#SibdO+8ZentHjfp?uT+^r~L; z=Oc!gxNgT}vyy4ygUn|l)|$xF_gKSD29tB&>DpCyemSy}YBq1{^)4%3XLKDg)TLtd8( zySAURVP=k=xH)8M!UKiu+U938;CopArzvD&{=FWwDT>k5iH(pgX$cl zb$G zi08&gG1&9gYu2!3sG0j|qaipZ$(MZY`8JT;Q~b5IlRbasIh&T+MafXm9J zZ{YbI@H2v#;ONw>A`*lLX**{6n%oZVR<#pYH+Q>w3W5PIZUn}C*ywnmNuO0w0ziN> zVal?ahv*hy>=cx40j1YFNRxiX9=f3uCSy1OT4(rV)n6=PuRY@Ty6CuA`&$s+5BvrM zxj0kt!10!|q9(A`o`&fap@-i8Rk!QvhHc)WTxGyE={P$btyct>YKSt8< zGg6$q8gTiuHrgqdzh;yQnEI#16uFGGz=JyHkcg>Q%l`XRxJ5L3>^LR(Ov=;wuuVcb zD2rg8c;gWe9FCMpaDBA}598rX8(uJB& zZ=)2QF*`&Bo+Kg;_UV;$Ei*d$9!8pkH?r&C(LScU%m+gJstOHwFdPOR)cxT12_?d? z@EYSbs&PiQZ{Is8y*cuH_Kj1Rov0YmY09>o{wkn|dHiG6Eip;EjoRSl0PD4>rjni* zGgdxz=)B8Mu*)k3T4y{t?8AsA&hXeR2bwr6`RA=Z15PhqAwcJnw-_ZIJX zNa|W0rXtd#%-e9zZT`!A?m#*@p>D)9r_Ck&0dJH2DYs}}hbDWdTt5Hf^E;x(Mc2O1 z#uJyzCn*`dmm)vRt&^+g&t4gAzr3p^?+6P!*W0?s^DVC7_vW|cY_-w+jjdJD)TXWd z44|d^sobsH2tggIj5oS?V91!_t?29#S1W4DR74OqBB$>0LsOqXxcr#`yQYjA$B#PA zV!__lee{w&$P7T3lfIvWH8gO=W8ew~=42=EN{QvF>z11dO-I2sB%{PSX;LDcDmMw? z8PN4Dl1615V-12P&eE^4`2%1@A;SQMf@sAM7VI!w+ zCQycFj>N_Lk3KLPZjl*o)t>@+9(Os$?N;9>g8Jfp9k%qpXw;96|C5}AE3hD;TJqmL zmAEI>V=h3Xfx4K>$&$d2rI`H8)uq0h(uO_J5*t5YD>Mn1id#T89~26e)uVoBD)e`Y9e!bSYJc~ zGS}A-`yTI1YSWrk8-KWT)tRd|kd*^j4jI$p?v10((_j4dSg7YB3A&~ja;9+GJPI`pmU07Ivi7>y-Tv}EobAOyZ*m-Q!oS@aS` zPai0En`d5b}@0RqygvH#x~LRu)!LlH_Ir^eRvTYLEDg~Dg!GR!C!|u83yj%akpjj06`f7 ztx5uN=u1e&S`}TEIn44%de$T~!W~nAa-6d?XI<;RR;nEMdCc9XWwO$j=verACA8>? zMnSAwhz-mTkS1Q!L^cMG`uJ?+V%MY~7`aJhUoDRHQy=Pf##+GY3)XR`X|zxx{ z9M)mFoyjS@Gktv(=xn5wEL;JV3&JJ)JQ_1+MG-SwH1bYAz{^70JOYCB;_=O~C-87a zZQxoiHV-caZVdzra21wk%~_OsbJkhnUe_HV@ie1uIifjBib$JP!`wg&lqjpW?*+`d zmS#yK9=Q3fuJ&VmEfCb*S`LiM7cI=^HL1ADGS;=_Z=76r`~ zzWb(M;!@yg1ezr9-fVXK%45|FsOX~3xV@s6><{c?Z-GS(!WSIIqsrfCUBlemg?(=j zRy(^&7`j5yQF(?am7_s9kF|M<-BDTuMKF}qn2c13<*RW)&JUYO(-r26N7(7xRwe~GQ%jkQ2BzXn&8-(_U zL#j%5bG0-v;!)gAX-RB`a81sdh+1B#4@XuU(ng4)k&EI`y>5SqW{!&Ob-pkQ!R%Kh;tdN}_=vL0sVUhCnbGrDW8Amp z!BaVkf$B&Yu*JALxrLU!BrS3)B^*|7Z&x=CnN#rx*K%nW`NfBs=CM5zfOu2iAXbvD z9b%<85BU?)KMBgu{IBBjLuh`9=AP^UHykg%GbsJLxwI6tKzd$Y+rGEjwqtzc+wYex M+RnPr^5n&T0i)LU_y7O^ diff --git a/docs/design/objects_diagram2.png b/docs/design/objects_diagram2.png deleted file mode 100644 index 0ef5fa3f240e98bb22d2c575310aadadd41b0e5a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3219 zcmeHJdo+~m8XuR)wOq=`rQF7)V!j!XkjkymxDF|)CNqueG%B}T&Lmq*MkB%usjyQn zN11V{5W-~ILot}#;v^#>)iw=E_Ndfpowd%|Ywff4U*~()dcJqP@ALkC&*k^6^^x3M z9Oa}pNP|EiImBK&4-iNc0D(jtSBnY#TD>6!5J(Km9)3z3}*wzmD@~ z5Yp4V($oJYE@3{^)qfw?pDF);7_+prBubv#2m(pDAnbN~M)gk*$>kK(Den4Lf9P<% zYzphc+=-fkP1n!5D@FxJ^Cl*G4_r~-Glx*bUrlCYDhUkE)bi*l;{>0(UixK`W1a_G zP*V}Dnqw_9-YwlTqxQuW&`Y;yl*N4(k|z4=|DoLBm3g|{ub1Bx`RrDJ|LGK!kGzNS z+X>2rRQr$JFI0$S)K>!f#+d$2ml~`IgA`{TglV2LRZN*Qgy@AlU(j8ME2J9e!mgTL z4wpuqFymC6ZI|zBsoJQl@Z^oNomz@(eD~!Ltd3frIxP2E9G$cVKj=?KEG;S7SCFR0 zjx69QaW%7{lkWw3@IJeS%~4>pbq9TMF&yR0RGoy7i|Nk&*13KApg|>1L(27+;!{Jg zD72Y7J9Bm)%H2f+;Q(8u%cyw7(4yh%OAU&1bWu3iN%$0p6_$P8?{oXf7~hC@(*x}+ z-#4B$2PH?=&dDYv7#Pvo&LBqeupWU}T^&`{UI$qEC3e`SN@sU0~(KMY-)Qy0AKox1im&DM1$2 zwh4t?Bd&@~vw+h+W@w@iTm*!Eb`|w?LrnEIWzeg$9$9i7B!rN=e>mR!m^jwKTdC`K zdxiJ4`Hwk}yih*Y<)Re|7j*o)ynoMQF+q`2q!{`R885}(-O91j9W7Zz+a85qCH=dBo1pl zc-#BjG~6yVvm*>%%eDS?Dj96NOrul8FeAf2%#;Ab6Q zDyA*6lD)0N;$@*T@lwE>XgIT6To&3068q*__3t%LC%VPd#^SCj5FEub#;U#@q99Zd z?uGfHMdW?M13PEI!zxXKIMc^|$iaC}JaRBQuwiHUnd0Bal{Q#EeC0&?7!xeXffo(P zyfAC-ddw7TrWD3WA?=9X7bX*)a-$1#lkC2&$ zx@cVEr`!0Wx3!24(DtZp??`1HKJV#D)qu@!k+rt*q->_CVP3HJ>z!tmfHgS0jOBAm z4dw1_BwruiI3>@kk?F$jEDw3re_0X|cU_I1&sJ=DIg|7&-#!R)R;0)b+Ih|4`VwQY z+ESuWAjwfCDzVX*!w5l%&en5LVpDg{Y2RmQE^s!)_D~h5#a1`vs~CsY5B(x>D1$PY zEI6DR7;_;EzQwm8kQ+Ziu&)eutRH&xIkNWyFXfpC(z15AY$$Vqu|c*PC)Mc=;V^D= z$9hJ0n$>fi!|qB*fYE0yAXLsOXrrF2Iy7Lg+3}#-IFk5~>&jaLRvY2nnjR4L{tr_ii9?i}t_bHCP z^plPVz(~Vz1)}EdchkpinG)E?ch-EgnKrOx#+Ih4a=V5F6%+tY&}IzQGm5NX-T9L!6O2N-f|F|)CGhv7dFUNaQ9QMSR(1Nz%=i&>6*GdS@Lfk(;B4ksoI}CICsvc_o*GiINKyS5p1AtpD4R+F;)C#J&~Gw2IRa!j>QJ zvog^X4sBd&x%5_ktm^30LQ9Gpu#y&a#?fgJs3ad_m(B?Ue1DgWW@<-6eiGTjO^stZ zVUjazk^tCD7>zVQ0G@L0VlUbDWN?Xkri-bg7q*E><**Y}whEc{^+;go)2$mxC8>s@ zP8H0{cN|sxk^FXFKC|wwy2l0Ja1Obzof^EZ?!G#`2A~AOa0HB#jgfT`3%n?_FOwagPe1Z&u^2tO(bXd5K~|^fPx@#z+|ZfzxZJwavWNu;oXtv zWI12eL!GS#fb3oSF}SqK!?tQVyYyiYl$K0tVAclsQU8j!qkd0I#;P_yXzRb%75OC7 zqeMa)a{*c;)Q>M^MMS(xW>gTv&EUoclwB0;$~SfCF`*7Z!|}7O;oqw)*LKlqWo)Z| z5~0I)MN+#`E#{@u$Oj2ziDbaF`cofRep(jO+k}=8ihxSdyhUvS-yB+jf%261-XH5G zW?Mm|Fh_Le?-}1bu}cY)RSjg1bxS>5Y3VVx`_`WsS0)c;mX-At=Zh;;q={i%o-x_C zE!x4%EpVKl*KsD4$HJ}IKPZov6{=YEKRz6?!dE*7{IES+%p8*a0Yl2#$s9E;unzqZ Y@sjQ0&Yna3FF%e5dl$R%J?L|P0A~Sil>h($ diff --git a/docs/design/platform-detection.png b/docs/design/platform-detection.png deleted file mode 100644 index a30b7e2b56304516af22ff760b282e3b79af2a35..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1695 zcmV;Q24MM#P)P3DQgw zGbV#SUa!b;c4cIG#XYMo&4m=!QOji4P2AW3JvAF;& zGJlt72vGNLPVy8n%FIyV^{fUCnI(zw07X%q^yK(3Ls57UgHiJ)WTMV!nZERM9Yf6m z^JmI?wgvY$H{+HOt*jIt8Wxj<$iP-KW+%Cwy>^nnjtsYCY#vjrt0nT- z^Z`qzg{rZQan`J6?N46Df*FBtY_$whweuvx*c7ra>a}EOA8!(k3HGwIliZHzmxnQ? z|4b=ju-8_za;@7o4^_-yxo+D$RB?UY*4k+E;3~^%j9&Y8dn}RHZJUIu-fN$FO6PUk zV&NTHwVKvzUl`@-yl%Ug1&m%BG9|CuE@qO^Ys)mhl-F$+F*Q`RUK=tcuiGwSYN%?x zwmjS1mDg<-F=Mi{CYlCe^ErK9ruEv1@~q@~+vE%-8~|F>*vw`&vsnqY*aIKxKomYk zjeA#SEFFhAH6jhbA6W$`W!Q+ptah4y(D+gJP;1rnRo9iqma1ys5!{TWst4S$!TReb zrd)f5t{;sxnzQuGcWi8={<=Hn+T*y~5j*5E-|5VdJ2s@V%y0>IL))p!W`8&pJ7m7o z#Vh-hk?QSLk*jr=oh^>He6_gMEX2_!3z79~wuO}0l5O0CweKtPb?|hzl+WZ};KPXa zM#CU3=u!@YWtl73X((3>UcY4-JbB7OAsg=Mn_YV9i|=#bd!x=4HhIkX#b=#|zmM$v z5^r+nm}kOEdPL7yoCy8yB~O!o9V9=w`8Da`pG}7zkvX<-gn#4~-B$!6^vqi$B;)=X zj+Du3JjaE1Mskc(crq=16M}4>mjrUzFR9D}S%_lRSZLw6XZ3@z=ue@@N%AX_JV<)T z4$|XQS#GC}k2}uxCDU#3eM9(O*2yNK$DC7r@_}!oJEljfSnFB9^^c_7WT7!dJq%JC zu|gP=I~nVkdZRq8CJtm7{eUxL80_(6y^ySzlXFbUE)%^gmto(iGyPeXEvu{1WsC=h zucEXU%NmpNs|jjD8FUP7+lD_r9I0yAGssAZ>Bhh7-V3;LEa-?jLw^82@8x;mB#BAl zMmsA~_r%ZfK?2V)Kj|f%*OV2W=lGON1||a`J|#|G5Snn}-r7$68E;L9f;~IW(W3Mx zrZRvLTjs(zaW{`iUP)yfMNuip0)b8{B@mrLNc%R_+D=cBwUnZ&AHm^qcL3|8SmAc| z+fW8u3Oe6+PE>)~ruz?$gGc8EZU#GN879{6i`HWeuJyAZ15)iyrGm*_&m?I)_wBN< pHDfavNE$I0w$IKsv)TV;{{awMvD6acc9;MF002ovPDHLkV1kLWKLP*% diff --git a/docs/design/system-interface.html b/docs/design/system-interface.html deleted file mode 100644 index c505bbe59..000000000 --- a/docs/design/system-interface.html +++ /dev/null @@ -1,258 +0,0 @@ - - - - - - - FreeType 2 Internals - - - - - -
-

-FreeType 2.0 System Interface

- -
-

-© 2000 David Turner (david@freetype.org)
-© 2000 The FreeType Development Team (devel@freetype.org)

- -


-

-
  -

Introduction:

-
    - This document explains how the FreeType 2 library performs the low-level and - system-specific operations of memory management and i/o access. It is targetted - to FreeType hackers, porters and "advanced" developers who want special - features like providing their own memory manager or streams. -

    - Note that the only system-specific part of the library is a file - named "ftsystem.c", normally located in the directory - "freetype2/config/<system>" where <system> designates - your platform (e.g. "config/ansi/ftsystem.c" or - "config/unix/ftsystem.c"). -

    -

- -

-

-

- -

I. Memory Management

-
    - Memory allocation and releases are performed through a FT_Memory object in - FreeType. A FT_Memory is nothing more than a table of functions plus - an arbitrary user data field. It is defined in the file - "freetype2/include/ftsystem.h" and has the following structure: -

    -

      - typedef struct
      - { -
        - -
        void* user // a user-defined pointer. This is zero by default -
        void* (*alloc)( FT_System, int) // a function used to allocate a new block -
        void* (*realloc)( FT_System, int, int, void* ) // a function used to reallocate a given block -
        void (*free)( FT_System, void*) // a function used to release a given block -
        -
      - } FT_MemoryRec, *FT_Memory;
      -
    -

    - You'll notice that:

    -

      -
    • The FT_Memory type is really a pointer to a FT_MemoryRec. - This is a normal convention for the FreeType code. -
    • The realloc takes two integer arguments. The first one is the - current block size, the second one its new size. -
    -

    - - All current implementations of "ftsystem.c" provide a very simple - implementation of the FT_Memory interface by calling directly the - standard C alloc, realloc and free. -

    - The FreeType source code never invokes directly the function pointers. Rather, - it calls FT_Alloc, FT_Realloc and FT_Free functions - which are defined in "freetype2/src/base/ftobjs.c". These will not be - discussed here. -

    - If you want to use your own memory allocator rather than the one provided - by your build of FreeType, follow these simple steps:

    -

      -
    1. Create your own FT_Memory object, with pointers that map to - your own memory management routines (beware function signatures though). -

      -

    2. Call FT_Build_Library(memory,&library). This will create a new - FT_Library object that uses your own FT_Memory exclusively. - Note however that this library has no font drivers loaded in !! -

      -

    3. Load the default font drivers into the new library, either by - calling FT_Default_Drivers(library), or by adding them manually - through repeated calls to FT_Add_Driver(library,&driver_interface) -

      -

    - This will replace the FT_Init_FreeType(&library) call that an application - must do to initialise one library instance. -

    - Notice that you don't need to recompile FreeType 2 to use your own memory - manager !!. -

    -

- -

-

-

- -

II. Streams

-
    -

    1. Basic Stream Structure

    -

    - A stream models the array of bytes found in a font file. FreeType 2 separates - streams into two families :

    -

      -
    • memory-based streams:
      - when the stream's content is entirely found in memory. This is the - case for ROM font files, or memory-mapped files. -

      -

    • disk-based streams:
      - when the stream isn't directly accessible in memory. This is the - case for local or remote files. -

      -

    -

    - Note that a stream's nature only determines how FreeType accesses its content, not - the way it is effectively stored. For example, in the case of a compressed font file, - one implementation may choose to uncompress the font in memory, then provide a memory - based stream to access it. Another one might chose a disk based stream to perform - on-the-fly decompression of the font data. Similarly, the font file can be stored - on a local disk, or obtained from a network. This will be completely transparent to - FreeType. -

    - The stream structure is: -

    -

      - typedef struct
      - {
      -
        -
        char* base for memory-based streams, the address - of its first byte. - -
        ulong size the stream's size in bytes. - -
        ulong pos the current stream position in the file - -
        descriptor a union field used to hold either an - integer file descriptor or pointer. - This field is not used by FreeType - itself, but is left to implementations - of "ftsystem" -
        pathname a union field that can hold either an - integer or pointer. It is not used by - FreeType itself, but is left to - implementations. These can put the - file pathname's during debugging for - example. - -
        read a pointer to a function used to seek the - stream and/or read a run of bytes from it. - -
        close a pointer to a function called when the - stream is closed. - -
        memory a FT_Memory object, which is used - to allocate frames for disk-based streams. - This field is set and used by FreeType. - -
        cursor a pointer in memory used when accessing - frames. This is set and used by FreeType. - -
        limit a pointer in memory used when accessing - frames. This is set and used by FreeType. -
      - } FT_StreamRec, *FT_Stream -
    -

    - - The following important things must be noticed here:

    -

      -
    • The FT_Stream type is really a pointer to a FT_StreamRec. - This is a normal convention for the FreeType source. -

      - -

    • When the read field is non NULL, the stream is considered to be - disk-based. Otherwise, the stream is memory-based, and the base - field must be set by "ftsystem.c" when the stream is - created. -

      - -

    • The base field must be set to 0 when a disk-based stream is created. - However, this field will later be set and used by the FreeType library when - accessing frames of bytes within the font file (of course, this doesn't - happen with memory-based streams). -
    - -

    2. Stream lifecyles

    -

    - Each FT_Face needs its own stream to access font data. The most common - way to create a new FT_Stream object is to call the function - FT_New_Face. This function takes a file pathname argument that - is used to create a new stream object. -

    - This is possible because each implementation of "ftsystem.c" provides - a function called FT_New_Stream which takes a file pathname and a - FT_Stream pointer as an argument. The function simply opens the file - and initialises the stream structure accordingly. It is called by FT_New_Face - to create the face's stream object. -

    - A stream is only closed when the face is destroyed through FT_Done_Face. - Its close field function will then be called. Note that the function should - never destroy the FT_Stream. -

    - - -

    3. Using your own streams

    -

    - There are cases where it is interesting to provide your own stream to create - a new face object, rather than rely on the default implementation. For example, - a filepathname, which is a C string, might not be useful on a system where files - are named with a UTF-16 string or via an i-node number of memory address (for ROM files). -

    - For this purpose, the FT_Open_Face is defined. It simply takes a - FT_Stream pointer as its second argument, instead of a file pathname (the - stream must be allocated and initialised by you, so be careful). -

    - Actually, the only thing that FT_New_Face does is create a new stream - through FT_New_Stream, then call FT_Open_Face to create the - face with it. -

    - Note also that you can use the function FT_New_Memory_Face to create - a new font face for a memory-based font file, whose address and size can be passed - as arguments. The function automatically creates the corresponding memory-based - stream and use it to create the face. -

    - -

- - -

-

-

- -

III. Thread synchronisation

-
    - The FreeType library uses no static data. It can be used concurrently by two - thread as long as each one uses its own FT_Library instance. Otherwise, - one can very simply synchronize access to a single library instance by using a - mutex to protect each call to one of FreeType's API functions. -

    -

- - diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html deleted file mode 100644 index fb8a5b3ae..000000000 --- a/docs/tutorial/index.html +++ /dev/null @@ -1,871 +0,0 @@ - - - - - - FreeType 2 Tutorial - - - - -

- FreeType 2.0 Tutorial -

- -

- © 2000 David Turner - (david@freetype.org)
- © 2000 The FreeType Development Team - (www.freetype.org) -

- -
- - -
- -
- -

- Introduction -

- -

This short tutorial will teach you how to use the FreeType 2 - library in your own applications.

- -
- -

- 1. Header files -

- -

To include the main FreeType header file, simply say

- - - 
-    #include <freetype/freetype.h>
- - -

in your application code. Note that other files are available in the - FreeType include directory, most of them being included by - "freetype.h". They will be described later in this - tutorial.

- -
- -

- 2. Initialize the library -

- -

Simply create a variable of type FT_Library named, for - example, library, and call the function - FT_Init_FreeType() as in

- - - 
-    #include <freetype/freetype.h>
-
-    FT_Library  library;
-
-    ...
-
-    {
-      ...
-      error = FT_Init_FreeType( &library );
-      if ( error )
-      {
-        ... an error occurred during library initialization ...
-      }
-    }
- - -

This function is in charge of the following:

- -
    -
  • -

    Creating a new instance of the FreeType 2 library, and set - the handle library to it.

    -
    • -
  • -

    Load each modules that FreeType knows about in the library. - This means that by default, your new library object is able - to handle TrueType, Type 1, CID-keyed & OpenType/CFF fonts - gracefully.

    -
    • -
- -

As you can see, the function returns an error code, like most others - in the FreeType API. An error code of 0 always means that - the operation was successful; otherwise, the value describes the error, - and library is set to NULL.

- -
- -

- 3. Load a font face -

- -

- a. From a font file -

- -

Create a new face object by calling FT_New_Face. - A face describes a given typeface and style. For example, - "Times New Roman Regular" and "Times New Roman Italic" correspond to - two different faces.

- - - 
-    FT_Library   library;   /* handle to library     */
-    FT_Face      face;      /* handle to face object */
-
-    error = FT_Init_FreeType( &library );
-    if ( error ) { ... }
-
-    error = FT_New_Face( library,
-                         "/usr/share/fonts/truetype/arial.ttf",
-                         0,
-                         &face );
-    if ( error == FT_Err_Unknown_File_Format )
-    {
-      ... the font file could be opened and read, but it appears
-      ... that its font format is unsupported
-    }
-    else if ( error )
-    {
-      ... another error code means that the font file could not
-      ... be opened or read, or simply that it is broken...
-    }
- - -

As you can certainly imagine, FT_New_Face opens a font - file, then tries to extract one face from it. Its parameters are

- - - - - - - - - - - - - - - - - - -
- library - -

handle to the FreeType library instance where the face object - is created

-
- filepathname - -

the font file pathname (standard C string).

-
- face_index - -

Certain font formats allow several font faces to be embedded - in a single file.

- -

This index tells which face you want to load. An error will - be returned if its value is too large.

- -

Index 0 always work though.

-
- face - -

A pointer to the handle that will be set to describe - the new face object.

- -

It is set to NULL in case of error.

-
- -

To know how many faces a given font file contains, simply load its - first face (use face_index=0), then see the value of - face->num_faces which indicates how many faces are embedded - in the font file.

- -

- b. From memory -

- -

In the case where you have already loaded the font file in memory, - you can similarly create a new face object for it by calling - FT_New_Memory_Face as in

- - - 
-    FT_Library   library;   /* handle to library     */
-    FT_Face      face;      /* handle to face object */
-
-    error = FT_Init_FreeType( &library );
-    if ( error ) { ... }
-
-    error = FT_New_Memory_Face( library,
-                                buffer,    /* first byte in memory */
-                                size,      /* size in bytes        */
-                                0,         /* face_index           */
-                                &face );
-    if ( error ) { ... }
- - -

As you can see, FT_New_Memory_Face() simply takes a - pointer to the font file buffer and its size in bytes instead of a - file pathname. Other than that, it has exactly the same semantics as - FT_New_Face().

- -

- c. From other sources (compressed files, network, etc.) -

- -

There are cases where using a file pathname or preloading the file - in memory is simply not enough. With FreeType 2, it is possible - to provide your own implementation of i/o routines.

- -

This is done through the FT_Open_Face() function, which - can be used to open a new font face with a custom input stream, select - a specific driver for opening, or even pass extra parameters to the - font driver when creating the object. We advise you to refer to the - FreeType 2 reference manual in order to learn how to use it.

- -

Note that providing a custom stream might also be used to access a - TrueType font embedded in a Postscript Type 42 wrapper.

- -
- -

- 4. Accessing face content -

- -

A face object models all information that globally describes - the face. Usually, this data can be accessed directly by dereferencing - a handle, like

- - - - - - - - - - - - - - - - - - - - - - -
- face->num_glyphs - -

Gives the number of glyphs available in the font face. - A glyph is simply a character image. It doesn't necessarily - correspond to a character code though.

-
- face->flags - -

A 32-bit integer containing bit flags used to describe some - face properties. For example, the flag - FT_FACE_FLAG_SCALABLE is used to indicate that the face's - font format is scalable and that glyph images can be rendered for - all character pixel sizes. For more information on face flags, - please read the FreeType 2 API Reference.

-
- face->units_per_EM - -

This field is only valid for scalable formats (it is set to 0 - otherwise). It indicates the number of font units covered by the - EM.

-
- face->num_fixed_sizes - -

This field gives the number of embedded bitmap strikes - in the current face. A strike is simply a series of - glyph images for a given character pixel size. For example, a - font face could include strikes for pixel sizes 10, 12 - and 14. Note that even scalable font formats can have - embedded bitmap strikes!

-
- face->fixed_sizes - -

this is a pointer to an array of FT_Bitmap_Size - elements. Each FT_Bitmap_Size indicates the horizontal - and vertical pixel sizes for each of the strikes that are - present in the face.

-
- -

For a complete listing of all face properties and fields, please read - the FreeType 2 API Reference.

- -

- -

- 5. Setting the current pixel size -

- -

FreeType 2 uses "size objects" to model all - information related to a given character size for a given face. - For example, a size object will hold the value of certain metrics - like the ascender or text height, expressed in 1/64th of a pixel, - for a character size of 12 points.

- -

When the FT_New_Face function is called (or one of its - cousins), it automatically creates a new size object for - the returned face. This size object is directly accessible as - face->size.

- -

NOTA BENE: a single face object can deal with one or more size - objects at a time, however, this is something that few programmers - really need to do. We have thus have decided to simplify the API for - the most common use (i.e. one size per face), while keeping this - feature available through additional fuctions.

- -

When a new face object is created, its size object defaults to the - character size of 10 pixels (both horizontally and vertically) for - scalable formats. For fixed-sizes formats, the size is more or less - undefined, which is why you must set it before trying to load a - glyph.

- -

To do that, simply call FT_Set_Char_Size(). Here is an - example where the character size is set to 16pt for a 300x300 dpi - device:

- - - 
-    error = FT_Set_Char_Size(
-              face,    /* handle to face object           */
-              0,       /* char_width in 1/64th of points  */
-              16*64,   /* char_height in 1/64th of points */
-              300,     /* horizontal device resolution    */
-              300 );   /* vertical device resolution      */
- - -

You will notice that:

- -
    -
  • -

    The character width and heights are specified in 1/64th of - points. A point is a physical distance, equaling 1/72th - of an inch, it's not a pixel..

    -

    • -
  • -

    The horizontal and vertical device resolutions are expressed in - dots-per-inch, or dpi. You can use 72 or - 96 dpi for display devices like the screen. The resolution - is used to compute the character pixel size from the character - point size.

    -
    • -
  • -

    A value of 0 for the character width means "same as - character height", a value of 0 for the character height - means "same as character width". Otherwise, it is possible - to specify different char widths and heights.

    -
    • -
  • -

    Using a value of 0 for the horizontal or vertical resolution means - 72 dpi, which is the default.

    -
    • -
  • -

    The first argument is a handle to a face object, not a size - object. That's normal, and must be seen as a convenience.

    -
    • -
- -

This function computes the character pixel size that corresponds to - the character width and height and device resolutions. However, if you - want to specify the pixel sizes yourself, you can simply call - FT_Set_Pixel_Sizes(), as in

- - - 
-    error = FT_Set_Pixel_Sizes(
-              face,   /* handle to face object            */
-              0,      /* pixel_width                      */
-              16 );   /* pixel_height                     */
- - -

This example will set the character pixel sizes to 16x16 pixels. - As previously, a value of 0 for one of the dimensions means - "same as the other".

- -

Note that both functions return an error code. Usually, an error - occurs with a fixed-size font format (like FNT or PCF) when trying to - set the pixel size to a value that is not listed in the - face->fixed_sizes array.

- -
- -

- 6. Loading a glyph image -

- -

- a. Converting a character code into a glyph index -

- -

Usually, an application wants to load a glyph image based on its - character code, which is a unique value that defines the - character for a given encoding. For example, the character - code 65 represents the `A' in ASCII encoding.

- -

A face object contains one or more tables, called - charmaps, that are used to convert character codes to glyph - indices. For example, most TrueType fonts contain two charmaps. One - is used to convert Unicode character codes to glyph indices, the other - is used to convert Apple Roman encoding into glyph indices. Such - fonts can then be used either on Windows (which uses Unicode) and - Macintosh (which uses Apple Roman, bwerk). Note also that a given - charmap might not map to all the glyphs present in the font.

- -

By default, when a new face object is created, it lists all the - charmaps contained in the font face and selects the one that supports - Unicode character codes if it finds one. Otherwise, it tries to find - support for Latin-1, then ASCII.

- -

We will describe later how to look for specific charmaps in a face. - For now, we will assume that the face contains at least a Unicode - charmap that was selected during FT_New_Face(). To convert a - Unicode character code to a font glyph index, we use - FT_Get_Char_Index() as in

- - - 
-    glyph_index = FT_Get_Char_Index( face, charcode );
- - -

This will look the glyph index corresponding to the given - charcode in the charmap that is currently selected for the - face. If charmap is selected, the function simply returns the - charcode.

- -

Note that this is one of the rare FreeType functions that do not - return an error code. However, when a given character code has no - glyph image in the face, the value 0 is returned. By convention, - it always correspond to a special glyph image called the missing - glyph, which usually is represented as a box or a space.

- -

- b. Loading a glyph from the face -

- -

Once you have a glyph index, you can load the corresponding glyph - image. Note that the glyph image can be in several formats. For - example, it will be a bitmap for fixed-size formats like FNT, FON, or - PCF. It will also be a scalable vector outline for formats like - TrueType or Type 1. The glyph image can also be stored in an - alternate way that is not known at the time of writing this - documentation.

- -

The glyph image is always stored in a special object called a - glyph slot. As its name suggests, a glyph slot is simply a - container that is able to hold one glyph image at a time, be it a - bitmap, an outline, or something else. Each face object has a single - glyph slot object that can be accessed as - face->glyph.

- -

Loading a glyph image into the slot is performed by calling - FT_Load_Glyph() as in

- - - 
-    error = FT_Load_Glyph( 
-              face,          /* handle to face object */
-              glyph_index,   /* glyph index           */
-              load_flags );  /* load flags, see below */
- - -

The load_flags value is a set of bit flags used to - indicate some special operations. The default value - FT_LOAD_DEFAULT is 0.

- -

This function will try to load the corresponding glyph image - from the face. Basically, this means that:

- -
    -
  • -

    If a bitmap is found for the corresponding glyph and pixel - size, it will in the slot (embedded bitmaps are always - favored over native image formats, because we assume that - they are higher-quality versions of the same image. This - can be ignored by using the FT_LOAD_NO_BITMAP flag)

    -
    • - -
  • -

    Otherwise, a native image for the glyph will be loaded. - It will also be scaled to the current pixel size, as - well as hinted for certain formats like TrueType and - Type1.

    -
    • -
- -

The field glyph->format describe the format - used to store the glyph image in the slot. If it is not - ft_glyph_format_bitmap, one can immediately - convert it to a bitmap through FT_Render_Glyph, - as in:

- - - 
-   error = FT_Render_Glyph(
-                  face->glyph,      /* glyph slot  */
-		  render_mode );    /* render mode */
-
- - -

The parameter render_mode is a set of bit flags used - to specify how to render the glyph image. Set it to 0 to render - a monochrome bitmap, or to ft_render_mode_antialias to - generate a high-quality (256 gray levels) anti-aliased bitmap - from the glyph image.

- -

Once you have a bitmap glyph image, you can access it directly - through glyph->bitmap (a simple bitmap descriptor), - and position it through glyph->bitmap_left and - glyph->bitmap_top.

- -

Note that bitmap_left is the horizontal distance from the - current pen position to the left-most border of the glyph bitmap, - while bitmap_top is the vertical distance from the - pen position (on the baseline) to the top-most border of the - glyph bitmap. It is positive to indicate an upwards - distance.

- -

The next section will detail the content of a glyph slot and - how to access specific glyph information (including metrics).

- -

- c. Using other charmaps -

- -

As said before, when a new face object is created, it will look for - a Unicode, Latin-1, or ASCII charmap and select it. The currently - selected charmap is accessed via face->charmap. This - field is NULL when no charmap is selected, which typically happens - when you create a new FT_Face object from a font file that - doesn't contain an ASCII, Latin-1, or Unicode charmap (rare - stuff).

- -

There are two ways to select a different charmap with FreeType 2. - The easiest is when the encoding you need already has a corresponding - enumeration defined in <freetype/freetype.h>, as - ft_encoding_big5. In this case, you can simply call - FT_Select_CharMap as in:

- - 
-    error = FT_Select_CharMap(
-                    face,                 /* target face object */
-		    ft_encoding_big5 );   /* encoding..         */
-
- -

Another way is to manually parse the list of charmaps for the - face, this is accessible through the fields - num_charmaps and charmaps - (notice the 's') of the face object. As you could expect, - the first is the number of charmaps in the face, while the - second is a table of pointers to the charmaps - embedded in the face.

- -

Each charmap has a few visible fields used to describe it more - precisely. Mainly, one will look at - charmap->platform_id and - charmap->encoding_id that define a pair of - values that can be used to describe the charmap in a rather - generic way.

- -

Each value pair corresponds to a given encoding. For example, - the pair (3,1) corresponds to Unicode. Their list is - defined in the TrueType specification but you can also use the - file <freetype/ftnameid.h> which defines several - helpful constants to deal with them..

- -

To look for a specific encoding, you need to find a corresponding - value pair in the specification, then look for it in the charmaps - list. Don't forget that some encoding correspond to several - values pair (yes it's a real mess, but blame Apple and Microsoft - on such stupidity..). Here's some code to do it:

- - - 
-    FT_CharMap  found = 0;
-    FT_CharMap  charmap;
-    int         n;
-
-    for ( n = 0; n < face->num_charmaps; n++ )
-    {
-      charmap = face->charmaps[n];
-      if ( charmap->platform_id == my_platform_id &&
-           charmap->encoding_id == my_encoding_id )
-      {
-        found = charmap;
-        break;
-      }
-    }
-
-    if ( !found ) { ... }
-
-    /* now, select the charmap for the face object */
-    error = FT_Set_CharMap( face, found );
-    if ( error ) { ... }
- - -

Once a charmap has been selected, either through - FT_Select_CharMap or FT_Set_CharMap, - it is used by all subsequent calls to - FT_Get_Char_Index().

- - -

- d. Glyph Transforms: -

- -

It is possible to specify an affine transformation to be applied - to glyph images when they're loaded. Of course, this will only - work for scalable (vectorial) font formats.

- -

To do that, simply call FT_Set_Transform, as in:

- - 
-   error = FT_Set_Transform(
-                    face,           /* target face object    */
-		    &matrix,    /* pointer to 2x2 matrix */
-		    &delta );   /* pointer to 2d vector  */
-
- -

This function will set the current transform for a given face - object. Its second parameter is a pointer to a simple - FT_Matrix structure that describes a 2x2 affine matrix. - The third parameter is a pointer to a FT_Vector structure - that describe a simple 2d vector.

- -

Note that the matrix pointer can be set to NULL, (in which case - the identity transform will be used). Coefficients of the matrix - are in 16.16 fixed float units.

- -

The vector pointer can also be set to NULL (in which case a delta - of (0,0) will be used). The vector coordinates are expressed in - 1/64th of a pixel (also known as 26.6 fixed floats).

- -

NOTA BENE: The transform is applied every glyph that is loaded - through FT_Load_Glyph. Note that loading a glyph bitmap - with a non-trivial transform will produce an error..

- -
- -

- 7. Accessing glyph image data -

- -

Glyph image data is accessible through face->glyph. - See the definition of the FT_GlyphSlot type for more details. - As stated previously, each face has a single glyph slot, where - one glyph image at a time can be loaded. Each time - you call FT_Load_Glyph(), you erase the content of the glyph - slot with a new glyph image.

- -

Note however that the glyph slot object itself doesn't change, only - its content, which means that you can perfectly create a "shortcut" to - access it as in

- - - 
-    {
-      /* shortcut to glyph slot */
-      FT_GlyphSlot  glyph = face->glyph;
-
-      for ( n = 0; n < face->num_glyphs; n++ )
-      {
-        ... load glyph n ...
-        ... access glyph data as glyph->xxxx
-      }
-    }
- - -

The glyph variable will be valid until its parent - face is destroyed. Here are a few important fields of the - glyph slot:

- - - - - - - - - - - - - - - - - - -
- glyph->format - -

Indicates the type of the loaded glyph image. Can be either - ft_glyph_format_bitmap, ft_glyph_format_outline, - or other values.

-
- glyph->metrics - -

A simple structure used to hold the glyph image's metrics. - Note that most distances are expressed in 1/64th of - pixels! See the API reference or the user guide for a - description of the FT_Glyph_Metrics structure.

-
- glyph->bitmap - -

If the glyph slot contains a bitmap, a simple - FT_Bitmap that describes it. See the API reference or - user guide for a description of the FT_Bitmap - structure.

-
- glyph->outline - -

When the glyph slot contains a scalable outline, this structure - describes it. See the definition of the FT_Outline - structure.

-
- -

- 8. Rendering glyph outlines into bitmaps -

- -

You can easily test the format of the glyph image by inspecting the - face->glyph->format variable. If its value is - ft_glyph_format_bitmap, the glyph image that was loaded is a - bitmap that can be directly blit to your own surfaces through your - favorite graphics library (FreeType 2 doesn't provide bitmap - blitting routines, as you may imagine :-)

- -

If the format is ft_glyph_format_outline or something else, - the library provides a means to convert such glyph images to bitmaps - through what are called rasters.

- -

On the other hand, if the image is a scalable outline or something - else, FreeType provides a function to convert the glyph image into a - pre-existing bitmap that you will handle to it, named - FT_Get_Glyph_Bitmap. Here's a simple example code - that renders an outline into a monochrome bitmap:

- - - 
-    {
-      FT_GlyphSlot  glyph;
-
-      ... load glyph ...
-
-      glyph = face->glyph;   /* shortcut to glyph data */
-      if ( glyph->format == ft_glyph_format_outline )
-      {
-        FT_Bitmap  bit;
-
-        /* set-up a bitmap descriptor for our target bitmap */
-        bit.rows       = bitmap_height;
-        bit.width      = bitmap_width;
-        bit.pitch      = bitmap_row_bytes;
-        /* render into a mono bitmap */
-        bit.pixel_mode = ft_pixel_mode_mono;
-        bit.buffer     = bitmap_buffer;
-
-        /* render the outline directly into the bitmap */
-        error = FT_Get_Glyph_Bitmap( face, &bit );
-        if ( error ) { ... }
-      }
-    }
- - -

You should note that FT_Get_Glyph_Bitmap() doesn't - create the bitmap. It only needs a descriptor, of type - FT_Bitmap, and writes directly into it.

- -

Note that the FreeType scan-converter for outlines can also generate - anti-aliased glyph bitmaps with 128 level of grays. For now, it is - restricted to rendering to 8-bit gray-level bitmaps, though this may - change in the future. Here is some code to do just that:

- - - 
-    {
-      FT_GlyphSlot  glyph;
-
-      ... load glyph ...
-
-      glyph = face->glyph;   /* shortcut to glyph data */
-      if ( glyph->format == ft_glyph_format_outline )
-      {
-        FT_Bitmap  bit;
-
-        /* set-up a bitmap descriptor for our target bitmap */
-        bit.rows       = bitmap_height;
-        bit.width      = bitmap_width;
-        bit.pitch      = bitmap_row_bytes;
-        /* 8-bit gray-level bitmap */
-        bit.pixel_mode = ft_pixel_mode_gray;
-        /* MUST be 128 for now     */
-        bit.grays      = 128;
-        bit.buffer     = bitmap_buffer;
-
-        /* clean the bitmap - IMPORTANT */
-        memset( bit.buffer, 0, bit.rows*bit.pitch );
-
-        /* render the outline directly into the bitmap */
-        error = FT_Get_Glyph_Bitmap( face, &bit );
-        if ( error ) { ... }
-      }
-    }
- - -

You will notice that

- -
    -
  • -

    As previously, FT_Get_Glyph_Bitmap() doesn't generate - the bitmap, it simply renders to it.

    -
    • -
  • -

    The target bitmap must be cleaned before calling the function. - This is a limitation of our current anti-aliasing algorithm and is - EXTREMELY important.

    -
    • -
  • -

    The anti-aliaser uses 128 levels of grays exclusively for - now (this will probably change in a near future). This means that - you must set bit.grays to 128. The generated - image uses values from 0 (back color) to 127 (foreground color).

    -
    • -
  • -

    It is not possible to render directly an anti-aliased - outline into a pre-existing gray-level bitmap, or even any - colored-format one (like RGB16 or paletted 8-bits). We will not - discuss this issue in great details here, but the reason is that we - do not want to deal with graphics composition (or alpha-blending) - within FreeType.

    -

    • -
-
-
- - -