Lenard Lindstrom avatar Lenard Lindstrom committed 46ed016

Finish freetype module doc page (towards Issue #75)

Fill in missing information and make the format consistent. Add lots of
cross-links. The doc page still needs a proof reading. Phrasing differs
among the various method and property descriptions. The terminalogy is
also somewhat loose.

Comments (0)

Files changed (4)

docs/reST/ref/examples.rst

 
    .. ## pygame.examples.fonty.main ##
 
+.. function:: freetype_misc.main
+
+   | :sl:`run a freetype rendering example`
+   | :sg:`freetype_misc.main() -> None`
+
+   A showcase of rendering features the :class:`pygame.freetype.Font`
+   class provides in addition to those available with :class:`pygame.font.Font`.
+   It is a demonstration of direct to surface rendering, with vertical text
+   and rotated text, opaque text and semi transparent text, horizontally
+   stretched text and vertically stretched text.
+
+   .. ## pygame.examples.fonty.main ##
+
 .. function:: vgrade.main
 
    | :sl:`display a vertical gradient`

docs/reST/ref/freetype.rst

 
 | :sl:`Enhanced Pygame module for loading and rendering computer fonts`
 
-The :mod:`pygame.freetype` module allows for the rendering of all font file formats
-supported by FreeType, namely ``TTF``, Type1, ``CFF``, OpenType, ``SFNT``, ``PCF``,
-``FNT``, ``BDF``, ``PFR`` and Type42 fonts. It can render any UTF-32 character in a
-font file.
+The :mod:`pygame.freetype` module is a replacement for :mod:`pygame.font`.
+It has all of the functionality of the original, plus many new features.
+Yet is has absolutely no dependencies on the SDL_ttf library.
+It is implemented directly on the FreeType 2 library.
+The :mod:`pygame.freetype` module is not itself backward compatible with
+:mod:`pygame.font`.
+Instead, use the :mod:`pygame.ftfont` module as a drop-in replacement
+for :mod:`pygame.font`.
 
-This module is a replacement for :mod:`pygame.font`. It has all of the functionality
-of the original, plus many new features. Yet is has absolutely no dependencies
-on the SDL_ttf library. The :mod:`pygame.freetype` module is not itself backward
-compatible with :mod:`pygame.font`. Instead, a new :mod:`pygame.ftfont` provides
-a drop-in replacement for :mod:`pygame.font`.
+All font file formats supported by FreeType can be rendered by
+:mod:`pygame.freetype`, namely ``TTF``, Type1, ``CFF``, OpenType,
+``SFNT``, ``PCF``, ``FNT``, ``BDF``, ``PFR`` and Type42 fonts.
+All glyphs having UTF-32 code points are accessible (see :attr:`ucs4`).
 
-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()``.
+Most work on fonts is done using :class:`Font` instances.
+The module itself only has routines for initialization and creation
+of :class:`Font` objects.
+You can load fonts from the system using the :func:`SysFont` function.
 
-You can load fonts from the system by using the ``pygame.freetype.SysFont()``
-function. There are a few other functions to help find system fonts.
+Extra support of bitmap fonts is available. Available bitmap sizes can
+be listed (see :meth:`Font.get_sizes`). For bitmap only fonts :class:`Font`
+can set the size for you
+(see the :ref:`Font class size argument <freetype-font-size-argument>`).
 
-For now undefined character codes are replaced with the ``undefined character``.
+For now undefined character codes are replaced with the ``.notdef``
+(not defined) character.
 How undefined codes are handled may become configurable in a future release.
 
 Pygame comes with a builtin default font. This can always be accessed by
-passing None as the font name to the Font constructor.
+passing None as the font name to the :class:`Font` constructor.
 
-New in Pygame 1.9.2
+Extra rendering features available to :class:`pygame.freetype.Font`
+are direct to surface rendering (see :meth:`Font.render_to`), character kerning
+(see :attr:`Font.kerning`), vertical layout (see :attr:`Font.vertical`),
+rotation of rendered text (see :attr:`rotation`), and the strong style
+(see :attr:`Font.strong`). Some properties are configurable, such as
+strong style strength (see :attr:`Font.strength`) and underline positioning
+(see :attr:`underline_adjustment`). Text can be positioned by the upper
+right corner of the text box or by the text baseline (see :attr:`Font.origin`).
+Finally, a font's vertical and horizontal size can be adjusted separately
+(see :attr:`Font.size`). The :mod:`pygame.examples.freetype` example
+(:func:`pygame.examples.freetype_misc.main`) shows these features in use.
+
+The Pygame package does not import :mod:`freetype` automatically when
+loaded. This module must be imported explicitly to be used. ::
+
+   import pygame
+   import pygame.freetype
+
+The :mod:`freetype` module is new in Pygame 1.9.2
+
 
 .. function:: get_error
 
-   | :sl:`Return the latest FreeType2 error`
+   | :sl:`Return the latest FreeType error`
    | :sg:`get_error() -> str`
 
    Return a description of the last error which occurred in the FreeType2
 
 .. function:: get_version
 
-   | :sl:`Return the FreeType 2 version`
+   | :sl:`Return the FreeType version`
    | :sg:`get_version() -> (int, int, int)`
 
-   Returns the version of the FreeType2 library which was used to build the
-   'freetype' module.
+   Returns the version of the FreeType library in use by this module.
 
-   Note that the freetype module depends on the FreeType 2 library. It will
-   not compile with the original FreeType 1.0. Hence, the first element of the
-   tuple will always be "2".
+   Note that the :mod:`freetype` module depends on the FreeType 2 library.
+   It will not compile with the original FreeType 1.0. Hence, the first element
+   of the tuple will always be "2".
 
 .. function:: init
 
-   | :sl:`Initialize the underlying FreeType 2 library.`
+   | :sl:`Initialize the underlying FreeType library.`
    | :sg:`init(cache_size=64, resolution=72)`
 
-   This function initializes the underlying FreeType 2 library and must be
-   called before trying to use any of the functionality of the 'freetype'
+   This function initializes the underlying FreeType library and must be
+   called before trying to use any of the functionality of the :mod:`freetype`
    module.
 
-   However, this function will be automatically called by ``pygame.init()``.
-   It is safe to call this function more than once.
+   However, :meth:`pygame.init()` will automatically call this function
+   if the :mod:`freetype` module is already imported. It is safe to call this
+   function more than once.
 
-   Optionally, you may specify a default size for the Glyph cache: this is the
+   Optionally, you may specify a default *cache_size* for the Glyph cache: the
    maximum number of glyphs that will be cached at any given time by the
    module. Exceedingly small values will be automatically tuned for
-   performance. Also a default pixel resolution, in dots per inch, can
+   performance. Also a default pixel *resolution*, in dots per inch, can
    be given to adjust font scaling.
 
 .. function:: quit
 
-   | :sl:`Shut down the underlying FreeType 2 library.`
+   | :sl:`Shut down the underlying FreeType library.`
    | :sg:`quit()`
 
-   This function de-initializes the ``freetype`` module. After calling this
+   This function closes the ``freetype`` module. 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
 
 .. function:: was_init
 
-   | :sl:`Return whether the the FreeType 2 library is initialized.`
+   | :sl:`Return whether the the FreeType library is initialized.`
    | :sg:`was_init() -> bool`
 
-   Returns whether the the FreeType 2 library is initialized.
+   Returns whether the the FreeType library is initialized.
 
 .. function:: get_default_resolution
 
    | :sl:`Return the default pixel size in dots per inch`
    | :sg:`get_default_resolution() -> long`
 
-   Returns the default pixel size, in dots per inch for the module. If not changed
-   it will be 72.
+   Returns the default pixel size, in dots per inch, for the module.
+   The default is 72dpi.
 
 .. function:: set_default_resolution
 
    | :sg:`set_default_resolution([resolution])`
 
    Set the default pixel size, in dots per inch, for the module. If the
-   optional argument is omitted or zero the resolution is reset to 72.
+   optional argument is omitted or zero the resolution is reset to 72dpi.
+
+.. function:: SysFont
+
+   | :sl:`create a Font object from the system fonts`
+   | :sg:`SysFont(name, size, bold=False, italic=False) -> Font`
+
+   Return a new Font object that is loaded from the system fonts. The font will
+   match the requested *bold* and *italic* flags. If a suitable system font
+   is not found the default, Pygame, is returned instead. The font *name*
+   can be a comma separated list of font names to search for.
 
 .. function:: get_default_font
 
    | :sl:`Get the filename of the default font`
    | :sg:`get_default_font() -> string`
 
-   Return the filename of the system font. This is not the full path to the
-   file. This file can usually be found in the same directory as the font
-   module, but it can also be bundled in separate archives.
+   Return the filename of the default Pygame font. This is not the full path
+   to the file. The file is usually in the same directory as the font module,
+   but can also be bundled in a separate archive.
 
 .. class:: Font
 
    | :sg:`Font(file, size=0, font_index=0, resolution=0, ucs4=False) -> Font`
 
    Argument *file* can be either a string representing the font's filename, a
-   file-like object containing the font, or None; if None, the default, built-in font
-   is used.
+   file-like object containing the font, or None; if None, the default,
+   Pygame, font is used.
+
+   .. _freetype-font-size-argument:
 
    Optionally, a *size* argument may be specified to set the default size in
-   points, which will be used when rendering the font. The size can also be
-   passed explicitly to 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 is bitmap and no *size* is given, the default size is set
-   to the first available size for the font, if possible.
+   points, which determines the size of the rendered characters.
+   The size can also be passed explicitly to 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 is bitmap and no *size*
+   is given, the default size is set to the first available size for the font.
 
    If the font file has more than one font, the font to load can be chosen with
    the *index* argument. An exception is raised for an out-of-range font index
    value.
 
-   The optional resolution argument sets the pixel size, in dots per inch,
+   The optional *resolution* argument sets the pixel size, in dots per inch,
    for use in scaling glyphs for this Font instance. If 0 then the default
    module value, set by :meth:`freetype.init`, is used. The Font object's
-   resolution can only be changed by reinitializing the Font instance.
+   resolution can only be changed by re-initializing the Font instance.
 
-   The optional ucs4 argument, an integer, sets the default text translation
+   The optional *ucs4* argument, an integer, sets the default text translation
    mode: 0 (False) recognize UTF-16 surrogate pairs, any other value (True),
    to treat Unicode text as UCS-4, with no surrogate pairs. See
    :attr:`Font.ucs4`.
       | :sl:`Return the size and offset of rendered text`
       | :sg:`get_rect(text, style=STYLE_DEFAULT, rotation=0, size=0) -> rect`
 
-      Gets the final dimensions and origin, in pixels, of 'text' using the
-      current point size, style, rotation and orientation. These are either
-      taken from the arguments, if given, else from the default values set
-      for the font object.
+      Gets the final dimensions and origin, in pixels, of *text* using the
+      optional *size* in points, *style*, and *rotation*. For other
+      relevant render properties, and for any optional argument not given,
+      the default values set for the :class:`Font` instance are used.
 
-      Returns a rect containing the width and height of the text's bounding
-      box and the position of the text's origin. The origin can be used
-      to align separately rendered pieces of text. It gives the baseline
-      position and bearing at the start of the text.
+      Returns a :class:`Rect` instance containing the width and height
+      of the text's bounding box and the position of the text's origin.
+      The origin is useful in aligning separately rendered pieces of text.
+      It gives the baseline position and bearing at the start of the text.
+      See the :meth:`render_to` method for an example.
 
-      If text is a char (byte) string, then its encoding is assumed to be
+      If *text* is a char (byte) string, its encoding is assumed to be
       ``LATIN1``.
 
-      Optionally, text can be :const:`None`, which will return the bounding
+      Optionally, *text* can be :const:`None`, which will return the bounding
       rectangle for the text passed to a previous :meth:`get_rect`,
       :meth:`render`, :meth:`render_to`, :meth:`render_raw`, or
       :meth:`render_raw_to` call. See :meth:`render_to` for more
       | :sl:`Return the glyph metrics for the given text`
       | :sg:`get_metrics(text, size=0) -> [(...), ...]`
 
-      Returns the glyph metrics for each character in 'text'.
+      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:
+      The glyph metrics are returned as a list of tuples. Each tuple gives
+      metrics of a single character glyph. The glyph metrics are:
 
       ::
 
       float values.
 
       The calculations are done using the font's default size in points.
-      Optionally you may specify another point size to use.
+      Optionally you may specify another point size with the *size* argument.
 
       The metrics are adjusted for the current rotation, strong, and oblique
       settings.
       | :sl:`The scaled height of the font in pixels`
       | :sg:`get_sized_height(<size>=0) -> int`
 
-      Read only. Gets the height of the font. This is the average value of all
+      Returns the height of the font. This is the average value of all
       glyphs in the font. It is not adjusted for strong or rotation.
 
    .. method:: get_sized_glyph_height
       | :sg:`get_sizes() -> [(int, int, int, float, float), ...]`
       | :sg:`get_sizes() -> []`
 
-      This returns a list of tuple records, one for each point size
+      Returns a list of tuple records, one for each point size
       supported. Each tuple containing the point size, the height in pixels,
       width in pixels, horizontal ppem (nominal width) in fractional pixels,
       and vertical ppem (nominal height) in fractional pixels.
       | :sl:`Return rendered text as a surface`
       | :sg:`render(text, fgcolor=None, bgcolor=None, style=STYLE_DEFAULT, rotation=0, size=0) -> (Surface, Rect)`
 
-      Returns a new :mod:`pygame.Surface`, with the text rendered to it
+      Returns a new :mod:`Surface`, with the text rendered to it
       in the color given by 'fgcolor'. If no foreground color is given,
       the default foreground color, :attr:`fgcolor` is used.
       If ``bgcolor`` is given, the surface
-      will be filled with this color. If no background color is given,
-      the surface is filled with zero alpha opacity. Normally the returned
+      will be filled with this color. When no background color is given,
+      the surface background is transparent, zero alpha. Normally the returned
       surface has a 32 bit pixel size. However, if ``bgcolor`` is :const:`None`
-      and anti-aliasing is disabled a two color 8 bit surface with colorkey
-      set for the background color is returned.
+      and anti-aliasing is disabled a monochrome 8 bit colorkey surface,
+      with colorkey set for the background color, is returned.
 
       The return value is a tuple: the new surface and the bounding
       rectangle giving the size and origin of the rendered text.
 
       If an empty string is passed for text then the returned Rect is zero
-      width and the height of the font. If dest is :const:`None` the returned
-      surface is the same dimensions as the boundary rect.
-      The rect will test False.
+      width and the height of the font.
 
-      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 :attr:`vertical` attribute.
-      Optionally you may specify another point size to use via the 'size'
-      argument, a text rotation via the 'rotation' argument, or a new text
-      style via the 'style' argument. See the attr :attr:`size`,
-      :attr:`rotation`, and :attr:`style` attributes.
+      Optional *fgcolor*, *style*, *rotation*, and *size* arguments override
+      the default values set for the :class:`Font` instance.
 
-      If text is a char (byte) string, then its encoding is assumed to be
+      If *text* is a char (byte) string, then its encoding is assumed to be
       ``LATIN1``.
 
-      Optionally, text can be None, which will return the bounding
-      rectangle for the text passed to a previous :meth:`get_rect`,
-      :meth:`render`, :meth:`render_to`, :meth:`render_raw`, or
-      :meth:`render_raw_to` call. See :meth:`render_to` for more
-      details.
+      Optionally, *text* can be :const:`None`, which will render the text
+      passed to a previous :meth:`get_rect`, :meth:`render`, :meth:`render_to`,
+      :meth:`render_raw`, or :meth:`render_raw_to` call.
+      See :meth:`render_to` for details.
 
    .. method:: render_to
 
       | :sl:`Render text onto an existing surface`
       | :sg:`render_to(surf, dest, text, fgcolor=None, bgcolor=None, style=STYLE_DEFAULT, rotation=0, size=0) -> Rect`
 
-      Renders the string 'text' to a :mod:`pygame.Surface` 'surf',
-      using the color 'fgcolor', if given, or the default foreground
-      color, :attr:`fgcolor`, otherwise.
+      Renders the string *text* to the :mod:`pygame.Surface` *surf*,
+      at position *dest*, a (x, y) surface coordinate pair.
+      If either x or y is not an integer it is converted to one if possible.
+      Any sequence where the first two items are x and y positional elements
+      is accepted, including a :class:`Rect` instance.  As with :meth:`render`,
+      optional *fgcolor*, *style*, *rotation*, and *size* argument are
+      available.
 
-      Argument 'dest' is an (x, y) surface coordinate pair. If either x
-      or y is not an integer it is converted to one if possible.
-      Any sequence, including :class:`Rect`, for which the first
-      two elements are positions x and y is accepted.
-
-      If a background color is given, the surface is first filled with that
-      color. The text is blitted next. Both the background fill and text
-      rendering involve full alpha blits. That is, the alpha values of
-      both the foreground and background colors, as well as those of the
-      destination surface if it has per-pixel alpha.
+      If a background color *bgcolor* is given, the text bounding box is
+      first filled with that color. The text is blitted next.
+      Both the background fill and text rendering involve full alpha blits.
+      That is, the alpha values of the foreground, background, and destination
+      target surface all affect the blit.
 
       The return value is a rectangle giving the size and position of the
       rendered text within the surface.
       If an empty string is passed for text then the returned :class:`Rect`
       is zero width and the height of the font. The rect will test False.
 
-      Optionally, text can be set :const:`None`, which will re-render text
+      Optionally, *text* can be set :const:`None`, which will re-render text
       passed to a previous :meth:`render_to`, :meth:`get_rect`, :meth:`render`,
       :meth:`render_raw`, or :meth:`render_raw_to` call. Primarily, this
       feature is an aid to using :meth:`render_to` in combination with
       with a text string or one of the above properties has changed
       after the :meth:`get_rect` call.
 
-      By default, the point size and style set for the font are used
-      if not passed as arguments. The text is unrotated unless a non-zero
-      rotation value is given.
-
-      If text is a char (byte) string, then its encoding is assumed to be
+      If *text* is a char (byte) string, then its encoding is assumed to be
       ``LATIN1``.
 
    .. method:: render_raw
       | :sl:`Return rendered text as a string of bytes`
       | :sg:`render_raw(text, style=STYLE_DEFAULT, rotation=0, size=0, invert=False) -> (bytes, (int, int))`
 
-      Like :meth:`render` but the tuple returned is an 8 bit
-      monochrome string of bytes and its size. The foreground color is 255, the
+      Like :meth:`render` but with the pixels returned as a byte string
+      of 8-bit gray-scale values. The foreground color is 255, the
       background 0, useful as an alpha mask for a foreground pattern.
 
    .. method:: render_raw_to
       | :sg:`render_raw_to(array, text, dest=None, style=STYLE_DEFAULT, rotation=0, size=0, invert=False) -> (int, int)`
 
       Render to an array object exposing an array struct interface. The array
-      must be two dimensional with integer items. The default dest value, None,
-      is equivalent to (0, 0). See :meth:`render_to`.
+      must be two dimensional with integer items. The default *dest* value,
+      :const:`None`, is equivalent to position (0, 0). See :meth:`render_to`.
+      As with the other render methods, *text* can be :const:`None` to
+      render a text string passed previously to another method.
 
    .. attribute:: style
 
 
       Gets or sets the default style of the Font. This default style will be
       used for all text rendering and size calculations unless overridden
-      specifically in the \`render()` or \`get_size()` calls. The style value
-      may be a bit-wise ``OR`` of one or more of the following constants:
+      specifically in the :meth:`render` or :meth:`get_size` calls.
+      The style value may be a bit-wise OR of one or more of the following
+      constants:
 
       ::
 
       Optionally, the default style can be modified or obtained accessing the
       individual style attributes (underline, oblique, strong).
 
-      The ``STYLE_OBLIQUE`` and ``STYLE_STRONG`` styles are for scalable fonts
-      only. An attempt to set either for a bitmap font raises an AttributeError.
-      An attempt to set either for an inactive font, as returned by
-      ``Font.__new__()``, raises a RuntimeError.
+      The :const:`STYLE_OBLIQUE` and :const:`STYLE_STRONG` styles are for
+      scalable fonts only. An attempt to set either for a bitmap font raises
+      an AttributeError. An attempt to set either for an inactive font,
+      as returned by :meth:`Font.__new__`, raises a RuntimeError.
 
    .. attribute:: 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 overridden specifically in the \`render()` or
-      \`get_size()` calls, via the 'style' parameter.
+      calculations unless overridden specifically in the :meth:`render` or
+      :meth:`get_size` calls, via the 'style' parameter.
 
    .. attribute:: strong
 
 
       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 overridden specifically in the \`render()` or
-      \`get_size()` calls, via the 'style' parameter.
+      calculations unless overridden specifically in the :meth:`render` or
+      :meth:`get_size` calls, via the 'style' parameter.
 
    .. attribute:: oblique
 
 
       Gets or sets whether the font will be rendered as oblique. This
       default style value will be used for all text rendering and size
-      calculations unless overridden specifically in the \`render()` or
-      \`get_size()` calls, via the 'style' parameter.
+      calculations unless overridden specifically in the :meth:`render` or
+      :meth:`get_size` calls, via the *style* parameter.
 
       The oblique style is only supported for scalable (outline) fonts.
-      An attempt to set this property will raise an AttributeError.
-      If the font object is inactive, as returned by Font.__new__,
-      setting this property raises a RuntimeError.
+      An attempt to set this style on a bitmap font will raise an
+      AttributeError. If the font object is inactive, as returned by
+      :meth:`Font.__new__`, setting this property raises a RuntimeError.
 
    .. attribute:: wide
 
       | :sg:`wide -> bool`
 
       Gets or sets whether the font will be stretched horizontally
-      when drawing text. It produces a result similar to font.Font's
-      bold. This style is only available for unrotated text.
+      when drawing text. It produces a result similar to
+      :class:`pygame.font.Font`'s bold. This style not available for
+      rotated text.
 
    .. attribute:: strength
 
       strong or wide transformations, as a fraction of the untransformed
       size. For the wide style only the horizontal dimension is
       increased. For strong text both the horizontal and vertical
-      dimensions are enlarged. A wide style of strength 1/12 is
-      equivalent to the font.Font bold style. The default is 1/36.
+      dimensions are enlarged. A wide style of strength 0.08333 ( 1/12 ) is
+      equivalent to the :class:`pygame.font.Font` bold style.
+      The default is 0.02778 ( 1/36 ).
 
       The strength style is only supported for scalable (outline) fonts.
-      An attempt to set this property will raise an AttributeError.
-      If the font object is inactive, as returned by Font.__new__,
-      setting this property raises a RuntimeError.
+      An attempt to set this property on a bitmap font will raise an
+      AttributeError. If the font object is inactive, as returned by
+      :meth:`Font.__new__`, assignment to this property raises a RuntimeError.
 
    .. attribute:: underline_adjustment
 
       Gets or sets a factor which, when positive, is multiplied with the
       font's underline offset to adjust the underline position. A negative
       value turns an underline into a strike-through or overline. It is
-      multiplied with the ascender. Accepted values are between -2.0 and 2.0
+      multiplied with the ascender. Accepted values range between -2.0 and 2.0
       inclusive. A value of 0.5 closely matches Tango underlining. A value of
-      1.0 mimics SDL_ttf.
+      1.0 mimics :class:`pygame.font.Font` underlining.
 
    .. attribute:: fixed_width
 
       | :sl:`Gets whether the font is fixed-width`
       | :sg:`fixed_width -> bool`
 
-      Read only. Return True if the font contains fixed-width characters
-      (for example Courier, Bitstream Vera Sans Mono, Andale Mono).
+      Read only. Returns :const:`True` if the font contains fixed-width
+      characters (for example Courier, Bitstream Vera Sans Mono, Andale Mono).
 
    .. attribute:: fixed_sizes
 
-      | :sl:`the number of embedded bitmap sizes the font`
+      | :sl:`the number of available bitmap sizes for the font`
       | :sg:`fixed_sizes -> int`
 
-      Read only. Return the number of point sizes for which the font contains
+      Read only. Returns the number of point sizes for which the font contains
       bitmap character images. If zero then the font is not a bitmap font. 
-      A scalable font may contain pre-rendered point sizes.
+      A scalable font may contain pre-rendered point sizes as strikes.
 
    .. attribute:: scalable
 
       | :sl:`Gets whether the font is scalable`
       | :sg:`scalable -> bool`
 
-      Read only. Return True if the font contains outline glyphs. If so,
-      the point size is not limited to available bitmap sizes.
+      Read only. Returns :const:`True` if the font contains outline glyphs.
+      If so, the point size is not limited to available bitmap sizes.
 
    .. attribute:: use_bitmap_strikes
 
-      | :sl:`allow the use of embeddeded bitmaps in an outline font file`
+      | :sl:`allow the use of embedded bitmaps in an outline font file`
       | :sg:`use_bitmap_strikes -> bool`
 
-      Some scalable fonts contain embedded bitmaps for particular point
+      Some scalable fonts include embedded bitmaps for particular point
       sizes. This property controls whether or not those bitmap strikes
-      are used. Setting ``False`` disables the loading of any bitmap strike.
-      Setting ``True``, the default value, allows bitmap strikes for an
-      unrotated render when no style other than :attr:`wide` or
-      :attr:`underline` is set. This property has no effect on bitmap fonts.
+      are used. Set it :const:`False` to disable the loading of any bitmap
+      strike. Set it :const:`True`, the default, to permit bitmap strikes
+      for a nonrotated render with no style other than :attr:`wide` or
+      :attr:`underline`. This property is ignored for bitmap fonts.
 
       See also :attr:`fixed_sizes` and :meth:`get_sizes`.
 
       | :sl:`Font anti-aliasing mode`
       | :sg:`antialiased -> bool`
 
-      Gets or sets the font's anti-aliasing mode. This defaults to ``True`` on
-      all fonts, which are rendered with full 8 bit blending.
+      Gets or sets the font's anti-aliasing mode. This defaults to
+      :const:`True` on all fonts, which are rendered with full 8 bit blending.
 
-      Setting this to ``False`` will enable monochrome rendering. This should
+      Set to :const:`False` to do monochrome rendering. This should
       provide a small speed gain and reduce cache memory size.
 
    .. attribute:: kerning
       | :sl:`Character kerning mode`
       | :sg:`kerning -> bool`
 
-      Gets or sets the font's kerning mode. This defaults to False on all
-      fonts, which will be rendered by default without kerning.
+      Gets or sets the font's kerning mode. This defaults to :const:`False`
+      on all fonts, which will be rendered without kerning.
 
-      Setting this to true will change all rendering methods to do kerning
-      between character pairs for surface size calculation and all
-      render operations.
+      Set to :const:`True` to add kerning between character pairs, if supported
+      by the font, when positioning glyphs.
 
    .. attribute:: vertical
 
       | :sl:`Font vertical mode`
       | :sg:`vertical -> bool`
 
-      Gets or sets whether the font is a vertical font such as fonts in fonts
-      representing Kanji glyphs or other styles of vertical writing.
+      Gets or sets whether the characters are laid out vertically rather
+      than horizontally. May be useful when rendering Kanji or some other
+      vertical script.
 
-      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.
+      Set to :const:`True` to switch to a vertical text layout. The default
+      is :const:`False`, place horizontally.
 
-      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.
+      Note that the :class:`Font` class does not automatically determine
+      script orientation. Vertical layout must be selected explicitly.
 
       Also note that several font formats (especially bitmap based ones) don't
       contain the necessary metrics to draw glyphs vertically, so drawing in
       | :sl:`text rotation in degrees counterclockwise`
       | :sg:`rotation -> int`
 
-      Get or set the baseline angle of the rendered text. The angle is
+      Gets or sets the baseline angle of the rendered text. The angle is
       represented as integer degrees. The default angle is 0, with horizontal
-      text rendered along the X axis, and vertical text along the Y axis.
-      A non-zero value rotates these axes counterclockwise that many degrees.
-      Degree values outside of the range 0 to 359 inclusive are reduced to the
-      corresponding angle within the range (eg. 390 -> 390 - 360 -> 30,
-      -45 -> 360 + -45 -> 315, 720 -> 720 - (2 * 360) -> 0).
+      text rendered along the X-axis, and vertical text along the Y-axis.
+      A positive value rotates these axes counterclockwise that many degrees.
+      A negative angle corresponds to a clockwise rotation. The rotation
+      value is normalized to a value within the range 0 to 359 inclusive
+      (eg. 390 -> 390 - 360 -> 30, -45 -> 360 + -45 -> 315,
+      720 -> 720 - (2 * 360) -> 0).
 
-      Text rotation is only supported for scalable (outline) fonts. An attempt
-      to change the rotation of a bitmap font raises an AttributeError.
-      An attempt to change the rotation of an inactive font objects, as
-      returned by Font.__new__(), raises a RuntimeError.
+      Only scalable (outline) fonts can be rotated. An attempt to change
+      the rotation of a bitmap font raises an AttributeError.
+      An attempt to change the rotation of an inactive font instance, as
+      returned by :meth:`Font.__new__`, raises a RuntimeError.
 
    .. attribute:: fgcolor
 
       | :sl:`default foreground color`
       | :sg:`fgcolor -> Color`
 
-      Get or set the default glyph rendering color. It is initially opaque
+      Gets or sets the default glyph rendering color. It is initially opaque
       black ― (0, 0, 0, 255). Applies to :meth:`render` and :meth:`render_to`.
 
    .. attribute:: origin
       | :sl:`Font render to text origin mode`
       | :sg:`origin -> bool`
 
-      If set True, then when rendering to an existing surface, the position
-      is taken to be that of the text origin. Otherwise the render position is
-      the top-left corner of the text bounding box.
+      If set :const:`True`, :meth:`render_to` and :meth:`render_to_raw` will
+      take the *dest* position to be that of the text origin, as opposed to
+      the top-left corner of the bounding box. See :meth:`get_rect` for
+      details.
 
    .. attribute:: pad
 
       | :sl:`padded boundary mode`
       | :sg:`pad -> bool`
 
-      If set True, then the text boundary rectangle will be inflated to match
-      that of font.Font. Otherwise, the boundary rectangle is just large
-      enough for the text.
+      If set :const:`True`, then the text boundary rectangle will be inflated
+      to match that of :class:`font.Font`. Otherwise, the boundary rectangle
+      is just large enough for the text.
 
    .. attribute:: ucs4
 
       interpreters built with a UCS-2 unicode type (on Windows, for instance).
       It also means character values within the UTF-16 surrogate area (0xD800
       to 0xDFFF) are considered part of a surrogate pair. A malformed surrogate
-      pair will raise an UnicodeEncodeError. Setting ucs4 True turns surrogate
-      pair decoding off, letting interpreters with a UCS-4 unicode type access
-      the full UCS-4 character range.
+      pair will raise a UnicodeEncodeError. Setting ucs4 :const:`True` turns
+      surrogate pair decoding off, allowing access the full UCS-4 character
+      range to a Python interpreter built with four byte unicode character
+      support.
 
    .. attribute:: resolution
 
       | :sl:`Pixel resolution in dots per inch`
       | :sg:`resolution -> int`
 
-      Gets the pixel size used in scaling font glyphs for this Font instance.
+      Read only. Gets pixel size used in scaling font glyphs for this
+      :class:`Font` instance.

src/doc/examples_doc.h

 
 #define DOC_PYGAMEEXAMPLESFONTYMAIN "fonty.main() -> None\nrun a font rendering example"
 
+#define DOC_PYGAMEEXAMPLESFREETYPEMISCMAIN "freetype_misc.main() -> None\nrun a freetype rendering example"
+
 #define DOC_PYGAMEEXAMPLESVGRADEMAIN "vgrade.main() -> None\ndisplay a vertical gradient"
 
 #define DOC_PYGAMEEXAMPLESEVENTLISTMAIN "eventlist.main() -> None\ndisplay pygame events"
  fonty.main() -> None
 run a font rendering example
 
+pygame.examples.freetype_misc.main
+ freetype_misc.main() -> None
+run a freetype rendering example
+
 pygame.examples.vgrade.main
  vgrade.main() -> None
 display a vertical gradient

src/doc/freetype_doc.h

 /* Auto generated file: with makeref.py .  Docs go in src/ *.doc . */
 #define DOC_PYGAMEFREETYPE "Enhanced Pygame module for loading and rendering computer fonts"
 
-#define DOC_PYGAMEFREETYPEGETERROR "get_error() -> str\nReturn the latest FreeType2 error"
+#define DOC_PYGAMEFREETYPEGETERROR "get_error() -> str\nReturn the latest FreeType error"
 
-#define DOC_PYGAMEFREETYPEGETVERSION "get_version() -> (int, int, int)\nReturn the FreeType 2 version"
+#define DOC_PYGAMEFREETYPEGETVERSION "get_version() -> (int, int, int)\nReturn the FreeType version"
 
-#define DOC_PYGAMEFREETYPEINIT "init(cache_size=64, resolution=72)\nInitialize the underlying FreeType 2 library."
+#define DOC_PYGAMEFREETYPEINIT "init(cache_size=64, resolution=72)\nInitialize the underlying FreeType library."
 
-#define DOC_PYGAMEFREETYPEQUIT "quit()\nShut down the underlying FreeType 2 library."
+#define DOC_PYGAMEFREETYPEQUIT "quit()\nShut down the underlying FreeType library."
 
-#define DOC_PYGAMEFREETYPEWASINIT "was_init() -> bool\nReturn whether the the FreeType 2 library is initialized."
+#define DOC_PYGAMEFREETYPEWASINIT "was_init() -> bool\nReturn whether the the FreeType library is initialized."
 
 #define DOC_PYGAMEFREETYPEGETDEFAULTRESOLUTION "get_default_resolution() -> long\nReturn the default pixel size in dots per inch"
 
 #define DOC_PYGAMEFREETYPESETDEFAULTRESOLUTION "set_default_resolution([resolution])\nSet the default pixel size in dots per inch for the module"
 
+#define DOC_PYGAMEFREETYPESYSFONT "SysFont(name, size, bold=False, italic=False) -> Font\ncreate a Font object from the system fonts"
+
 #define DOC_PYGAMEFREETYPEGETDEFAULTFONT "get_default_font() -> string\nGet the filename of the default font"
 
 #define DOC_PYGAMEFREETYPEFONT "Font(file, size=0, font_index=0, resolution=0, ucs4=False) -> Font\nCreate a new Font instance from a supported font file."
 
 #define DOC_FONTFIXEDWIDTH "fixed_width -> bool\nGets whether the font is fixed-width"
 
-#define DOC_FONTFIXEDSIZES "fixed_sizes -> int\nthe number of embedded bitmap sizes the font"
+#define DOC_FONTFIXEDSIZES "fixed_sizes -> int\nthe number of available bitmap sizes for the font"
 
 #define DOC_FONTSCALABLE "scalable -> bool\nGets whether the font is scalable"
 
-#define DOC_FONTUSEBITMAPSTRIKES "use_bitmap_strikes -> bool\nallow the use of embeddeded bitmaps in an outline font file"
+#define DOC_FONTUSEBITMAPSTRIKES "use_bitmap_strikes -> bool\nallow the use of embedded bitmaps in an outline font file"
 
 #define DOC_FONTANTIALIASED "antialiased -> bool\nFont anti-aliasing mode"
 
 
 pygame.freetype.get_error
  get_error() -> str
-Return the latest FreeType2 error
+Return the latest FreeType error
 
 pygame.freetype.get_version
  get_version() -> (int, int, int)
-Return the FreeType 2 version
+Return the FreeType version
 
 pygame.freetype.init
  init(cache_size=64, resolution=72)
-Initialize the underlying FreeType 2 library.
+Initialize the underlying FreeType library.
 
 pygame.freetype.quit
  quit()
-Shut down the underlying FreeType 2 library.
+Shut down the underlying FreeType library.
 
 pygame.freetype.was_init
  was_init() -> bool
-Return whether the the FreeType 2 library is initialized.
+Return whether the the FreeType library is initialized.
 
 pygame.freetype.get_default_resolution
  get_default_resolution() -> long
  set_default_resolution([resolution])
 Set the default pixel size in dots per inch for the module
 
+pygame.freetype.SysFont
+ SysFont(name, size, bold=False, italic=False) -> Font
+create a Font object from the system fonts
+
 pygame.freetype.get_default_font
  get_default_font() -> string
 Get the filename of the default font
 
 pygame.freetype.Font.fixed_sizes
  fixed_sizes -> int
-the number of embedded bitmap sizes the font
+the number of available bitmap sizes for the font
 
 pygame.freetype.Font.scalable
  scalable -> bool
 
 pygame.freetype.Font.use_bitmap_strikes
  use_bitmap_strikes -> bool
-allow the use of embeddeded bitmaps in an outline font file
+allow the use of embedded bitmaps in an outline font file
 
 pygame.freetype.Font.antialiased
  antialiased -> bool
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.