+
+FreeType 2 Design - Modules 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
+
+ |