# 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',
        'ABCDEFGHIJ',
        'KLMNOPQRST',
        'UVWXYZ    ',
        'abcdefghij',
        'klmnopqrst',
        'uvwxyz    ',
        ',;.:!?+-()' ]

  `surface`

    The `sdl2.SDL_Surface` containing the character bitmaps.

  `offsets`

    A dict containing the character offsets on the `surface`.

  `mapping`

    The character mapping table, a list of strings.

  `size`

    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.

  `bg_color`

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

  `color`

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

  `default_font`

    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.

  `size`

    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`.

  `close`()

    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`.