Text rendering routines

class sdl2.ext.BitmapFont(surface : Sprite, size : iterable[, mapping=None)

A bitmap graphics to character mapping. The BitmapFont class uses an image surface to find and render font character glyphs for text. It requires a mapping table, which denotes the characters available on the image.

The mapping table is a list of strings, where each string reflects a line of characters on the image. Each character within each line has the same size as specified by the size argument.

A typical mapping table might look like

[ '0123456789',
  'UVWXYZ    ',
  'uvwxyz    ',
  ',;.:!?+-()' ]

The sdl2.SDL_Surface containing the character bitmaps.


A dict containing the character offsets on the surface.


The character mapping table, a list of strings.


The size of an individual glyph bitmap on the font.

render(text : string[, bpp=None]) → Sprite

Renders the passed text on a new Sprite and returns it. If no explicit bpp are provided, the bpp settings of the surface are used.

render_on(surface : Sprite, text : string[, offset=(0, 0)]) -> (int, int, int, int)

Renders a text on the passed sprite, starting at a specific offset. The top-left start position of the text will be the passed offset and a 4-value tuple with the changed area will be returned.

contains(c : string) → bool

Checks, whether a certain character exists in the font.

can_render(text : string) → bool

Checks, whether all characters in the passed text can be rendered.

class sdl2.ext.FontManager(font_path : str[, alias=None[, size=16[, color=Color(255, 255, 255)[, bg_color=Color(0, 0, 0)[, index=0]]]]])

Manage fonts and rendering of text.

One font path must be given to initialise the FontManager. default_font will be set to this font. size is the default font size in pixels. color and bg_color will give the FontManager a default color. index will select a specific font face from a file containing multiple font faces. The first face is always at index 0. It can be used for TTC (TrueType Font Collection) fonts.


The sdl2.ext.Color to be used as background color.


The sdl2.ext.Color to be used for rendering text.


Returns the name of the current default font being used by the FontManager. On assigning default_font, the value must be a loaded font alias.


The default font size in pixels.

add(font_path : str[, alias=None[, size=None[, index=0]]])) → sdl2.sdlttf.TTF_Font

Add a font to the FontManager. alias is by default the font name, any other name can be passed, size is the font size in pixels and defaults to size. index selects a specific font face from a TTC (TrueType Font Collection) file. Returns the font pointer stored in fonts.


Closes all fonts used by the FontManager.

render(text : str[, alias=None[, size=None[, width=None[, color=None[, bg_color=None[, **kwargs]]]]]]) → sdl2.SDL_Surface

Renders text to a surface. This method uses the font designated by the passed alias or, if alias is omitted, by the set default_font. A size can be passed even if the font was not loaded with this size. A width can be given for automatic line wrapping. If no bg_color or color are given, it will default to the FontManager’s bg_color and color.