diff --git a/docs/design/design-4.html b/docs/design/design-4.html index 0a0c63338..f71cf07d0 100644 --- a/docs/design/design-4.html +++ b/docs/design/design-4.html @@ -1,289 +1,301 @@ + -The Design of FreeType 2 - Internal Objects - - + + + + The Design of FreeType 2 - Internal Objects - - -
- -

The Design of FreeType 2

- -
-

III. Internal Objects and Classes

-
- -

Let's have a look now at the internal objects that FreeType 2 - uses, i.e. those not directly available to client applications, and - let's see how they fit in the picture.

- -

1. Memory management:

- -

All memory management operations are performed through three specific - routines of the base layer, namely: FT_Alloc, FT_Realloc, - and FT_Free. Each one of these functions expects a - FT_Memory handle as its first parameter.

- -

The latter is a pointer to a simple object used to describe the current - memory pool/manager to use. It contains a simple table of - alloc/realloc/free functions. A memory manager is created at - library initialisation time by FT_Init_FreeType by calling - the function FT_New_Memory provided by the ftsystem - component.

- -

By default, this manager uses the ANSI malloc, realloc - and free functions. However, as ftsystem is a replaceable - part of the base layer, a specific build of the library could provide - a different default memory manager.

- -

Even with a default build, client applications are still able to provide - their own memory manager by not calling FT_Init_FreeType but - follow these simple steps:

- -
    -

  1. - create a new FT_Memory object by hand. The definition of - FT_MemoryRec is located in the public file - <freetype/ftsystem.h>. -

    2. - -

  2. - call FT_New_Library to create a new library instance using - your custom memory manager. This new library is "virgin" and doesn't - contain any registered modules. -

    3. - -

  3. - Register the set of default modules by calling the function - FT_Add_Default_Modules provided by the ftinit - component, or manually register your drivers by repeatedly - calling FT_Add_Module. -

    4. -
- - -
-

2. Input streams:

- -

Font files are always read through FT_Stream objects. The - definition of FT_StreamRec is located in the public file - <freetype/ftsystem.h>, which allows client developers - to provide their own implementation of streams if they wish so.

- -

The function FT_New_Face will always automatically create a - new stream object from the C pathname given as its second argument. - This is achieved by calling the function FT_New_Stream provided - by the ftsystem component. As the latter is replaceable, - the implementation of streams may vary greatly between platforms.

- -

As an example, the default implementation of streams is located in - the file "src/base/ftsystem.c" and uses the ANSI fopen, - fseek, fread calls. However, the Unix build of - FreeType 2 provides an alternative implementation that uses - memory-mapped files, when available on the host platform, resulting - in a significant access speed-up.

- -

FreeType distinguishes between memory-based and disk-based - streams. In the first case, all data is directly accessed in memory - (e.g. ROM-based, write-only static data and memory-mapped files), - while in the second, portions of the font files are read in chunks - called "frames", and temorarily buffered adequately through typical - seek/read operations.

- -

The FreeType stream sub-system also implements extremely efficient - algorithms to very quickly load structures from font files while - ensure complete safety in the case of "broken file".

- -

The function FT_New_Memory_Face can be used - to directly create/open a FT_Face object from data that is - readily available in memory (including ROM-based fonts).

- -

Finally, in the case where a custom input stream is needed, client - applications can use the function FT_Open_Face, which can - accept custom input streams.. This may be useful in the case of - compressed or remote font files, or even embedded font files that - need to be extracted from certain documents.

- -

Note that each face owns a single stream, which is also destroyed - by FT_Done_Face. Generally speaking, it's certainly - not a good idea to keep numerous FT_Face objects - opened.

- -
-

3. Modules:

- -

A FreeType 2 module is itself a piece of code. However, the library - creates a single FT_Module object for each module that is - registered when FT_Add_Module is called.

- -

The definition of FT_ModuleRec is not publicly available - to client applications. However, each module type is described - by a simple and public structure named FT_Module_Class, - defined in <freetype/ftmodule.h>, and is detailed - heavily later in this document:

- -

You need a pointer to a FT_Module_Class structure when - calling FT_Add_Module, whose declaration is:

- -

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

Calling this function will do the following:

