pygame2.freetype – Wrapping module for the FreeType 2 font library

This module allows for rendering all font formats supported by FreeType, namely TTF, Type1, CFF, OpenType, SFNT, PCF, FNT, BDF, PFR and Type42 fonts.

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 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 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 lookup the system fonts.

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

Module Functions

pygame2.freetype.get_error() → string
Returns the description of the last error which occurred in the FreeType library, or None if no errors have occurred.
pygame2.freetype.get_version() -> (int, int, int)

Gets the version of the FreeType2 library which was used to build the ‘freetype’ module.

Note that the FreeType module depends on the FreeType 2 library, and will not compile with the original FreeType 1.0, hence the first element of the tuple will always be 2.

pygame2.freetype.init(default_cache_size=64) → None

Initializes the underlying FreeType 2 library.

This function must be called before trying to use any of the functionality of the ‘freetype’ module. It is safe to call this function more than once.

Optionally, you may specify a default size for the Glyph cache: this is the maximum amount of glyphs that will be cached at any given time by the module. Exceedingly small values will be automatically tuned for performance.

pygame2.freetype.quit() → None

Shuts down the underlying FreeType 2 library.

After calling this function, you should not invoke any class, method or function related to the ‘freetype’ module as they are likely to fail or might give unpredictable results. It is safe to call this function even if the module hasn’t been initialized yet.

pygame2.freetype.was_init() → bool
Returns whether the the FreeType 2 library is initialized.

Font

class pygame2.freetype.Font(file[, ptsize, style, index]) → Font

Creates a new Font from a supported font file.

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 font. 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; font loading will fail if the given index is not contained in the font.

The ‘style’ argument will set the default style (italic, underline, bold) used to draw this font. This style may be overriden on any Font.render() call.

Attributes

Font.name
Read only. Gets the name of the font face.
Font.height
Read only. Gets the height of the Font. This is the average value of all glyphs in the font.
Font.style

Gets or sets the default style of the Font. This default style will be used for all text rendering and size calculations unless overriden specifically in the render() or get_size() calls. The style value may be a bitwise OR of one or more of the following constants:

STYLE_NONE STYLE_UNDERLINE STYLE_ITALIC STYLE_BOLD

These constants may be found on the FreeType constants module. Optionally, the default style can be modified or obtained accessing the individual style attributes (underline, italic, bold).

Font.underline
Gets or sets whether the font will be underlined when drawing text. This default style value will be used for all text rendering and size calculations unless overriden specifically in the render() or get_size() calls, via the ‘style’ parameter.
Font.bold
Gets or sets whether the font will be bold when drawing text. This default style value will be used for all text rendering and size calculations unless overriden specifically in the render() or get_size() calls, via the ‘style’ parameter.
Font.italic
Gets or sets whether the font will be slanted when drawing text. This default style value will be used for all text rendering and size calculations unless overriden specifically in the render() or get_size() calls, via the ‘style’ parameter.
Font.fixed_width

Read only. Returns whether this Font is a fixed-width (bitmap) font.

Note

Note that scalable fonts whose glyphs are all the same width (i.e. monospace TTF fonts used for programming) are not considered fixed width.

Font.antialiased

Gets or sets the font’s antialiasing mode. This defaults to True on all fonts, which will be rendered by default antialiased.

Setting this to true will change all rendering methods to use glyph bitmaps without antialiasing, which supposes a small speed gain and a significant memory gain because of the way glyphs are cached.

Font.vertical

Gets or sets whether the font is a vertical font such as fonts representing Kanji glyphs or other styles of vertical writing.

Changing this attribute will cause the font to be rendering vertically, and affects all other methods which manage glyphs or text layouts to use vertical metrics accordingly.

Note that the FreeType library doesn’t automatically detect whether a font contains glyphs which are always supposed to be drawn vertically, so this attribute must be set manually by the user.

Also note that several font formats (specially bitmap based ones) don’t contain the necessary metrics to draw glyphs vertically, so drawing in those cases will give unspecified results.

Methods

Font.get_size(text[, style, rotation, ptsize]) → int, int

Gets the size in pixels which ‘text’ will occupy when rendered using this Font. The calculations will take into account the font’s default style (e.g. underlined fonts take extra height for the underline), or the style may be overriden by the ‘style’ parameter.

Returns a tuple containing the width and height of the text’s bounding box.

The calculations are done using the font’s default size in points, without any rotation, and taking into account fonts which are set to be drawn vertically via the Font.vertical attribute. Optionally you may specify another point size to use via the ‘ptsize’ argument, or a text rotation via the ‘rotation’ argument.

Font.get_metrics(text[, bbmode, ptsize]) → [(...), ...]

Returns the glyph metrics for each character in ‘text’.

The glyph metrics are returned inside a list; each character will be represented as a tuple inside the list with the following values:

(min_x, max_x, min_y, max_y, horizontal_advance)

By default, these values are returned as grid-fitted pixel coordinates (ints). Optionally, one of the following constants (which can be found on the FreeType constants module) may be passed as the bbmode argument:

BBOX_EXACT: Return accurate floating point values.

BBOX_EXACT_GRIDFIT: Return accurate floating point values aligned to the drawing grid.

BBOX_PIXEL: Return pixel coordinates (ints).

BBOX_PIXEL_GRIDFIT (default): Return grid-aligned pixel coordinates.

The calculations are done using the font’s default size in points. Optionally you may specify another point size to use.

Font.render(dest, text, fgcolor[, bgcolor, style, rotation, ptsize]) → int, int[, :class:`pygame2.sdl.video.Surface`]

Renders a text on a SDL surface.

Renders the string text to a pygame2.sdl.video.Surface, using the color fgcolor.

The dest parameter is supposed to be a tuple containing the surface and the coordinates at which the text will be rendered, in that order.

If such tuple exists, and the destination surface is a valid pygame2.sdl.video.Surface (independently of its bit depth), the text will be rendered directly on top of it at the passed coordinates, using the given fgcolor, and painting the background of the text with the given ‘bgcolor’, if available. The alpha values for both colors are always taken into account. The width and height of the rendered text will be returned in a tuple.

If ‘None’ is passed instead of the destination tuple, a new 32 bit pygame2.sdl.video.Surface will be created with the required size to contain the drawn text, and using bgcolor as its background color. If a background color is not available, the surface will be filled with zero alpha opacity. The width and height of the rendered text, together with the new pygame2.sdl.video.Surface, will be returned in a tuple.

The rendering is done using the font’s default size in points and its default style, without any rotation, and taking into account fonts which are set to be drawn vertically via the Font.vertical attribute.

Optionally you may specify another point size to use via the ‘ptsize’ argument, a text rotation via the ‘rotation’ argument, or a new text style via the ‘style’ argument.

This function is only available when PyGame 2 has been compiled with SDL support.

Font.render_raw(text[, ptsize]) → int, int, bytes

Renders a text to a byte buffer.

Renders the string text to a raw buffer of bytes, each byte representing the opacity of the glyph’s raster image in grayscale.

The width (pitch) and height of the rendered text, together with the bytes buffer, will be returned in a tuple.

The rendering is done using the font’s default size in points. Optionally you may specify another point size to use.