From 7bfc089dc92bfe56649229985b59a9ba7241ddfe Mon Sep 17 00:00:00 2001 From: David Turner Date: Mon, 30 Oct 2000 18:55:47 +0000 Subject: [PATCH] added page 5 of design documentation --- docs/design/design-5.html | 324 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 324 insertions(+) create mode 100644 docs/design/design-5.html diff --git a/docs/design/design-5.html b/docs/design/design-5.html new file mode 100644 index 000000000..3e366abe1 --- /dev/null +++ b/docs/design/design-5.html @@ -0,0 +1,324 @@ + +FreeType 2 - Modules + + + + + +
+ +

FreeType 2 Design - Modules Classes

+ +
+

IV. Module Classes

+
+ +

We will now try to explain more precisely the types of modules + that FreeType 2 is capable of managing. Note that each one of them + is decribed with more details in the following chapters of this + document:

+ +
    +

  • + renderer modules are used to manage scalable glyph images. This + means transforming them, computing their bounding box, + and converting them to either monochrome or anti-aliased + bitmaps.

    + +

    Note that FreeType 2 is capable of dealing with any kind of + glyph images, as long as a renderer module is provided for it. The + library comes by default with two renderers:

    + +
    +

    raster

    +     		+

    supports the conversion of vectorial outlines (described by a + FT_Outline object) to monochrome bitmaps. +

    + +

    smooth

    +     		+

    supports the conversion of the same outlines to high-quality + anti-aliased pixmaps (using 256 levels of gray). Note + that this renderer also supports direct span generation.

    +
    + + +

  • + font driver modules are used to support one or more specific + font format. By default, FT2 comes with the following font drivers:

    + +
    + +
    +

    truetype

    +     		+

    supports TrueType font files

    +
    + +

    type1

    +     		+

    supports Postscript Type 1 fonts, both in binary (.pfb) or ASCII + (.pfa) formats, including Multiple Master fonts.

    +
    + +

    cid

    +     		+

    supports Postscript CID-keyed fonts

    +
    + +

    cff

    +     		+

    supports OpenType, CFF as well as CEF fonts (CEF is a derivative + of CFF used by Adobe in its SVG viewer).

    +
    + +

    winfonts

    +     		+

    supports Windows bitmap fonts (i.e. ".FON" and ".FNT").

    +
    + +

    Note that font drivers can support bitmapped or scalable glyph + images. A given font driver that supports bezier outlines through + the FT_Outline can also provide its own hinter, or rely + on FreeType's autohinter module. +

    • + +

  • + helper modules are used to hold shared code that is + often used by several font drivers, or even other modules. + Here are the default helpers:

    + +
    + sfnt + + used to support font formats based on the "SFNT" + storage scheme. This means TrueType & OpenType fonts as + well as other variants (like TrueType fonts that only + contain embedded bitmaps). +
    + + psnames + + used to provide various useful functions related to glyph + names ordering and Postscript encodings/charsets. For example, + this module is capable of automatically synthetizing a Unicode + charmap from a Type 1 glyph name dictionary. +
    + + psaux + + used to provide various useful functions related to Type 1 + charstring decoding, as this "feature" is needed by the + type1, cid and cff drivers. +
    +

    • + + +

  • + finally, the autohinter module has a specific role in + FreeType 2, as it can be used automatically during glyph loading + to process individual glyph outlines when a font driver doesn't + provide it's own hinting engine.

    + +

    This module's purpose and design is also heavily described + on the FreeType web site.

    +
    • +
+ +

We will now study how modules are described, then managed by + the library.

+ +

1. The FT_Module_Class structure:

+ +

As described later in this document, library initialisation is + performed by calling the FT_Init_FreeType function. The + latter is in charge of creating a new "empty" FT_Library + object, then register each "default" module by repeatedly calling + the FT_Add_Module function.

+ +

Similarly, client applications can call FT_Add_Module + any time they wish in order to register a new module in the library. + Let's take a look at this function's declaration:

+ +

+    extern FT_Error  FT_Add_Module( FT_Library              library,
+                                    const FT_Module_Class*  clazz );
+
+ +

As one can see, this function expects a handle to a library object, + as well as a pointer to a FT_Module_Class structure. It + returns an error code. In case of success, a new module object is + created and added to the library. Note by the way that the module + isn't returned directly by the call !.