- -
    -

  • - it will check if the library already holds a module object corresponding - to the same module name as the one found in the FT_Module_Class. -

    • - -

  • - it this is the case, it will compare the module version number to see - if it is possible to upgrade the module to a new version. If - the module class's version number is smaller than the already - installed one, the function returns immediately. Similarly, it checks - that the version of FreeType 2 that is running is correct compared - to the one required by the module. -

    • - -

  • - it creates a new FT_Module object, using data and flags - of the module class to determine its byte size and how to properly - initialize it. -

    • - -

  • - when a module initializer is present in the module class, it will - be called to complete the module object's initialisation. -

    • - -

  • - the new module is added to the library's list of "registered" - modules. In case of an upgrade, the previous module object is - simply destroyed. -

    • - -
- -

Note that this function doesn't return a FT_Module handle, - given that module objects are completely internal to the library - (and client applications shouldn't normally mess with them :-)

- -

Finally, it's important to understand that FreeType 2 recognizes - and manages several kinds of modules. These will be explained in - more details later in this document, but we'll list for now the - following types:

- -
    -

  • - renderer modules are used to convert native glyph images to - bitmaps/pixmaps. FT2 comes with two renderer modules - by default: one to generate monochrome bitmaps, the other to generate - high-quality anti-aliased pixmaps. -

    • - -

  • - font driver modules are used to support one or more specific - font format. Typically, each font driver provides a specific - implementation/derivative of FT_Face, FT_Size, - FT_GlyphSlot as well as FT_CharMap. -

    • - -

  • - helper modules are used to contain code that is shared - by several font drivers. For example, the sfnt module is - used to parse and manage tables found in SFNT-based font formats; - it is then used by both the TrueType and OpenType font drivers. -

    • - -

  • - finally, the auto-hinter module has a specific place in - the library's design, as its role is to process vectorial glyph - outlines, independently of their native font format, to produce - optimal results at small pixel sizes.. -

    • -
- -

