Commits

Lenard Lindstrom  committed ccfa4a8

freetype

  • Participants
  • Parent commits 81ca25b

Comments (0)

Files changed (1)

 # Parent 3299e2cc3c4c18e182eb8259b2b7620c1e4e6f5a
 Finish freetype module doc page
 
-diff -r 3299e2cc3c4c -r 247a0a153db2 docs/reST/ref/examples.rst
+diff -r 3299e2cc3c4c docs/reST/ref/examples.rst
 --- a/docs/reST/ref/examples.rst	Tue Nov 05 13:29:18 2013 -0800
-+++ b/docs/reST/ref/examples.rst	Wed Nov 06 12:59:09 2013 -0800
++++ b/docs/reST/ref/examples.rst	Wed Nov 06 18:22:06 2013 -0800
 @@ -129,6 +129,19 @@
  
     .. ## pygame.examples.fonty.main ##
  .. function:: vgrade.main
  
     | :sl:`display a vertical gradient`
-diff -r 3299e2cc3c4c -r 247a0a153db2 docs/reST/ref/freetype.rst
+diff -r 3299e2cc3c4c docs/reST/ref/freetype.rst
 --- a/docs/reST/ref/freetype.rst	Tue Nov 05 13:29:18 2013 -0800
-+++ b/docs/reST/ref/freetype.rst	Wed Nov 06 12:59:09 2013 -0800
-@@ -8,35 +8,55 @@
++++ b/docs/reST/ref/freetype.rst	Wed Nov 06 18:22:06 2013 -0800
+@@ -8,35 +8,61 @@
  
  | :sl:`Enhanced Pygame module for loading and rendering computer fonts`
  
  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`),
 +Finally, a font's vertical and horizontal size can be adjested 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
++
  
- New in Pygame 1.9.2
- 
-+
  .. function:: get_error
  
 -   | :sl:`Return the latest FreeType2 error`
     | :sg:`get_error() -> str`
  
     Return a description of the last error which occurred in the FreeType2
-@@ -44,7 +64,7 @@
+@@ -44,37 +70,37 @@
  
  .. function:: get_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
-@@ -56,7 +76,7 @@
+-   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 library.`
     | :sg:`init(cache_size=64, resolution=72)`
  
-    This function initializes the underlying FreeType 2 library and must be
-@@ -74,7 +94,7 @@
+-   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
  
     | :sg:`quit()`
  
     This function de-initializes the ``freetype`` module. After calling this
-@@ -85,7 +105,7 @@
+@@ -85,18 +111,18 @@
  
  .. function:: was_init
  
 +   | :sl:`Return whether the the FreeType library is initialized.`
     | :sg:`was_init() -> bool`
  
-    Returns whether the the FreeType 2 library is initialized.
-@@ -106,6 +126,16 @@
+-   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.
++   If not changed it will be 72.
+ 
+ .. function:: set_default_resolution
+ 
+@@ -106,14 +132,24 @@
     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.
  
 +   | :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 this will fallback on loading the default pygame font. The font name
-+   can be a comma separated list of font names to look for.
++   match the requested *bold* and *italic* flags. If a suitable system font
++   is not found the default, Pygame, font will load 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`
-@@ -124,6 +154,8 @@
-    file-like object containing the font, or None; if None, the default, built-in font
-    is used.
+    | :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
+ 
+@@ -121,27 +157,30 @@
+    | :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
-diff -r 3299e2cc3c4c -r 247a0a153db2 src/doc/examples_doc.h
+-   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 possible.
+ 
+    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.
+ 
+-   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`.
+@@ -192,20 +231,21 @@
+       | :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
+@@ -216,10 +256,10 @@
+       | :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:
+ 
+       ::
+ 
+@@ -230,7 +270,7 @@
+       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.
+@@ -284,7 +324,7 @@
+       | :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
+@@ -302,7 +342,7 @@
+       | :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.
+@@ -312,60 +352,51 @@
+       | :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
+       ``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 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* argumemt 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 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
++      both the foreground and background colors, as well as the per-pixel
++      alpha of the destination surface, affects the blit.
+ 
+       The return value is a rectangle giving the size and position of the
+       rendered text within the surface.
+@@ -407,10 +438,6 @@
+       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
+       ``LATIN1``.
+ 
+@@ -429,8 +456,8 @@
+       | :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`.
+ 
+    .. attribute:: style
+ 
+diff -r 3299e2cc3c4c src/doc/examples_doc.h
 --- a/src/doc/examples_doc.h	Tue Nov 05 13:29:18 2013 -0800
-+++ b/src/doc/examples_doc.h	Wed Nov 06 12:59:09 2013 -0800
++++ b/src/doc/examples_doc.h	Wed Nov 06 18:22:06 2013 -0800
 @@ -13,6 +13,8 @@
  
  #define DOC_PYGAMEEXAMPLESFONTYMAIN "fonty.main() -> None\nrun a font rendering example"
  pygame.examples.vgrade.main
   vgrade.main() -> None
  display a vertical gradient
-diff -r 3299e2cc3c4c -r 247a0a153db2 src/doc/freetype_doc.h
+diff -r 3299e2cc3c4c src/doc/freetype_doc.h
 --- a/src/doc/freetype_doc.h	Tue Nov 05 13:29:18 2013 -0800
-+++ b/src/doc/freetype_doc.h	Wed Nov 06 12:59:09 2013 -0800
++++ b/src/doc/freetype_doc.h	Wed Nov 06 18:22:06 2013 -0800
 @@ -1,20 +1,22 @@
  /* Auto generated file: with makeref.py .  Docs go in src/ *.doc . */
  #define DOC_PYGAMEFREETYPE "Enhanced Pygame module for loading and rendering computer fonts"