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  13
#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.

---