Note that every FT_Face object is owned by the - corresponding font driver (that depends on the original font file's - format). This means that all face objects are destroyed when a module - is removed/unregistered from a library instance (typically by calling - FT_Remove_Module).

- - -

Because of this, you should always take care that no FT_Face - object is opened when you upgrade or remove a module from a library, - as this could cause unexpected object deletion !!

- - -
-

4. Libraries:

- -

And we now come back to our well-known FT_Library objects. - From what have been said here, we already know that a library - instance owns at least the following:

- -
    -

  • - a memory manager object (FT_Memory), used for all - allocation/releases within the instance. -

    • - -

  • - a list of FT_Module objects, corresponding to the - "installed" or "registered" modules of the instance. This - list can be changed at any time through FT_Add_Module - and FT_Remove_Module. -

    • - -

  • - finally, remember that face objects are owner by font drivers - that are themselves modules owned by the library. -

    • -
- -

There is however another object owned by the library instance that - hasn't been described until now, and it's the raster pool.

- -

The raster pool is simply a block of memory of fixed size - that is used internally as a "scratch area" for various memory-hungry - transient operations. For example, it is used by each renderer when - converting a vectorial glyph outline into a bitmap (actually, - that's where its name comes from :-).

- -

The advantage of using a raster pool comes from the fact that it - allows us to completely avoid memory allocation during certain - memory-intensive though common transient operations (like - glyph bitmap generation), speeding up the overall process.

- -

The size of the raster pool is fixed at initialisation time - (it defaults to 16 Kb) and cannot be changed at run-time - (though we could fix this if there's a real need for that).

- -

When a transient operation needs more memory than the pool's - size, it can decide to either allocate a heap block as an - exceptional condition, or sub-divide recursively the task to - perform in order to never exceed the pool's threshold..

- -

This extremely memory-conservative behaviour is certainly one of - the keys to FreeType's performance in certain areas (most importantly - in glyph rendering / scanline-conversion ).

- -
-

5. Summary

- -

Finally, the following picture illustrates what has been said - in this section, as well as the previous, by presenting the - complete object graph of FreeType 2's base design:

- -
- -
+ + + +

+ The Design of FreeType 2 +

+ +
+ + +
+ + + +
+

+ III. Internal Objects and Classes +

+
+ +

Let us have a look now at the internal objects that + FreeType 2 uses, i.e., those not directly available to client + applications, and see how they fit into the picture.

+ +

+ 1. Memory management +

+ +

All memory management operations are performed through three specific + routines of the base layer, namely: FT_Alloc(), + FT_Realloc(), and FT_Free(). Each one of these + functions expects a FT_Memory handle as its first + parameter.

+ +

The latter is a pointer to a simple object used to describe the + current memory pool/manager. It contains a simple table of + alloc/realloc/free functions. A memory manager is created at library + initialization time by FT_Init_FreeType(), calling the function + FT_New_Memory() provided by the ftsystem + component.

+ +

By default, this manager uses the ANSI malloc(), + realloc(), and free() functions. However, as + ftsystem is a replaceable part of the base layer, a specific + build of the library could provide a different default memory + manager.

+ +

Even with a default build, client applications are still able to + provide their own memory manager by not calling + FT_Init_FreeType() but follow these simple steps:

+ +
    +
  1. +

    Create a new FT_Memory object by hand. The definition + of FT_MemoryRec is located in the public file + <freetype/ftsystem.h>.

    +
    2. +
  2. +

    Call FT_New_Library() to create a new library instance + using your custom memory manager. This new library doesn't yet + contain any registered modules.

    +
    3. +
  3. +

    Register the set of default modules by calling the function + FT_Add_Default_Modules() provided by the ftinit + component, or manually register your drivers by repeatedly + calling FT_Add_Module().

    +
    4. +
+ +
+ +

+ 2. Input streams +

+ +

Font files are always read through FT_Stream objects. The + definition of FT_StreamRec is located in the public file + <freetype/ftsystem.h>, which allows client developers to + provide their own implementation of streams if they wish so.

+ +

The function FT_New_Face() will always automatically create + a new stream object from the C pathname given as its second + argument. This is achieved by calling the function + FT_New_Stream() provided by the ftsystem component. + As the latter is replaceable, the implementation of streams may vary + greatly between platforms.

+ +

As an example, the default implementation of streams is located in + the file src/base/ftsystem.c and uses the ANSI + fopen(), fseek(), and fread() calls. + However, the Unix build of FreeType 2 provides an alternative + implementation that uses memory-mapped files, when available on the host + platform, resulting in a significant access speed-up.

+ +

FreeType distinguishes between memory-based and disk-based streams. + In the first case, all data is directly accessed in memory (e.g. + ROM-based, write-only static data and memory-mapped files), while in the + second, portions of the font files are read in chunks called + frames, and temporarily buffered similarly through typical + seek/read operations.

+ +

The FreeType stream sub-system also implements extremely efficient + algorithms to very quickly load structures from font files while + ensuring complete safety in the case of a "broken file".

+ +

The function FT_New_Memory_Face() can be used to directly + create/open a FT_Face object from data that is readily + available in memory (including ROM-based fonts).

+ +

Finally, in the case where a custom input stream is needed, client + applications can use the function FT_Open_Face(), which can + accept custom input streams. This may be useful in the case of + compressed or remote font files, or even embedded font files that need + to be extracted from certain documents.

+ +

Note that each face owns a single stream, which is also destroyed by + FT_Done_Face(). Generally speaking, it is certainly + not a good idea to keep numerous FT_Face objects + opened.

+ +
+ +

+ 3. Modules +

+ +

A FreeType 2 module is itself a piece of code. However, the + library creates a single FT_Module object for each module that + is registered when FT_Add_Module() is called.

+ +

The definition of FT_ModuleRec is not publicly available to + client applications. However, each module type is described by + a simple public structure named FT_Module_Class, defined in + <freetype/ftmodule.h>, and is described later in this + document:

+ +

You need a pointer to an FT_Module_Class structure when + calling FT_Add_Module(), whose declaration is:

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

Calling this function will do the following:

+ +
    +
  • +

    It will check whether the library already holds a module object + corresponding to the same module name as the one found in + FT_Module_Class.

    +
    • +
  • +

    If this is the case, it will compare the module version number to + see whether it is possible to upgrade the module to a new + version. If the module class's version number is smaller than the + already installed one, the function returns immediately. Similarly, + it checks that the version of FreeType 2 that is running is + correct compared to the one required by the module.

    +
    • +
  • +

    It creates a new FT_Module object, using data and flags + of the module class to determine its byte size and how to properly + initialize it.

    +
    • +
  • +

    If a module initializer is present in the module class, it will + be called to complete the module object's initialization.

    +
    • +
  • +

    The new module is added to the library's list of "registered" + modules. In case of an upgrade, the previous module object is + simply destroyed.

    +
    • +
+ +

Note that this function doesn't return an FT_Module handle, + given that module objects are completely internal to the library (and + client applications shouldn't normally mess with them :-)

+ +

Finally, it is important to understand that FreeType 2 + recognizes and manages several kinds of modules. These will be + explained in more details later in this document, but we will list for + now the following types:

+ +
    +
  • +

    Renderer modules are used to convert native glyph images + to bitmaps/pixmaps. FreeType 2 comes with two renderer modules + by default: one to generate monochrome bitmaps, the other to + generate high-quality anti-aliased pixmaps.

    +
    • +
  • +

    Font driver modules are used to support one or more font + formats. Typically, each font driver provides a specific + implementation/derivative of FT_Face, FT_Size, + FT_GlyphSlot, as well as FT_CharMap.

    +
    • +
  • +

    Helper modules are shared by several font drivers. For + example, the sfnt module parses and manages tables found in + SFNT-based font formats; it is then used by both the TrueType and + OpenType font drivers.

    +
    • +
  • +

    Finally, the auto-hinter module has a specific place in + the library's design, as its role is to process vectorial glyph + outlines, independently of their native font format, to produce + optimal results at small pixel sizes.

    +
    • +
+ +

Note that every FT_Face object is owned by the + corresponding font driver, depending on the original font file's format. + This means that all face objects are destroyed when a module is + removed/unregistered from a library instance (typically by calling the + FT_Remove_Module() function).

+ +

Because of this, you should always take care that no + FT_Face object is opened when you upgrade or remove a module + from a library, as this could cause unexpected object deletion!

+ +
+ +

+ 4. Libraries +

+ +

We now come back to our well-known FT_Library object. From + what have been said before, we already know that a library instance owns + at least the following:

+ +
    +
  • +

    A memory manager object (FT_Memory), used for all + allocation/releases within the instance.

    +
    • +
  • +

    A list of FT_Module objects, corresponding to the + "installed" or "registered" modules of the instance. This list can + be changed at any time through FT_Add_Module() and + FT_Remove_Module().

    +
    • +
  • +

    Remember that face objects are owner by font drivers that are + themselves modules owned by the library.

    +
    • +
+ +

There is however another object owned by the library instance that + hasn't been described yet: the raster pool.

+ +

The raster pool is simply a block of memory of fixed size + that is used internally as a "scratch area" for various memory-hungry + transient operations, avoiding memory allocation. For example, it is + used by each renderer when converting a vectorial glyph outline into a + bitmap (actually, that's where its name comes from :-).

+ +

The size of the raster pool is fixed at initialisation time (it + defaults to 16kByte) and cannot be changed at run-time (though we could + fix this if there is a real need for that).

+ +

When a transient operation needs more memory than the pool's size, it + can decide to either allocate a heap block as an exceptional condition, + or sub-divide recursively the task to perform in order to never exceed + the pool's threshold.

+ +

This extremely memory-conservative behaviour is certainly one of the + keys to FreeType's performance in certain areas (most importantly in + glyph rendering/scanline-conversion).

+ +
+ +

+ 5. Summary +

+ +

Finally, the following picture illustrates what has been said in this + section, as well as the previous, by presenting the complete object + graph of FreeType 2's base design:

+ +
+ to be done +
+ +
+
diff --git a/docs/design/design-5.html b/docs/design/design-5.html index 3e366abe1..76634d277 100644 --- a/docs/design/design-5.html +++ b/docs/design/design-5.html @@ -1,324 +1,400 @@ + -FreeType 2 - Modules - - + + + + 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").

    + + + +

    + The design of FreeType 2 +

    + +
    + +
    + + + +
    +

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

    -
    - -

    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 -

      • +
    • +

      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, FreeType 2 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 Bézier outlines + through 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: 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.

      +
    -
    - -

    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

    - -
    + +

    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 initialization 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 us + 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!

    + +

    Here the definition of FT_Module_Class, with some + explanation. 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;
    +     + +

    A description of its fields:

    + +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + module_flags + +

    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 an 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 if the module needs + to sub-class the base FT_ModuleRec class.

    +
    + module_name + +

    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 whether 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. The default value is + 0x20000 for FreeType version  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, if there is one. It is 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 + +

    A pointer to a function used to initialize 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 initialize the fields of FT_ModuleRec + subclasses.

    + +

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

    +
    + module_done + +

    A pointer to a function used to finalize 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 + finalization is necessary

    +
    + get_interface + +

    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 is no point to look so far into the + library's design.

    + +

    When FT_Add_Module is called, it first allocates a new + module instance, using the module_size class field to determine + its byte size. The function initializes the root FT_ModuleRec + field, 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 + describe these classes in the next chapters.

    + +
+