# :mod:pygame.freetype

--- Note that some features may change before a formal release

This module allows for rendering all face formats supported by FreeType, namely TTF, Type1, CFF, OpenType, SFNT, PCF, FNT, BDF, PFR and Type42 faces. It can render any UTF-32 character in a font file.

This module is optional, and replaces all of the functionality of the original 'font' module, whilst expanding it. This module depends in no way on the SDL_ttf library.

You should test that :mod:pygame.freetype is initialized before attempting to use the module; if the module is available and loaded, it will be automatically initialized by pygame.init()

Most of the work done with faces is done by using the actual Face objects. The module by itself only has routines to initialize itself and create Face objects with pygame.freetype.Face().

You can load faces from the system by using the pygame.freetype.SysFont() function. There are a few other functions to help lookup the system fonts.

For now undefined character codes are replaced with the undefined character. How undefined codes are handled may become configurable in a future release.

Pygame comes with a builtin default font. This can always be accessed by passing None as the font name to the Face constructor.

New in Pygame 1.9.2

'file' can be either a string representing the font's filename, a file-like object containing the font, or None; in this last case the default, built-in font will be used.

Optionally, a *ptsize* argument may be specified to set the default size in points which will be used to render the face. Such size can also be specified manually on each method call. Because of the way the caching system works, specifying a default size on the constructor doesn't imply a performance gain over manually passing the size on each function call.

If the font file has more than one face, the *index* argument may be specified to specify which face index to load. Defaults to 0; face loading will fail if the given index is not contained in the font.

The 'style' argument will set the default style (oblique, underline, strong) used to draw this face. This style may be overriden on any Face.render() call.

The optional vertical argument, an integer, sets the default orientation for the face: 0 (False) for horizontal, any other value (True) for vertical. See :attr:Face.vertical.

The optional ucs4 argument, an integer, sets the default text translation mode: 0 (False) recognize UTF-16 surrogate pairs, any other value (True), to treat unicode text as UCS-4, with no surrogate pairs. See :attr:Face.ucs4.

The optional resolution argument sets the pixel size, in dots per inch, to use for scaling glyphs for this Face instance. If 0 then the default module value, set by :meth:freetype.init, is used. The Face object's resolution can only be changed by reinitializing the instance.