pygame / docs / reST / ref / freetype.rst

Full commit


The :mod:`pygame.freetype` module allows for the rendering of all font file formats supported by FreeType, namely TTF, Type1, CFF, OpenType, SFNT, PCF, FNT, BDF, PFR and Type42 fonts. It can render any UTF-32 character in a font file.

This module is a replacement for :mod:`pygame.font`. It has all of the functionality of the original, plus many new features. Yet is has absolutely no dependencies on the SDL_ttf library. The :mod:`pygame.freetype` module is not itself backward compatible with :mod:`pygame.font`. Instead, a new :mod:`pygame.ftfont` provides a drop-in replacement for :mod:`pygame.font`.

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

You can load fonts from the system by using the pygame.freetype.SysFont() function. There are a few other functions to help find 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 Font constructor.

New in Pygame 1.9.2

Argument file can be either a string representing the font's filename, a file-like object containing the font, or None; if None, the default, built-in font is used.

Optionally, a ptsize argument may be specified to set the default size in points, which will be used when rendering the font. The size can also be passed explicitly to 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 font, the font to load can be chosen with the index argument. An exception is raised for an out-of-range font index value.

The style argument will set the default style (oblique, underline, strong) used to draw this font. This style may be overridden on any :meth:`Font.render` call.

The optional vertical argument, an integer, sets the default orientation for the font: 0 (False) for horizontal, any other value (True) for vertical. See :attr:`Font.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:`Font.ucs4`.

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