:mod:`pygame2.sdlext.font` -- Enhanced font rendering for SDL-based surfaces
============================================================================

Enhanced and specialised font rendering classes and functions for
SDL-based surfaces.


.. module:: pygame2.sdlext.font
   :synopsis: Enhanced font rendering for SDL-based surfaces

BitmapFont
----------
.. class:: BitmapFont (surface, size, mapping=None) -> BitmapFont

  Creates a BitmapFont suitable for bitmap to character mappings.

  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    ',
          ',;.:!?+-()' ]


Methods
^^^^^^^
.. method:: BitmapFont.can_render (text) -> bool

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


.. method:: BitmapFont.contains (c) -> bool

  Checks, whether a certain character exists in the font.


.. method:: BitmapFont.render_on (surface, text, offset=(0, 0)) -> Rect

  Renders a text on the passed surface, starting at offset.

  Renders a *text* on the existing *surface* . The top-left start
  position of the *text* will be the passed *offset* and a
  :class:`pygame2.Rect` with the changed area will be
  returned.


.. method:: BitmapFont.render (text) -> Surface

  Renders the passed *text* on a new
  :class:`pygame2.sdl.video.Surface` and returns it.



