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

Most of the work done with fonts is done by using the actual :class:`Font`
objects. The module by itself only has routines to initialize itself and
create :class:`Font` objects.


.. module:: pygame2.freetype
   :synopsis: Wrapping module for the FreeType 2 font library

Module Functions
----------------
.. function:: get_error() -> str

  Returns the description of the last error which occurred in the
  FreeType library, or None if no errors have occurred.



.. function:: 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.



.. function:: 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.



.. function:: 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.



.. function:: was_init() -> bool

  Returns whether the the FreeType 2 library is initialized.



Font
----
.. class:: 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 :meth:`render` call.


Attributes
^^^^^^^^^^
.. attribute:: Font.name

  Read only. Gets the name of the font face.

.. attribute:: Font.height

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

.. attribute:: Font.ptsize

  Gets or sets the default size of the Font in points.

.. attribute:: 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 :meth:`render()` or :meth:`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 in the
  :mod:`pygame2.freetype.constants` module.
  Optionally, the default style can be modified or obtained
  accessing the individual style attributes (underline, italic,
  bold).


.. attribute:: 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 :meth:`render()`
  or :meth:`get_size()` calls, via the *style* parameter.


.. attribute:: 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 :meth:`render()`
  or :meth:`get_size()` calls, via the *style* parameter.


.. attribute:: 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 :meth:`render()`
  or :meth:`get_size()` calls, via the *style* parameter.


.. attribute:: 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.


.. attribute:: 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.


.. attribute:: 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
^^^^^^^
.. method:: Font.copy() -> Font

  Creates a copy of the Font.


.. method:: 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 :attr:`vertical` attribute.
  Optionally you may specify another point size to use via the
  *ptsize* argument, or a text rotation via the 'rotation' argument.


.. method:: 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 bounding box constants
  of the :mod:`pygame2.freetype.constants` module  may be passed
  as the *bbmode* argument.

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


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

  Renders a text on a SDL surface.

  Renders the string *text* to a
  :class:`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
  :class:`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
  :class:`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 :class:`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 Pygame2 has been compiled
  with SDL support.


.. method:: 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.



