Skip to content

FreeType » Docs » Core API » Library Setup

# Library Setup

## Synopsis

Functions to start and end the usage of the FreeType library.

Note that `FT_Library_Version` and `FREETYPE_XXX` are of limited use because even a new release of FreeType with only documentation changes increases the version number.

## FT_Library

Defined in FT_FREETYPE_H (freetype/freetype.h).

      typedef struct FT_LibraryRec_  *FT_Library;

A handle to a FreeType library instance. Each ‘library’ is completely independent from the others; it is the ‘root’ of a set of objects like fonts, faces, sizes, etc.

It also embeds a memory manager (see `FT_Memory`), as well as a scan-line converter object (see `FT_Raster`).

[Since 2.5.6] In multi-threaded applications it is easiest to use one `FT_Library` object per thread. In case this is too cumbersome, a single `FT_Library` object across threads is possible also, as long as a mutex lock is used around `FT_New_Face` and `FT_Done_Face`.

#### note

Library objects are normally created by `FT_Init_FreeType`, and destroyed with `FT_Done_FreeType`. If you need reference-counting (cf. `FT_Reference_Library`), use `FT_New_Library` and `FT_Done_Library`.

## FT_Init_FreeType

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Init_FreeType( FT_Library  *alibrary );

Initialize a new FreeType library object. The set of modules that are registered by this function is determined at build time.

#### output

alibrary | A handle to a new library object.

#### return

FreeType error code. 0 means success.

#### note

In case you want to provide your own memory allocating routines, use `FT_New_Library` instead, followed by a call to `FT_Add_Default_Modules` (or a series of calls to `FT_Add_Module`) and `FT_Set_Default_Properties`.

See the documentation of `FT_Library` and `FT_Face` for multi-threading issues.

If you need reference-counting (cf. `FT_Reference_Library`), use `FT_New_Library` and `FT_Done_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.

## FT_Done_FreeType

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( FT_Error )
      FT_Done_FreeType( FT_Library  library );

Destroy a given FreeType library object and all of its children, including resources, drivers, faces, sizes, etc.

#### input

library | A handle to the target library object.

#### return

FreeType error code. 0 means success.

## FT_Library_Version

Defined in FT_FREETYPE_H (freetype/freetype.h).

      FT_EXPORT( void )
      FT_Library_Version( FT_Library   library,
                          FT_Int      *amajor,
                          FT_Int      *aminor,
                          FT_Int      *apatch );

Return the version of the FreeType library being used. This is useful when dynamically linking to the library, since one cannot use the macros `FREETYPE_MAJOR`, `FREETYPE_MINOR`, and `FREETYPE_PATCH`.

#### input

library | A source library handle.

#### output

amajor | The major version number.
aminor | The minor version number.
apatch | The patch version number.

#### note

The reason why this function takes a `library` argument is because certain programs implement library initialization in a custom way that doesn't use `FT_Init_FreeType`.

In such cases, the library version might not be available before the library object has been created.

## FREETYPE_XXX

Defined in FT_FREETYPE_H (freetype/freetype.h).

    #define FREETYPE_MAJOR  2
    #define FREETYPE_MINOR  14
    #define FREETYPE_PATCH  3

These three macros identify the FreeType source code version. Use `FT_Library_Version` to access them at runtime.

#### values

FREETYPE_MAJOR | The major version number.
FREETYPE_MINOR | The minor version number.
FREETYPE_PATCH | The patch level.

#### note

The version number of FreeType if built as a dynamic link library with the ‘libtool’ package is not controlled by these three macros.