# FreeType-2.3.1 API Reference

# Module Management

## Synopsis

| FT_Module_Class |  | FT_New_Library |  | FT_Renderer_Class
| FT_Add_Module |  | FT_Done_Library |  | FT_Get_Renderer
| FT_Get_Module |  | FT_Set_Debug_Hook |  | FT_Set_Renderer
| FT_Remove_Module |  | FT_Add_Default_Modules |  |

The definitions below are used to manage modules within FreeType. Modules can be added, upgraded, and removed at runtime.

#### FT_Module_Class

      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.

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_init | A function used to initialize (not create) a new module object.
module_done | A function used to finalize (not destroy) a given module object
get_interface | Queries a given module for a specific interface by name.

[Index] |  | [TOC]

#### FT_Add_Module

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

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

[Index] |  | [TOC]

#### FT_Get_Module

      FT_EXPORT( FT_Module )
      FT_Get_Module( FT_Library   library,
                     const char*  module_name );

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

[Index] |  | [TOC]

#### FT_Remove_Module

      FT_EXPORT( FT_Error )
      FT_Remove_Module( FT_Library  library,
                        FT_Module   module );

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

[Index] |  | [TOC]

#### FT_New_Library

      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.

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.

[Index] |  | [TOC]

#### FT_Done_Library

      FT_EXPORT( FT_Error )
      FT_Done_Library( FT_Library  library );

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

[Index] |  | [TOC]

#### FT_Set_Debug_Hook

      FT_EXPORT( void )
      FT_Set_Debug_Hook( FT_Library         library,
                         FT_UInt            hook_index,
                         FT_DebugHook_Func  debug_hook );

Sets a debug hook function for debugging the interpreter of a font format.

inout

library | A handle to the library object.

input

hook_index | The index of the debug hook. You should use the values defined in ‘ftobjs.h’, e.g., ‘FT_DEBUG_HOOK_TRUETYPE’.
debug_hook | The function used to debug the interpreter.

note
Currently, four debug hook slots are available, but only two (for the TrueType and the Type 1 interpreter) are defined. Since the internal headers of FreeType are no longer installed, the symbol ‘FT_DEBUG_HOOK_TRUETYPE’ isn't available publicly. This is a bug and will be fixed in a forthcoming release.

[Index] |  | [TOC]

#### FT_Add_Default_Modules

      FT_EXPORT( void )
      FT_Add_Default_Modules( FT_Library  library );

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

[Index] |  | [TOC]

#### FT_Renderer_Class

      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 FT_Module_Class fields.
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.
set_mode | A method used to pass additional parameters.
raster_class | For FT_GLYPH_FORMAT_OUTLINE renderers only. This is a pointer to its raster's class.
raster | For FT_GLYPH_FORMAT_OUTLINE renderers only. This is a pointer to the corresponding raster object, if any.

[Index] |  | [TOC]

#### FT_Get_Renderer

      FT_EXPORT( FT_Renderer )
      FT_Get_Renderer( FT_Library       library,
                       FT_Glyph_Format  format );

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

[Index] |  | [TOC]

#### FT_Set_Renderer

      FT_EXPORT( FT_Error )
      FT_Set_Renderer( FT_Library     library,
                       FT_Renderer    renderer,
                       FT_UInt        num_params,
                       FT_Parameter*  parameters );

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

[Index] |  | [TOC]