FreeType » Docs » Support API » Module Management
Module Management¶
Synopsis¶
The definitions below are used to manage modules within FreeType. Internal and external modules can be added, upgraded, and removed at runtime. For example, an alternative renderer or proprietary font driver can be registered and prioritized. Additionally, some module properties can also be controlled.
Here is a list of existing values of the module_name field in the FT_Module_Class structure.
autofitter
bdf
cff
gxvalid
otvalid
pcf
pfr
psaux
pshinter
psnames
raster1
sfnt
smooth
truetype
type1
type42
t1cid
winfonts
Note that the FreeType Cache sub-system is not a FreeType module.
FT_Module¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
typedef struct FT_ModuleRec_* FT_Module;
A handle to a given FreeType module object. A module can be a font driver, a renderer, or anything else that provides services to the former.
FT_Module_Constructor¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
A function used to initialize (not create) a new module object.
input
| module |
The module to initialize. |
FT_Module_Destructor¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
typedef void
(*FT_Module_Destructor)( FT_Module module );
A function used to finalize (not destroy) a given module object.
input
| module |
The module to finalize. |
FT_Module_Requester¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
typedef FT_Module_Interface
(*FT_Module_Requester)( FT_Module module,
const char* name );
A function used to query a given module for a specific interface.
input
| module |
The module to be searched. |
| name |
The name of the interface in the module. |
FT_Module_Class¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
typedef struct FT_Module_Class_
{
FT_ULong module_flags;
FT_Long 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;
The module class descriptor. While being a public structure necessary for FreeType's module bookkeeping, most of the fields are essentially internal, not to be used directly by an application.
fields
| module_flags |
Bit flags describing the module. |
| module_size |
The size of one module object/instance in bytes. |
| module_name |
The name of the module. |
| module_version |
The version, as a 16.16 fixed number (major.minor). |
| module_requires |
The version of FreeType this module requires, as a 16.16 fixed number (major.minor). Starts at version 2.0, i.e., 0x20000. |
| module_interface |
A typeless pointer to a structure (which varies between different modules) that holds the module's interface functions. This is essentially what |
| module_init |
The initializing function. |
| module_done |
The finalizing function. |
| get_interface |
The interface requesting function. |
FT_Add_Module¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( FT_Error )
FT_Add_Module( FT_Library library,
const FT_Module_Class* clazz );
Add a new module to a given library instance.
inout
| library |
A handle to the library object. |
input
| clazz |
A pointer to class descriptor for the module. |
return
FreeType error code. 0 means success.
note
An error will be returned if a module already exists by that name, or if the module requires a version of FreeType that is too great.
FT_Get_Module¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( FT_Module )
FT_Get_Module( FT_Library library,
const char* module_name );
Find a module by its name.
input
| library |
A handle to the library object. |
| module_name |
The module's name (as an ASCII string). |
return
A module handle. 0 if none was found.
note
FreeType's internal modules aren't documented very well, and you should look up the source code for details.
FT_Remove_Module¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( FT_Error )
FT_Remove_Module( FT_Library library,
FT_Module module );
Remove a given module from a library instance.
inout
| library |
A handle to a library object. |
input
| module |
A handle to a module object. |
return
FreeType error code. 0 means success.
note
The module object is destroyed by the function in case of success.
FT_Add_Default_Modules¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( void )
FT_Add_Default_Modules( FT_Library library );
Add the set of default drivers to a given library object. This is only useful when you create a library object with FT_New_Library (usually to plug a custom memory manager).
inout
| library |
A handle to a new library object. |
FT_FACE_DRIVER_NAME¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
#define FT_FACE_DRIVER_NAME( face ) \
( ( *(FT_Module_Class**)( ( face )->driver ) )->module_name )
A macro that retrieves the name of a font driver from a face object.
note
The font driver name is a valid module_name for FT_Property_Set and FT_Property_Get. This is not the same as FT_Get_Font_Format.
since
2.11
FT_Property_Set¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( FT_Error )
FT_Property_Set( FT_Library library,
const FT_String* module_name,
const FT_String* property_name,
const void* value );
Set a property for a given module.
input
| library |
A handle to the library the module is part of. |
| module_name |
The module name. |
| property_name |
The property name. Properties are described in section ‘Driver properties’. Note that only a few modules have properties. |
| value |
A generic pointer to a variable or structure that gives the new value of the property. The exact definition of |
return
FreeType error code. 0 means success.
note
If module_name isn't a valid module name, or property_name doesn't specify a valid property, or if value doesn't represent a valid value for the given property, an error is returned.
The following example sets property ‘bar’ (a simple integer) in module ‘foo’ to value 1.
FT_UInt bar;
bar = 1;
FT_Property_Set( library, "foo", "bar", &bar );
Note that the FreeType Cache sub-system doesn't recognize module property changes. To avoid glyph lookup confusion within the cache you should call FTC_Manager_Reset to completely flush the cache if a module property gets changed after FTC_Manager_New has been called.
It is not possible to set properties of the FreeType Cache sub-system itself with FT_Property_Set; use ?FTC_Property_Set? instead.
since
2.4.11
FT_Property_Get¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( FT_Error )
FT_Property_Get( FT_Library library,
const FT_String* module_name,
const FT_String* property_name,
void* value );
Get a module's property value.
input
| library |
A handle to the library the module is part of. |
| module_name |
The module name. |
| property_name |
The property name. Properties are described in section ‘Driver properties’. |
inout
| value |
A generic pointer to a variable or structure that gives the value of the property. The exact definition of |
return
FreeType error code. 0 means success.
note
If module_name isn't a valid module name, or property_name doesn't specify a valid property, or if value doesn't represent a valid value for the given property, an error is returned.
The following example gets property ‘baz’ (a range) in module ‘foo’.
typedef range_
{
FT_Int32 min;
FT_Int32 max;
} range;
range baz;
FT_Property_Get( library, "foo", "baz", &baz );
It is not possible to retrieve properties of the FreeType Cache sub-system with FT_Property_Get; use ?FTC_Property_Get? instead.
since
2.4.11
FT_Set_Default_Properties¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( void )
FT_Set_Default_Properties( FT_Library library );
If compilation option FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES is set, this function reads the FREETYPE_PROPERTIES environment variable to control driver properties. See section ‘Driver properties’ for more.
If the compilation option is not set, this function does nothing.
FREETYPE_PROPERTIES has the following syntax form (broken here into multiple lines for better readability).
<optional whitespace>
<module-name1> ':'
<property-name1> '=' <property-value1>
<whitespace>
<module-name2> ':'
<property-name2> '=' <property-value2>
...
Example:
FREETYPE_PROPERTIES=truetype:interpreter-version=35 \
cff:no-stem-darkening=0
inout
| library |
A handle to a new library object. |
since
2.8
FT_New_Library¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( FT_Error )
FT_New_Library( FT_Memory memory,
FT_Library *alibrary );
This function is used to create a new FreeType library instance from a given memory object. It is thus possible to use libraries with distinct memory allocators within the same program. Note, however, that the used FT_Memory structure is expected to remain valid for the life of the FT_Library object.
Normally, you would call this function (followed by a call to FT_Add_Default_Modules or a series of calls to FT_Add_Module, and a call to FT_Set_Default_Properties) instead of FT_Init_FreeType to initialize the FreeType library.
Don't use FT_Done_FreeType but FT_Done_Library to destroy a library instance.
input
| memory |
A handle to the original memory object. |
output
| alibrary |
A pointer to handle of a new library object. |
return
FreeType error code. 0 means success.
note
See the discussion of reference counters in the description of FT_Reference_Library.
FT_Done_Library¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( FT_Error )
FT_Done_Library( FT_Library library );
Discard a given library object. This closes all drivers and discards all resource objects.
input
| library |
A handle to the target library. |
return
FreeType error code. 0 means success.
note
See the discussion of reference counters in the description of FT_Reference_Library.
FT_Reference_Library¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( FT_Error )
FT_Reference_Library( FT_Library library );
A counter gets initialized to 1 at the time an FT_Library structure is created. This function increments the counter. FT_Done_Library then only destroys a library if the counter is 1, otherwise it simply decrements the counter.
This function helps in managing life-cycles of structures that reference FT_Library objects.
input
| library |
A handle to a target library object. |
return
FreeType error code. 0 means success.
since
2.4.2
FT_Renderer¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
typedef struct FT_RendererRec_* FT_Renderer;
A handle to a given FreeType renderer. A renderer is a module in charge of converting a glyph's outline image to a bitmap. It supports a single glyph image format, and one or more target surface depths.
FT_Renderer_Class¶
Defined in FT_RENDER_H (freetype/ftrender.h).
typedef struct FT_Renderer_Class_
{
FT_Module_Class root;
FT_Glyph_Format glyph_format;
FT_Renderer_RenderFunc render_glyph;
FT_Renderer_TransformFunc transform_glyph;
FT_Renderer_GetCBoxFunc get_glyph_cbox;
FT_Renderer_SetModeFunc set_mode;
FT_Raster_Funcs* raster_class;
} FT_Renderer_Class;
The renderer module class descriptor.
fields
| root |
The root |
| glyph_format |
The glyph image format this renderer handles. |
| render_glyph |
A method used to render the image that is in a given glyph slot into a bitmap. |
| transform_glyph |
A method used to transform the image that is in a given glyph slot. |
| get_glyph_cbox |
A method used to access the glyph's cbox. |
| set_mode |
A method used to pass additional parameters. |
| raster_class |
For |
FT_Get_Renderer¶
Defined in FT_RENDER_H (freetype/ftrender.h).
FT_EXPORT( FT_Renderer )
FT_Get_Renderer( FT_Library library,
FT_Glyph_Format format );
Retrieve the current renderer for a given glyph format.
input
| library |
A handle to the library object. |
| format |
The glyph format. |
return
A renderer handle. 0 if none found.
note
An error will be returned if a module already exists by that name, or if the module requires a version of FreeType that is too great.
To add a new renderer, simply use FT_Add_Module. To retrieve a renderer by its name, use FT_Get_Module.
FT_Set_Renderer¶
Defined in FT_RENDER_H (freetype/ftrender.h).
FT_EXPORT( FT_Error )
FT_Set_Renderer( FT_Library library,
FT_Renderer renderer,
FT_UInt num_params,
FT_Parameter* parameters );
Set the current renderer to use, and set additional mode.
inout
| library |
A handle to the library object. |
input
| renderer |
A handle to the renderer object. |
| num_params |
The number of additional parameters. |
| parameters |
Additional parameters. |
return
FreeType error code. 0 means success.
note
In case of success, the renderer will be used to convert glyph images in the renderer's known format into bitmaps.
This doesn't change the current renderer for other formats.
Currently, no FreeType renderer module uses parameters; you should thus always pass NULL as the value.
FT_Set_Debug_Hook¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
FT_EXPORT( void )
FT_Set_Debug_Hook( FT_Library library,
FT_UInt hook_index,
FT_DebugHook_Func debug_hook );
Set a debug hook function for debugging the interpreter of a font format.
While this is a public API function, an application needs access to FreeType's internal header files to do something useful.
Have a look at the source code of the ttdebug FreeType demo program for an example of its usage.
inout
| library |
A handle to the library object. |
input
| hook_index |
The index of the debug hook. You should use defined enumeration macros like |
| debug_hook |
The function used to debug the interpreter. |
note
Currently, four debug hook slots are available, but only one (for the TrueType interpreter) is defined.
FT_Driver¶
Defined in FT_FREETYPE_H (freetype/freetype.h).
typedef struct FT_DriverRec_* FT_Driver;
A handle to a given FreeType font driver object. A font driver is a module capable of creating faces from font files.
FT_DebugHook_Func¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
typedef FT_Error
(*FT_DebugHook_Func)( void* arg );
A drop-in replacement (or rather a wrapper) for the bytecode or charstring interpreter's main loop function.
Its job is essentially
-
to activate debug mode to enforce single-stepping,
-
to call the main loop function to interpret the next opcode, and
-
to show the changed context to the user.
An example for such a main loop function is TT_RunIns (declared in FreeType's internal header file src/truetype/ttinterp.h).
Have a look at the source code of the ttdebug FreeType demo program for an example of a drop-in replacement.
inout
| arg |
A typeless pointer, to be cast to the main loop function's data structure (which depends on the font module). For TrueType fonts it is bytecode interpreter's execution context, |
FT_DEBUG_HOOK_XXX¶
Defined in FT_MODULE_H (freetype/ftmodapi.h).
#define FT_DEBUG_HOOK_TRUETYPE 0
A list of named debug hook indices.
values
| FT_DEBUG_HOOK_TRUETYPE |
This hook index identifies the TrueType bytecode debugger. |