+ +

Let's study the definition of FT_Module_Class, and explain it + a bit. The following code is taken from + <freetype/ftmodule.h>:

+ +

+  typedef struct  FT_Module_Class_
+  {
+    FT_ULong               module_flags;
+    FT_Int                 module_size;
+    const FT_String*       module_name;
+    FT_Fixed               module_version;
+    FT_Fixed               module_requires;
+
+    const void*            module_interface;
+
+    FT_Module_Constructor  module_init;
+    FT_Module_Destructor   module_done;
+    FT_Module_Requester    get_interface;
+
+  } FT_Module_Class;
+
+ +

here's a description of its fields:

+ +
+

module_flags

+		 +

this is a set of bit flags used to describe the module's +category. Valid values are:

+
    +

  • + ft_module_font_driver if the module is a font driver +

    • + +

  • + ft_module_renderer if the module is a renderer +

    • + +

  • + ft_module_hinter if the module is an auto-hinter +

    • + +

  • + ft_module_driver_scalable if the module is a font + driver supporting scalable glyph formats. +

    • + +

  • + ft_module_driver_no_outlines if the module is a + font driver supporting scalable glyph formats that cannot + be described by a FT_Outline object +

    • + +

  • + ft_module_driver_has_hinter if the module is a font + driver that provides its own hinting scheme/algorithm +

    • +
+
+ +

module_size

+		 +

an integer that gives the size in bytes of a given module +object. This should never be less than +sizeof(FT_ModuleRec), but can be more when the module +needs to sub-class the base FT_ModuleRec class.

+
+ +

module_name

+		 +

this is the module's internal name, coded as a simple ASCII C +string. There can't be two modules with the same name registered +in a given FT_Library object. However, FT_Add_Module +uses the module_version field to detect module upgrades +and perform them cleanly, even at run-time.

+
+ +

module_version

+		 +

a 16.16 fixed float number giving the module's major and minor + version numbers. It is used to determine wether a module needs + to be upgraded when calling FT_Add_Module.

+
+ +

module_requires

+		 +

a 16.16 fixed float number giving the version of FreeType 2 that + is required to install this module. By default, should be 0x20000 + for FreeType 2.0

+
+ +

module_requires

+		 +

most modules support one or more "interfaces", i.e. tables of function +pointers. This field is used to point to the module's main interface, +where there is one. It's a short-cut that prevents users of the module +to call "get_interface" each time they need to access one of the object's +common entry points.

+ +

Note that is is optional, and can be set to NULL. Other interfaces +can also be accessed through the get_interface field.

+
+ +

module_init

+		 +

this is a pointer to a function used to initialise the fields of +a fresh new FT_Module object. It is called after the module's +base fields have been set by the library, and is generally used to +initialise the fields of FT_ModuleRec subclasses.

+ +

Most module classes set it to NULL to indicate that no extra +initialisation is necessary

+
+ +

module_done

+		 +

this is a pointer to a function used to finalise the fields of +a given FT_Module object. Note that it is called before the +library unsets the module's base fields, and is generally used to +finalize the fields of FT_ModuleRec subclasses.

+ +

Most module classes set it to NULL to indicate that no extra +finalisation is necessary

+
+ +

get_interface

+		 +

this is a pointer to a function used to request the address of +a given module interface. Set it to NULL if you don't need to support +additional interfaces but the main one.

+
+ +
+ + +

2. The FT_Module type:

+ +

the FT_Module type is a handle (i.e. a pointer) to a given + module object / instance, whose base structure is given by the + internal FT_ModuleRec type. We will intentionally not + describe this structure here, as there's not point to look so far + in the library's design.

+ +

When FT_Add_Module is called, it first allocate a new + module instance, using the module_size class + field to determine its byte size. The function initializes + a the root FT_ModuleRec fields, then calls + the class-specific initializer module_init + when this field is not set to NULL.

+ +

Note that the library defines several sub-classes of FT_ModuleRec, + which are, as you could have guessed:

+ +
    +

  • FT_Renderer for renderer modules

    +

  • FT_Driver for font driver modules

    +

  • FT_AutoHinter for the auto-hinter

    +
+ +

Helper modules use the base FT_ModuleRec type. + We will now detail these classes in the next chapters

+ +
+ +