illume avatar illume committed e909844 Merge

Merged in takluyver/pygame/docs-changes (pull request #19: More changes to the docs)

Comments (0)

Files changed (105)

 docs/\.buildinfo
 docs/objects.inv
 docs/doctrees/*
+docs/_sources
+docs/_static
+docs/genindex.html
+docs/search.html
+docs/searchindex.js
+docs/tut/newbieguide.html
+docs/filepaths.html
+docs/index.html
+docs/ref/*.html
+docs/tut/SpriteIntro.html

docs/_sources/filepaths.txt

-File Path Function Arguments
-============================
-
-File Path Function Arguments
-----------------------------
-
-   A Pygame function or method which takes a file path argument
-   will accept either an Unicode or a byte — 8-bit or ASCII character — string.
-   Unicode strings are translated to Python's default file system encoding,
-   as returned by sys.getfilesystemencoding().
-   An Unicode code point above U+FFFF — '\uFFFF' — can
-   be coded directly with a 32-bit escape
-   sequences — '\Uxxxxxxxx' — ,
-   even for Python interpreters built with an UCS-2 (16-bit character) unicode type.
-   Byte strings are passed to the operating system unchanged.
-
-   Null characters — '\x00' — 
-   are not permitted in the path, raising an exception.
-   An exception is also raised if an Unicode file path cannot be encoded.
-   How UTF-16 surrogate codes are handled is Python interpreter dependent.
-   Use UTF-32 code points and 32-bit escape sequences instead.
-   The exception types are function dependent.

docs/_sources/index.txt

-.. Pygame documentation master file, created by
-   sphinx-quickstart on Sat Mar  5 11:56:39 2011.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Pygame Front Page
-=================
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-   :hidden:
-
-   ref/*
-   filepaths
-
-Documents
----------
-
-`Readme`_
-  Basic information about Pygame, what it is, who is involved, and where to find it.
-
-`Install`_
-  Steps needed to compile Pygame on several platforms.
-  Also help on finding and installing prebuilt binaries for your system.
-
-`File Path Function Arguments`_
-  How Pygame handles file system paths.
-
-`LGPL License`_
-  This is the license Pygame is distributed under.
-  It provides for Pygame to be distributed with open source and commercial software.
-  Generally, if Pygame is not changed, it can be used with any type of program.
-  
-Tutorials
----------
-
-`Introduction to Pygame`_
-  An introduction to the basics of Pygame.
-  This is written for users of Python and appeared in volume two of the Py magazine.
-
-`Import and Initialize`_
-  The beginning steps on importing and initializing Pygame.
-  The Pygame package is made of several modules.
-  Some modules are not included on all platforms.
-
-`How do I move an Image?`_
-  A basic tutorial that covers the concepts behind 2D computer animation.
-  Information about drawing and clearing objects to make them appear animated.
-
-`Chimp Tutorial, Line by Line`_
-  The pygame examples include a simple program with an interactive fist and a chimpanzee.
-  This was inspired by the annoying flash banner of the early 2000's.
-  This tutorial examines every line of coded used in the example.
-
-`Sprite Module Introduction`_
-  Pygame includes a higher level sprite module to help organize games.
-  The sprite module includes several classes that help manage details found in almost all games types.
-  The Sprite classes are a bit more advanced than the regular Pygame modules,
-  and need more understanding to be properly used.
-
-`Surfarray Introduction`_
-  Pygame used the Numpy python module to allow efficient per pixel effects on images.
-  Using the surfae arrays is an advanced feature that allows custom effects and filters.
-  This also examines some of the simple effects from the Pygame example, arraydemo.py.
-
-`Camera Module Introduction`_
-  Pygame, as of 1.9, has a camera module that allows you to capture images,
-  watch live streams, and do some basic computer vision.
-  This tutorial covers those use cases.
-
-`Newbie Guide`_
-  A list of thirteen helpful tips for people to get comfortable using Pygame.
-
-`Making Games Tutorial`_
-  A large tutorial that covers the bigger topics needed to create an entire game.
-
-Reference
----------
-
-:ref:`genindex`
-  A list of all functions, classes, and methods in the Pygame package.
-
-:doc:`ref/cdrom`
-  How to access and control the CD audio devices.
-
-:doc:`ref/color`
-  Color representation.
-
-:doc:`ref/cursors`
-  Loading and compiling cursor images.
-
-:doc:`ref/display`
-  Configure the display surface.
-
-:doc:`ref/draw`
-  Drawing simple shapes like lines and ellipses to surfaces.
-
-:doc:`ref/event`
-  Manage the incoming events from various input devices and the windowing platform.
-
-:doc:`ref/examples`
-  Various programs demonstrating the use of individual pyame modules.
-
-:doc:`ref/font`
-  Loading and rendering Truetype fonts.
-
-:doc:`ref/freetype`
-  Enhanced Pygame module for loading and rendering font faces.
-
-:doc:`ref/gfxdraw`
-  Anti-aliasing draw functions.
-
-:doc:`ref/image`
-  Loading, saving, and transferring of surfaces.
-
-:doc:`ref/joystick`
-  Manage the joystick devices.
-
-:doc:`ref/key`
-  Manage the keyboard device.
-
-:doc:`ref/locals`
-  Pygame constants.
-
-:doc:`ref/mixer`
-  Load and play sounds
-
-:doc:`ref/mouse`
-  Manage the mouse device and display.
-
-:doc:`ref/movie`
-  Video playback from MPEG movies.
-
-:doc:`ref/music`
-  Play streaming music tracks.
-
-:doc:`ref/overlay`
-  Access advanced video overlays.
-
-:doc:`ref/pygame`
-  Top level functions to manage Pygame.
-
-:doc:`ref/pixelarray`
-  Manipulate image pixel data.
-
-:doc:`ref/rect`
-  Flexible container for a rectangle.
-
-:doc:`ref/scrap`
-  Native clipboard access.
-
-:doc:`ref/sndarray`
-  Manipulate sound sample data.
-
-:doc:`ref/sprite`
-  Higher level objects to represent game images.
-
-:doc:`ref/surface`
-  Objects for images and the screen.
-
-:doc:`ref/surfarray`
-  Manipulate image pixel data.
-
-:doc:`ref/tests`
-  Test Pygame.
-
-:doc:`ref/time`
-  Manage timing and framerate.
-
-:doc:`ref/transform`
-  Resize and move images.
-
-:ref:`search`
-  Search Pygame documents by keyword.
-
-.. _Readme: ../readme.html
-
-.. _Install: ../install.html
-
-.. _File Path Function Arguments: filepaths.html
-
-.. _LGPL License: ../LGPL
-
-.. _Introduction to Pygame: tut/intro/intro.html
-
-.. _Import and Initialize: tut/ImportInit.html
-
-.. _How do I move an Image?: tut/MoveIt.html
-
-.. _Chimp Tutorial, Line by Line: tut/chimp/ChimpLineByLine.html
-
-.. _Sprite Module Introduction: tut/SpriteIntro.html
-
-.. _Surfarray Introduction: tut/surfarray/SurfarrayIntro.html
-
-.. _Camera Module Introduction: tut/camera/CameraIntro.html
-
-.. _Newbie Guide: tut/newbieguide.html
-
-.. _Making Games Tutorial: tut/tom/MakeGames.html

docs/_sources/ref/camera.txt

-.. include:: common.txt
-
-:mod:`pygame.camera`
-====================
-
-.. module:: pygame.camera
-   :synopsis: pygame module for camera use
-
-| :sl:`pygame module for camera use`
-
-Pygame currently supports only Linux and v4l2 cameras.
-
-EXPERIMENTAL!: This api may change or disappear in later pygame releases. If
-you use this, your code will very likely break with the next pygame release.
-
-The Bayer to ``RGB`` function is based on:
-
-::
-
- Sonix SN9C101 based webcam basic I/F routines
- Copyright (C) 2004 Takafumi Mizuno <taka-qce@ls-a.jp>
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
- THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
- ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
- FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- SUCH DAMAGE.
-
-New in pygame 1.9.0.
-
-.. function:: colorspace
-
-   | :sl:`Surface colorspace conversion`
-   | :sg:`colorspace(Surface, format, DestSurface = None) -> Surface`
-
-   Allows for conversion from "RGB" to a destination colorspace of "HSV" or
-   "YUV". The source and destination surfaces must be the same size and pixel
-   depth. This is useful for computer vision on devices with limited processing
-   power. Capture as small of an image as possible, ``transform.scale()`` it
-   even smaller, and then convert the colorspace to ``YUV`` or ``HSV`` before
-   doing any processing on it.
-
-   .. ## pygame.camera.colorspace ##
-
-.. function:: list_cameras
-
-   | :sl:`returns a list of available cameras`
-   | :sg:`list_cameras() -> [cameras]`
-
-   Checks the computer for available cameras and returns a list of strings of
-   camera names, ready to be fed into :class:`pygame.camera.Camera`.
-
-   .. ## pygame.camera.list_cameras ##
-
-.. class:: Camera
-
-   | :sl:`load a camera`
-   | :sg:`Camera(device, (width, height), format) -> Camera`
-
-   Loads a v4l2 camera. The device is typically something like "/dev/video0".
-   Default width and height are 640 by 480. Format is the desired colorspace of
-   the output. This is useful for computer vision purposes. The default is
-   ``RGB``. The following are supported:
-
-      * ``RGB`` - Red, Green, Blue
-
-      * ``YUV`` - Luma, Blue Chrominance, Red Chrominance
-
-      * ``HSV`` - Hue, Saturation, Value
-
-   .. method:: start
-
-      | :sl:`opens, initializes, and starts capturing`
-      | :sg:`start() -> None`
-
-      Opens the camera device, attempts to initialize it, and begins recording
-      images to a buffer. The camera must be started before any of the below
-      functions can be used.
-
-      .. ## Camera.start ##
-
-   .. method:: stop
-
-      | :sl:`stops, uninitializes, and closes the camera`
-      | :sg:`stop() -> None`
-
-      Stops recording, uninitializes the camera, and closes it. Once a camera
-      is stopped, the below functions cannot be used until it is started again.
-
-      .. ## Camera.stop ##
-
-   .. method:: get_controls
-
-      | :sl:`gets current values of user controls`
-      | :sg:`get_controls() -> (hflip = bool, vflip = bool, brightness)`
-
-      If the camera supports it, get_controls will return the current settings
-      for horizontal and vertical image flip as bools and brightness as an int.
-      If unsupported, it will return the default values of (0, 0, 0). Note that
-      the return values here may be different than those returned by
-      set_controls, though these are more likely to be correct.
-
-      .. ## Camera.get_controls ##
-
-   .. method:: set_controls
-
-      | :sl:`changes camera settings if supported by the camera`
-      | :sg:`set_controls(hflip = bool, vflip = bool, brightness) -> (hflip = bool, vflip = bool, brightness)`
-
-      Allows you to change camera settings if the camera supports it. The
-      return values will be the input values if the camera claims it succeeded
-      or the values previously in use if not. Each argument is optional, and
-      the desired one can be chosen by supplying the keyword, like hflip. Note
-      that the actual settings being used by the camera may not be the same as
-      those returned by set_controls.
-
-      .. ## Camera.set_controls ##
-
-   .. method:: get_size
-
-      | :sl:`returns the dimensions of the images being recorded`
-      | :sg:`get_size() -> (width, height)`
-
-      Returns the current dimensions of the images being captured by the
-      camera. This will return the actual size, which may be different than the
-      one specified during initialization if the camera did not support that
-      size.
-
-      .. ## Camera.get_size ##
-
-   .. method:: query_image
-
-      | :sl:`checks if a frame is ready`
-      | :sg:`query_image() -> bool`
-
-      If an image is ready to get, it returns true. Otherwise it returns false.
-      Note that some webcams will always return False and will only queue a
-      frame when called with a blocking function like ``get_image()``. This is
-      useful to separate the framerate of the game from that of the camera
-      without having to use threading.
-
-      .. ## Camera.query_image ##
-
-   .. method:: get_image
-
-      | :sl:`captures an image as a Surface`
-      | :sg:`get_image(Surface = None) -> Surface`
-
-      Pulls an image off of the buffer as an ``RGB`` Surface. It can optionally
-      reuse an existing Surface to save time. The bit depth of the surface is
-      either 24bits or the same as the optionally supplied Surface.
-
-      .. ## Camera.get_image ##
-
-   .. method:: get_raw
-
-      | :sl:`returns an unmodified image as a string`
-      | :sg:`get_raw() -> string`
-
-      Gets an image from a camera as a string in the native pixelformat of the
-      camera. Useful for integration with other libraries.
-
-      .. ## Camera.get_raw ##
-
-   .. ## pygame.camera.Camera ##
-
-.. ## pygame.camera ##

docs/_sources/ref/cdrom.txt

-.. include:: common.txt
-
-:mod:`pygame.cdrom`
-===================
-
-.. module:: pygame.cdrom
-   :synopsis: pygame module for audio cdrom control
-
-| :sl:`pygame module for audio cdrom control`
-
-The cdrom module manages the ``CD`` and ``DVD`` drives on a computer. It can
-also control the playback of audio cd's. This module needs to be initialized
-before it can do anything. Each ``CD`` object you create represents a cdrom
-drive and must also be initialized individually before it can do most things.
-
-.. function:: init
-
-   | :sl:`initialize the cdrom module`
-   | :sg:`init() -> None`
-
-   Initialize the cdrom module. This will scan the system for all ``CD``
-   devices. The module must be initialized before any other functions will
-   work. This automatically happens when you call ``pygame.init()``.
-
-   It is safe to call this function more than once.
-
-   .. ## pygame.cdrom.init ##
-
-.. function:: quit
-
-   | :sl:`uninitialize the cdrom module`
-   | :sg:`quit() -> None`
-
-   Uninitialize the cdrom module. After you call this any existing ``CD``
-   objects will no longer work.
-
-   It is safe to call this function more than once.
-
-   .. ## pygame.cdrom.quit ##
-
-.. function:: get_init
-
-   | :sl:`true if the cdrom module is initialized`
-   | :sg:`get_init() -> bool`
-
-   Test if the cdrom module is initialized or not. This is different than the
-   ``CD.init()`` since each drive must also be initialized individually.
-
-   .. ## pygame.cdrom.get_init ##
-
-.. function:: get_count
-
-   | :sl:`number of cd drives on the system`
-   | :sg:`get_count() -> count`
-
-   Return the number of cd drives on the system. When you create ``CD`` objects
-   you need to pass an integer id that must be lower than this count. The count
-   will be 0 if there are no drives on the system.
-
-   .. ## pygame.cdrom.get_count ##
-
-.. class:: CD
-
-   | :sl:`class to manage a cdrom drive`
-   | :sg:`CD(id) -> CD`
-
-   You can create a ``CD`` object for each cdrom on the system. Use
-   ``pygame.cdrom.get_count()`` to determine how many drives actually exist.
-   The id argument is an integer of the drive, starting at zero.
-
-   The ``CD`` object is not initialized, you can only call ``CD.get_id()`` and
-   ``CD.get_name()`` on an uninitialized drive.
-
-   It is safe to create multiple ``CD`` objects for the same drive, they will
-   all cooperate normally.
-
-   .. method:: init
-
-      | :sl:`initialize a cdrom drive for use`
-      | :sg:`init() -> None`
-
-      Initialize the cdrom drive for use. The drive must be initialized for
-      most ``CD`` methods to work. Even if the rest of pygame has been
-      initialized.
-
-      There may be a brief pause while the drive is initialized. Avoid
-      ``CD.init()`` if the program should not stop for a second or two.
-
-      .. ## CD.init ##
-
-   .. method:: quit
-
-      | :sl:`uninitialize a cdrom drive for use`
-      | :sg:`quit() -> None`
-
-      Uninitialize a drive for use. Call this when your program will not be
-      accessing the drive for awhile.
-
-      .. ## CD.quit ##
-
-   .. method:: get_init
-
-      | :sl:`true if this cd device initialized`
-      | :sg:`get_init() -> bool`
-
-      Test if this ``CDROM`` device is initialized. This is different than the
-      ``pygame.cdrom.init()`` since each drive must also be initialized
-      individually.
-
-      .. ## CD.get_init ##
-
-   .. method:: play
-
-      | :sl:`start playing audio`
-      | :sg:`play(track, start=None, end=None) -> None`
-
-      Playback audio from an audio cdrom in the drive. Besides the track number
-      argument, you can also pass a starting and ending time for playback. The
-      start and end time are in seconds, and can limit the section of an audio
-      track played.
-
-      If you pass a start time but no end, the audio will play to the end of
-      the track. If you pass a start time and 'None' for the end time, the
-      audio will play to the end of the entire disc.
-
-      See the ``CD.get_numtracks()`` and ``CD.get_track_audio()`` to find
-      tracks to playback.
-
-      Note, track 0 is the first track on the ``CD``. Track numbers start at
-      zero.
-
-      .. ## CD.play ##
-
-   .. method:: stop
-
-      | :sl:`stop audio playback`
-      | :sg:`stop() -> None`
-
-      Stops playback of audio from the cdrom. This will also lose the current
-      playback position. This method does nothing if the drive isn't already
-      playing audio.
-
-      .. ## CD.stop ##
-
-   .. method:: pause
-
-      | :sl:`temporarily stop audio playback`
-      | :sg:`pause() -> None`
-
-      Temporarily stop audio playback on the ``CD``. The playback can be
-      resumed at the same point with the ``CD.resume()`` method. If the ``CD``
-      is not playing this method does nothing.
-
-      Note, track 0 is the first track on the ``CD``. Track numbers start at
-      zero.
-
-      .. ## CD.pause ##
-
-   .. method:: resume
-
-      | :sl:`unpause audio playback`
-      | :sg:`resume() -> None`
-
-      Unpause a paused ``CD``. If the ``CD`` is not paused or already playing,
-      this method does nothing.
-
-      .. ## CD.resume ##
-
-   .. method:: eject
-
-      | :sl:`eject or open the cdrom drive`
-      | :sg:`eject() -> None`
-
-      This will open the cdrom drive and eject the cdrom. If the drive is
-      playing or paused it will be stopped.
-
-      .. ## CD.eject ##
-
-   .. method:: get_id
-
-      | :sl:`the index of the cdrom drive`
-      | :sg:`get_id() -> id`
-
-      Returns the integer id that was used to create the ``CD`` instance. This
-      method can work on an uninitialized ``CD``.
-
-      .. ## CD.get_id ##
-
-   .. method:: get_name
-
-      | :sl:`the system name of the cdrom drive`
-      | :sg:`get_name() -> name`
-
-      Return the string name of the drive. This is the system name used to
-      represent the drive. It is often the drive letter or device name. This
-      method can work on an uninitialized ``CD``.
-
-      .. ## CD.get_name ##
-
-   .. method:: get_busy
-
-      | :sl:`true if the drive is playing audio`
-      | :sg:`get_busy() -> bool`
-
-      Returns True if the drive busy playing back audio.
-
-      .. ## CD.get_busy ##
-
-   .. method:: get_paused
-
-      | :sl:`true if the drive is paused`
-      | :sg:`get_paused() -> bool`
-
-      Returns True if the drive is currently paused.
-
-      .. ## CD.get_paused ##
-
-   .. method:: get_current
-
-      | :sl:`the current audio playback position`
-      | :sg:`get_current() -> track, seconds`
-
-      Returns both the current track and time of that track. This method works
-      when the drive is either playing or paused.
-
-      Note, track 0 is the first track on the ``CD``. Track numbers start at
-      zero.
-
-      .. ## CD.get_current ##
-
-   .. method:: get_empty
-
-      | :sl:`False if a cdrom is in the drive`
-      | :sg:`get_empty() -> bool`
-
-      Return False if there is a cdrom currently in the drive. If the drive is
-      empty this will return True.
-
-      .. ## CD.get_empty ##
-
-   .. method:: get_numtracks
-
-      | :sl:`the number of tracks on the cdrom`
-      | :sg:`get_numtracks() -> count`
-
-      Return the number of tracks on the cdrom in the drive. This will return
-      zero of the drive is empty or has no tracks.
-
-      .. ## CD.get_numtracks ##
-
-   .. method:: get_track_audio
-
-      | :sl:`true if the cdrom track has audio data`
-      | :sg:`get_track_audio(track) -> bool`
-
-      Determine if a track on a cdrom contains audio data. You can also call
-      ``CD.num_tracks()`` and ``CD.get_all()`` to determine more information
-      about the cdrom.
-
-      Note, track 0 is the first track on the ``CD``. Track numbers start at
-      zero.
-
-      .. ## CD.get_track_audio ##
-
-   .. method:: get_all
-
-      | :sl:`get all track information`
-      | :sg:`get_all() -> [(audio, start, end, lenth), ...]`
-
-      Return a list with information for every track on the cdrom. The
-      information consists of a tuple with four values. The audio value is True
-      if the track contains audio data. The start, end, and length values are
-      floating point numbers in seconds. Start and end represent absolute times
-      on the entire disc.
-
-      .. ## CD.get_all ##
-
-   .. method:: get_track_start
-
-      | :sl:`start time of a cdrom track`
-      | :sg:`get_track_start(track) -> seconds`
-
-      Return the absolute time in seconds where at start of the cdrom track.
-
-      Note, track 0 is the first track on the ``CD``. Track numbers start at
-      zero.
-
-      .. ## CD.get_track_start ##
-
-   .. method:: get_track_length
-
-      | :sl:`length of a cdrom track`
-      | :sg:`get_track_length(track) -> seconds`
-
-      Return a floating point value in seconds of the length of the cdrom
-      track.
-
-      Note, track 0 is the first track on the ``CD``. Track numbers start at
-      zero.
-
-      .. ## CD.get_track_length ##
-
-   .. ## pygame.cdrom.CD ##
-
-.. ## pygame.cdrom ##

docs/_sources/ref/color.txt

-.. include:: common.txt
-
-:mod:`pygame.Color`
-===================
-
-.. currentmodule:: pygame
-
-.. class:: Color
-
-   | :sl:`pygame object for color representations`
-   | :sg:`Color(name) -> Color`
-   | :sg:`Color(r, g, b, a) -> Color`
-   | :sg:`Color(rgbvalue) -> Color`
-
-   The Color class represents ``RGBA`` color values using a value range of
-   0-255. It allows basic arithmetic operations to create new colors, supports
-   conversions to other color spaces such as ``HSV`` or ``HSL`` and lets you
-   adjust single color channels. Alpha defaults to 255 when not given.
-
-   'rgbvalue' can be either a color name, an ``HTML`` color format string, a
-   hex number string, or an integer pixel value. The ``HTML`` format is
-   '#rrggbbaa', where rr, gg, bb, and aa are 2 digit hex numbers. The alpha aa
-   is optional. A hex number string has the form '0xrrggbbaa', where aa is
-   optional.
-
-   Color objects support equality comparison with other color objects and 3 or
-   4 element tuples of integers (New in 1.9.0). There was a bug in pygame 1.8.1
-   where the default alpha was 0, not 255 like previously.
-
-   New implementation of Color was done in pygame 1.8.1.
-
-   .. attribute:: r
-
-      | :sl:`Gets or sets the red value of the Color.`
-      | :sg:`r -> int`
-
-      The red value of the Color.
-
-      .. ## Color.r ##
-
-   .. attribute:: g
-
-      | :sl:`Gets or sets the green value of the Color.`
-      | :sg:`g -> int`
-
-      The green value of the Color.
-
-      .. ## Color.g ##
-
-   .. attribute:: b
-
-      | :sl:`Gets or sets the blue value of the Color.`
-      | :sg:`b -> int`
-
-      The blue value of the Color.
-
-      .. ## Color.b ##
-
-   .. attribute:: a
-
-      | :sl:`Gets or sets the alpha value of the Color.`
-      | :sg:`a -> int`
-
-      The alpha value of the Color.
-
-      .. ## Color.a ##
-
-   .. attribute:: cmy
-
-      | :sl:`Gets or sets the CMY representation of the Color.`
-      | :sg:`cmy -> tuple`
-
-      The ``CMY`` representation of the Color. The ``CMY`` components are in
-      the ranges ``C`` = [0, 1], ``M`` = [0, 1], ``Y`` = [0, 1]. Note that this
-      will not return the absolutely exact ``CMY`` values for the set ``RGB``
-      values in all cases. Due to the ``RGB`` mapping from 0-255 and the
-      ``CMY`` mapping from 0-1 rounding errors may cause the ``CMY`` values to
-      differ slightly from what you might expect.
-
-      .. ## Color.cmy ##
-
-   .. attribute:: hsva
-
-      | :sl:`Gets or sets the HSVA representation of the Color.`
-      | :sg:`hsva -> tuple`
-
-      The ``HSVA`` representation of the Color. The ``HSVA`` components are in
-      the ranges ``H`` = [0, 360], ``S`` = [0, 100], ``V`` = [0, 100], A = [0,
-      100]. Note that this will not return the absolutely exact ``HSV`` values
-      for the set ``RGB`` values in all cases. Due to the ``RGB`` mapping from
-      0-255 and the ``HSV`` mapping from 0-100 and 0-360 rounding errors may
-      cause the ``HSV`` values to differ slightly from what you might expect.
-
-      .. ## Color.hsva ##
-
-   .. attribute:: hsla
-
-      | :sl:`Gets or sets the HSLA representation of the Color.`
-      | :sg:`hsla -> tuple`
-
-      The ``HSLA`` representation of the Color. The ``HSLA`` components are in
-      the ranges ``H`` = [0, 360], ``S`` = [0, 100], ``V`` = [0, 100], A = [0,
-      100]. Note that this will not return the absolutely exact ``HSL`` values
-      for the set ``RGB`` values in all cases. Due to the ``RGB`` mapping from
-      0-255 and the ``HSL`` mapping from 0-100 and 0-360 rounding errors may
-      cause the ``HSL`` values to differ slightly from what you might expect.
-
-      .. ## Color.hsla ##
-
-   .. attribute:: i1i2i3
-
-      | :sl:`Gets or sets the I1I2I3 representation of the Color.`
-      | :sg:`i1i2i3 -> tuple`
-
-      The ``I1I2I3`` representation of the Color. The ``I1I2I3`` components are
-      in the ranges ``I1`` = [0, 1], ``I2`` = [-0.5, 0.5], ``I3`` = [-0.5,
-      0.5]. Note that this will not return the absolutely exact ``I1I2I3``
-      values for the set ``RGB`` values in all cases. Due to the ``RGB``
-      mapping from 0-255 and the ``I1I2I3`` mapping from 0-1 rounding errors
-      may cause the ``I1I2I3`` values to differ slightly from what you might
-      expect.
-
-      .. ## Color.i1i2i3 ##
-
-   .. method:: normalize
-
-      | :sl:`Returns the normalized RGBA values of the Color.`
-      | :sg:`normalize() -> tuple`
-
-      Returns the normalized ``RGBA`` values of the Color as floating point
-      values.
-
-      .. ## Color.normalize ##
-
-   .. method:: correct_gamma
-
-      | :sl:`Applies a certain gamma value to the Color.`
-      | :sg:`correct_gamma (gamma) -> Color`
-
-      Applies a certain gamma value to the Color and returns a new Color with
-      the adjusted ``RGBA`` values.
-
-      .. ## Color.correct_gamma ##
-
-   .. method:: set_length
-
-      | :sl:`Set the number of elements in the Color to 1,2,3, or 4.`
-      | :sg:`set_length(len) -> None`
-
-      The default Color length is 4. Colors can have lengths 1,2,3 or 4. This
-      is useful if you want to unpack to r,g,b and not r,g,b,a. If you want to
-      get the length of a Color do ``len(acolor)``.
-
-      New in pygame 1.9.0.
-
-      .. ## Color.set_length ##
-
-   .. ## pygame.Color ##

docs/_sources/ref/cursors.txt

-.. include:: common.txt
-
-:mod:`pygame.cursors`
-=====================
-
-.. module:: pygame.cursors
-   :synopsis: pygame module for cursor resources
-
-| :sl:`pygame module for cursor resources`
-
-Pygame offers control over the system hardware cursor. Pygame only supports
-black and white cursors for the system. You control the cursor with functions
-inside :mod:`pygame.mouse`.
-
-This cursors module contains functions for loading and unencoding various
-cursor formats. These allow you to easily store your cursors in external files
-or directly as encoded python strings.
-
-The module includes several standard cursors. The ``pygame.mouse.set_cursor()``
-function takes several arguments. All those arguments have been stored in a
-single tuple you can call like this:
-
-::
-
-   >>> pygame.mouse.set_cursor(*pygame.cursors.arrow)
-
-This module also contains a few cursors as formatted strings. You'll need to
-pass these to ``pygame.cursors.compile()`` function before you can use them.
-The example call would look like this:
-
-::
-
-   >>> cursor = pygame.cursors.compile(pygame.cursors.textmarker_strings)
-   >>> pygame.mouse.set_cursor(*cursor)
-
-The following variables are cursor bitmaps that can be used as cursor:
-
-   * ``pygame.cursors.arrow``
-
-   * ``pygame.cursors.diamond``
-
-   * ``pygame.cursors.broken_x``
-
-   * ``pygame.cursors.tri_left``
-
-   * ``pygame.cursors.tri_right``
-
-The following strings can be converted into cursor bitmaps with
-``pygame.cursors.compile()`` :
-
-   * ``pygame.cursors.thickarrow_strings``
-
-   * ``pygame.cursors.sizer_x_strings``
-
-   * ``pygame.cursors.sizer_y_strings``
-
-   * ``pygame.cursors.sizer_xy_strings``
-
-.. function:: compile
-
-   | :sl:`create binary cursor data from simple strings`
-   | :sg:`compile(strings, black='X', white='.', xor='o') -> data, mask`
-
-   A sequence of strings can be used to create binary cursor data for the
-   system cursor. The return values are the same format needed by
-   ``pygame.mouse.set_cursor()``.
-
-   If you are creating your own cursor strings, you can use any value represent
-   the black and white pixels. Some system allow you to set a special toggle
-   color for the system color, this is also called the xor color. If the system
-   does not support xor cursors, that color will simply be black.
-
-   The width of the strings must all be equal and be divisible by 8. An example
-   set of cursor strings looks like this
-
-   ::
-
-       thickarrow_strings = (               #sized 24x24
-         "XX                      ",
-         "XXX                     ",
-         "XXXX                    ",
-         "XX.XX                   ",
-         "XX..XX                  ",
-         "XX...XX                 ",
-         "XX....XX                ",
-         "XX.....XX               ",
-         "XX......XX              ",
-         "XX.......XX             ",
-         "XX........XX            ",
-         "XX........XXX           ",
-         "XX......XXXXX           ",
-         "XX.XXX..XX              ",
-         "XXXX XX..XX             ",
-         "XX   XX..XX             ",
-         "     XX..XX             ",
-         "      XX..XX            ",
-         "      XX..XX            ",
-         "       XXXX             ",
-         "       XX               ",
-         "                        ",
-         "                        ",
-         "                        ")
-
-   .. ## pygame.cursors.compile ##
-
-.. function:: load_xbm
-
-   | :sl:`load cursor data from an xbm file`
-   | :sg:`load_xbm(cursorfile) -> cursor_args`
-   | :sg:`load_xbm(cursorfile, maskfile) -> cursor_args`
-
-   This loads cursors for a simple subset of ``XBM`` files. ``XBM`` files are
-   traditionally used to store cursors on unix systems, they are an ascii
-   format used to represent simple images.
-
-   Sometimes the black and white color values will be split into two separate
-   ``XBM`` files. You can pass a second maskfile argument to load the two
-   images into a single cursor.
-
-   The cursorfile and maskfile arguments can either be filenames or filelike
-   object with the readlines method.
-
-   The return value cursor_args can be passed directly to the
-   ``pygame.mouse.set_cursor()`` function.
-
-   .. ## pygame.cursors.load_xbm ##
-
-.. ## pygame.cursors ##

docs/_sources/ref/display.txt

-.. include:: common.txt
-
-:mod:`pygame.display`
-=====================
-
-.. module:: pygame.display
-   :synopsis: pygame module to control the display window and screen
-
-| :sl:`pygame module to control the display window and screen`
-
-This module offers control over the pygame display. Pygame has a single display
-Surface that is either contained in a window or runs full screen. Once you
-create the display you treat it as a regular Surface. Changes are not
-immediately visible onscreen, you must choose one of the two flipping functions
-to update the actual display.
-
-The origin of the display, where x = 0, and y = 0 is the top left of the
-screen. Both axis increase positively towards the botom right of the screen.
-
-The pygame display can actually be initialized in one of several modes. By
-default the display is a basic software driven framebuffer. You can request
-special modules like hardware acceleration and OpenGL support. These are
-controlled by flags passed to ``pygame.display.set_mode()``.
-
-Pygame can only have a single display active at any time. Creating a new one
-with ``pygame.display.set_mode()`` will close the previous display. If precise
-control is needed over the pixel format or display resolutions, use the
-functions ``pygame.display.mode_ok()``, ``pygame.display.list_modes()``, and
-``pygame.display.Info()`` to query information about the display.
-
-Once the display Surface is created, the functions from this module effect the
-single existing display. The Surface becomes invalid if the module is
-uninitialized. If a new display mode is set, the existing Surface will
-automatically switch to operate on the new display.
-
-Then the display mode is set, several events are placed on the pygame event
-queue. ``pygame.QUIT`` is sent when the user has requested the program to
-shutdown. The window will receive ``pygame.ACTIVEEVENT`` events as the display
-gains and loses input focus. If the display is set with the
-``pygame.RESIZABLE`` flag, ``pygame.VIDEORESIZE`` events will be sent when the
-user adjusts the window dimensions. Hardware displays that draw direct to the
-screen will get ``pygame.VIDEOEXPOSE`` events when portions of the window must
-be redrawn.
-
-.. function:: init
-
-   | :sl:`initialize the display module`
-   | :sg:`init() -> None`
-
-   Initializes the pygame display module. The display module cannot do anything
-   until it is initialized. This is usually handled for you automatically when
-   you call the higher level ``pygame.init()``.
-
-   Pygame will select from one of several internal display backends when it is
-   initialized. The display mode will be chosen depending on the platform and
-   permissions of current user. Before the display module is initialized the
-   environment variable ``SDL_VIDEODRIVER`` can be set to control which backend
-   is used. The systems with multiple choices are listed here.
-
-   ::
-
-      Windows : windib, directx
-      Unix    : x11, dga, fbcon, directfb, ggi, vgl, svgalib, aalib
-
-   On some platforms it is possible to embed the pygame display into an already
-   existing window. To do this, the environment variable ``SDL_WINDOWID`` must
-   be set to a string containing the window id or handle. The environment
-   variable is checked when the pygame display is initialized. Be aware that
-   there can be many strange side effects when running in an embedded display.
-
-   It is harmless to call this more than once, repeated calls have no effect.
-
-   .. ## pygame.display.init ##
-
-.. function:: quit
-
-   | :sl:`uninitialize the display module`
-   | :sg:`quit() -> None`
-
-   This will shut down the entire display module. This means any active
-   displays will be closed. This will also be handled automatically when the
-   program exits.
-
-   It is harmless to call this more than once, repeated calls have no effect.
-
-   .. ## pygame.display.quit ##
-
-.. function:: get_init
-
-   | :sl:`true if the display module is initialized`
-   | :sg:`get_init() -> bool`
-
-   Returns True if the :mod:`pygame.display` module is currently initialized.
-
-   .. ## pygame.display.get_init ##
-
-.. function:: set_mode
-
-   | :sl:`initialize a window or screen for display`
-   | :sg:`set_mode(resolution=(0,0), flags=0, depth=0) -> Surface`
-
-   This function will create a display Surface. The arguments passed in are
-   requests for a display type. The actual created display will be the best
-   possible match supported by the system.
-
-   The resolution argument is a pair of numbers representing the width and
-   height. The flags argument is a collection of additional options. The depth
-   argument represents the number of bits to use for color.
-
-   The Surface that gets returned can be drawn to like a regular Surface but
-   changes will eventually be seen on the monitor.
-
-   If no resolution is passed or is set to (0, 0) and pygame uses ``SDL``
-   version 1.2.10 or above, the created Surface will have the same size as the
-   current screen resolution. If only the width or height are set to 0, the
-   Surface will have the same width or height as the screen resolution. Using a
-   ``SDL`` version prior to 1.2.10 will raise an exception.
-
-   It is usually best to not pass the depth argument. It will default to the
-   best and fastest color depth for the system. If your game requires a
-   specific color format you can control the depth with this argument. Pygame
-   will emulate an unavailable color depth which can be slow.
-
-   When requesting fullscreen display modes, sometimes an exact match for the
-   requested resolution cannot be made. In these situations pygame will select
-   the closest compatable match. The returned surface will still always match
-   the requested resolution.
-
-   The flags argument controls which type of display you want. There are
-   several to choose from, and you can even combine multiple types using the
-   bitwise or operator, (the pipe "|" character). If you pass 0 or no flags
-   argument it will default to a software driven window. Here are the display
-   flags you will want to choose from:
-
-   ::
-
-      pygame.FULLSCREEN    create a fullscreen display
-      pygame.DOUBLEBUF     recommended for HWSURFACE or OPENGL
-      pygame.HWSURFACE     hardware accelerated, only in FULLSCREEN
-      pygame.OPENGL        create an opengl renderable display
-      pygame.RESIZABLE     display window should be sizeable
-      pygame.NOFRAME       display window will have no border or controls
-
-   .. ## pygame.display.set_mode ##
-
-.. function:: get_surface
-
-   | :sl:`get a reference to the currently set display surface`
-   | :sg:`get_surface() -> Surface`
-
-   Return a reference to the currently set display Surface. If no display mode
-   has been set this will return None.
-
-   .. ## pygame.display.get_surface ##
-
-.. function:: flip
-
-   | :sl:`update the full display Surface to the screen`
-   | :sg:`flip() -> None`
-
-   This will update the contents of the entire display. If your display mode is
-   using the flags ``pygame.HWSURFACE`` and ``pygame.DOUBLEBUF``, this will
-   wait for a vertical retrace and swap the surfaces. If you are using a
-   different type of display mode, it will simply update the entire contents of
-   the surface.
-
-   When using an ``pygame.OPENGL`` display mode this will perform a gl buffer
-   swap.
-
-   .. ## pygame.display.flip ##
-
-.. function:: update
-
-   | :sl:`update portions of the screen for software displays`
-   | :sg:`update(rectangle=None) -> None`
-   | :sg:`update(rectangle_list) -> None`
-
-   This function is like an optimized version of ``pygame.display.flip()`` for
-   software displays. It allows only a portion of the screen to updated,
-   instead of the entire area. If no argument is passed it updates the entire
-   Surface area like ``pygame.display.flip()``.
-
-   You can pass the function a single rectangle, or a sequence of rectangles.
-   It is more efficient to pass many rectangles at once than to call update
-   multiple times with single or a partial list of rectangles. If passing a
-   sequence of rectangles it is safe to include None values in the list, which
-   will be skipped.
-
-   This call cannot be used on ``pygame.OPENGL`` displays and will generate an
-   exception.
-
-   .. ## pygame.display.update ##
-
-.. function:: get_driver
-
-   | :sl:`get the name of the pygame display backend`
-   | :sg:`get_driver() -> name`
-
-   Pygame chooses one of many available display backends when it is
-   initialized. This returns the internal name used for the display backend.
-   This can be used to provide limited information about what display
-   capabilities might be accelerated. See the ``SDL_VIDEODRIVER`` flags in
-   ``pygame.display.set_mode()`` to see some of the common options.
-
-   .. ## pygame.display.get_driver ##
-
-.. function:: Info
-
-   | :sl:`Create a video display information object`
-   | :sg:`Info() -> VideoInfo`
-
-   Creates a simple object containing several attributes to describe the
-   current graphics environment. If this is called before
-   ``pygame.display.set_mode()`` some platforms can provide information about
-   the default display mode. This can also be called after setting the display
-   mode to verify specific display options were satisfied. The VidInfo object
-   has several attributes:
-
-   ::
-
-     hw:         True if the display is hardware accelerated
-     wm:         True if windowed display modes can be used
-     video_mem:  The megabytes of video memory on the display. This is 0 if unknown
-     bitsize:    Number of bits used to store each pixel
-     bytesize:   Number of bytes used to store each pixel
-     masks:      Four values used to pack RGBA values into pixels
-     shifts:     Four values used to pack RGBA values into pixels
-     losses:     Four values used to pack RGBA values into pixels
-     blit_hw:    True if hardware Surface blitting is accelerated
-     blit_hw_CC: True if hardware Surface colorkey blitting is accelerated
-     blit_hw_A:  True if hardware Surface pixel alpha blitting is accelerated
-     blit_sw:    True if software Surface blitting is accelerated
-     blit_sw_CC: True if software Surface colorkey blitting is accelerated
-     blit_sw_A:  True if software Surface pixel alpha blitting is acclerated
-     current_h, current_h:  Width and height of the current video mode, or of the
-       desktop mode if called before the display.set_mode is called.
-       (current_h, current_w are available since SDL 1.2.10, and pygame 1.8.0)
-       They are -1 on error, or if an old SDL is being used.
-
-   .. ## pygame.display.Info ##
-
-.. function:: get_wm_info
-
-   | :sl:`Get information about the current windowing system`
-   | :sg:`get_wm_info() -> dict`
-
-   Creates a dictionary filled with string keys. The strings and values are
-   arbitrarily created by the system. Some systems may have no information and
-   an empty dictionary will be returned. Most platforms will return a "window"
-   key with the value set to the system id for the current display.
-
-   New with pygame 1.7.1
-
-   .. ## pygame.display.get_wm_info ##
-
-.. function:: list_modes
-
-   | :sl:`get list of available fullscreen modes`
-   | :sg:`list_modes(depth=0, flags=pygame.FULLSCREEN) -> list`
-
-   This function returns a list of possible dimensions for a specified color
-   depth. The return value will be an empty list if no display modes are
-   available with the given arguments. A return value of -1 means that any
-   requested resolution should work (this is likely the case for windowed
-   modes). Mode sizes are sorted from biggest to smallest.
-
-   If depth is 0, ``SDL`` will choose the current/best color depth for the
-   display. The flags defaults to ``pygame.FULLSCREEN``, but you may need to
-   add additional flags for specific fullscreen modes.
-
-   .. ## pygame.display.list_modes ##
-
-.. function:: mode_ok
-
-   | :sl:`pick the best color depth for a display mode`
-   | :sg:`mode_ok(size, flags=0, depth=0) -> depth`
-
-   This function uses the same arguments as ``pygame.display.set_mode()``. It
-   is used to depermine if a requested display mode is available. It will
-   return 0 if the display mode cannot be set. Otherwise it will return a pixel
-   depth that best matches the display asked for.
-
-   Usually the depth argument is not passed, but some platforms can support
-   multiple display depths. If passed it will hint to which depth is a better
-   match.
-
-   The most useful flags to pass will be ``pygame.HWSURFACE``,
-   ``pygame.DOUBLEBUF``, and maybe ``pygame.FULLSCREEN``. The function will
-   return 0 if these display flags cannot be set.
-
-   .. ## pygame.display.mode_ok ##
-
-.. function:: gl_get_attribute
-
-   | :sl:`get the value for an opengl flag for the current display`
-   | :sg:`gl_get_attribute(flag) -> value`
-
-   After calling ``pygame.display.set_mode()`` with the ``pygame.OPENGL`` flag,
-   it is a good idea to check the value of any requested OpenGL attributes. See
-   ``pygame.display.gl_set_attribute()`` for a list of valid flags.
-
-   .. ## pygame.display.gl_get_attribute ##
-
-.. function:: gl_set_attribute
-
-   | :sl:`request an opengl display attribute for the display mode`
-   | :sg:`gl_set_attribute(flag, value) -> None`
-
-   When calling ``pygame.display.set_mode()`` with the ``pygame.OPENGL`` flag,
-   Pygame automatically handles setting the OpenGL attributes like color and
-   doublebuffering. OpenGL offers several other attributes you may want control
-   over. Pass one of these attributes as the flag, and its appropriate value.
-   This must be called before ``pygame.display.set_mode()``
-
-   The ``OPENGL`` flags are;
-
-   ::
-
-     GL_ALPHA_SIZE, GL_DEPTH_SIZE, GL_STENCIL_SIZE, GL_ACCUM_RED_SIZE,
-     GL_ACCUM_GREEN_SIZE,  GL_ACCUM_BLUE_SIZE, GL_ACCUM_ALPHA_SIZE,
-     GL_MULTISAMPLEBUFFERS, GL_MULTISAMPLESAMPLES, GL_STEREO
-
-   .. ## pygame.display.gl_set_attribute ##
-
-.. function:: get_active
-
-   | :sl:`true when the display is active on the display`
-   | :sg:`get_active() -> bool`
-
-   After ``pygame.display.set_mode()`` is called the display Surface will be
-   visible on the screen. Most windowed displays can be hidden by the user. If
-   the display Surface is hidden or iconified this will return False.
-
-   .. ## pygame.display.get_active ##
-
-.. function:: iconify
-
-   | :sl:`iconify the display surface`
-   | :sg:`iconify() -> bool`
-
-   Request the window for the display surface be iconified or hidden. Not all
-   systems and displays support an iconified display. The function will return
-   True if successfull.
-
-   When the display is iconified ``pygame.display.get_active()`` will return
-   False. The event queue should receive a ``ACTIVEEVENT`` event when the
-   window has been iconified.
-
-   .. ## pygame.display.iconify ##
-
-.. function:: toggle_fullscreen
-
-   | :sl:`switch between fullscreen and windowed displays`
-   | :sg:`toggle_fullscreen() -> bool`
-
-   Switches the display window between windowed and fullscreen modes. This
-   function only works under the unix x11 video driver. For most situations it
-   is better to call ``pygame.display.set_mode()`` with new display flags.
-
-   .. ## pygame.display.toggle_fullscreen ##
-
-.. function:: set_gamma
-
-   | :sl:`change the hardware gamma ramps`
-   | :sg:`set_gamma(red, green=None, blue=None) -> bool`
-
-   Set the red, green, and blue gamma values on the display hardware. If the
-   green and blue arguments are not passed, they will both be the same as red.
-   Not all systems and hardware support gamma ramps, if the function succeeds
-   it will return True.
-
-   A gamma value of 1.0 creates a linear color table. Lower values will darken
-   the display and higher values will brighten.
-
-   .. ## pygame.display.set_gamma ##
-
-.. function:: set_gamma_ramp
-
-   | :sl:`change the hardware gamma ramps with a custom lookup`
-   | :sg:`set_gamma_ramp(red, green, blue) -> bool`
-
-   Set the red, green, and blue gamma ramps with an explicit lookup table. Each
-   argument should be sequence of 256 integers. The integers should range
-   between 0 and 0xffff. Not all systems and hardware support gamma ramps, if
-   the function succeeds it will return True.
-
-   .. ## pygame.display.set_gamma_ramp ##
-
-.. function:: set_icon
-
-   | :sl:`change the system image for the display window`
-   | :sg:`set_icon(Surface) -> None`
-
-   Sets the runtime icon the system will use to represent the display window.
-   All windows default to a simple pygame logo for the window icon.
-
-   You can pass any surface, but most systems want a smaller image around
-   32x32. The image can have colorkey transparency which will be passed to the
-   system.
-
-   Some systems do not allow the window icon to change after it has been shown.
-   This function can be called before ``pygame.display.set_mode()`` to create
-   the icon before the display mode is set.
-
-   .. ## pygame.display.set_icon ##
-
-.. function:: set_caption
-
-   | :sl:`set the current window caption`
-   | :sg:`set_caption(title, icontitle=None) -> None`
-
-   If the display has a window title, this function will change the name on the
-   window. Some systems support an alternate shorter title to be used for
-   minimized displays.
-
-   .. ## pygame.display.set_caption ##
-
-.. function:: get_caption
-
-   | :sl:`get the current window caption`
-   | :sg:`get_caption() -> (title, icontitle)`
-
-   Returns the title and icontitle for the display Surface. These will often be
-   the same value.
-
-   .. ## pygame.display.get_caption ##
-
-.. function:: set_palette
-
-   | :sl:`set the display color palette for indexed displays`
-   | :sg:`set_palette(palette=None) -> None`
-
-   This will change the video display color palette for 8bit displays. This
-   does not change the palette for the actual display Surface, only the palette
-   that is used to display the Surface. If no palette argument is passed, the
-   system default palette will be restored. The palette is a sequence of
-   ``RGB`` triplets.
-
-   .. ## pygame.display.set_palette ##
-
-.. ## pygame.display ##

docs/_sources/ref/draw.txt

-.. include:: common.txt
-
-:mod:`pygame.draw`
-==================
-
-.. module:: pygame.draw
-   :synopsis: pygame module for drawing shapes
-
-| :sl:`pygame module for drawing shapes`
-
-Draw several simple shapes to a Surface. These functions will work for
-rendering to any format of Surface. Rendering to hardware Surfaces will be
-slower than regular software Surfaces.
-
-Most of the functions take a width argument to represent the size of stroke
-around the edge of the shape. If a width of 0 is passed the function will
-actually solid fill the entire shape.
-
-All the drawing functions respect the clip area for the Surface, and will be
-constrained to that area. The functions return a rectangle representing the
-bounding area of changed pixels.
-
-Most of the arguments accept a color argument that is an ``RGB`` triplet. These
-can also accept an ``RGBA`` quadruplet. The alpha value will be written
-directly into the Surface if it contains pixel alphas, but the draw function
-will not draw transparently. The color argument can also be an integer pixel
-value that is already mapped to the Surface's pixel format.
-
-These functions must temporarily lock the Surface they are operating on. Many
-sequential drawing calls can be sped up by locking and unlocking the Surface
-object around the draw calls.
-
-.. function:: rect
-
-   | :sl:`draw a rectangle shape`
-   | :sg:`rect(Surface, color, Rect, width=0) -> Rect`
-
-   Draws a rectangular shape on the Surface. The given Rect is the area of the
-   rectangle. The width argument is the thickness to draw the outer edge. If
-   width is zero then the rectangle will be filled.
-
-   Keep in mind the ``Surface.fill()`` method works just as well for drawing
-   filled rectangles. In fact the ``Surface.fill()`` can be hardware
-   accelerated on some platforms with both software and hardware display modes.
-
-   .. ## pygame.draw.rect ##
-
-.. function:: polygon
-
-   | :sl:`draw a shape with any number of sides`
-   | :sg:`polygon(Surface, color, pointlist, width=0) -> Rect`
-
-   Draws a polygonal shape on the Surface. The pointlist argument is the
-   vertices of the polygon. The width argument is the thickness to draw the
-   outer edge. If width is zero then the polygon will be filled.
-
-   For aapolygon, use aalines with the 'closed' parameter.
-
-   .. ## pygame.draw.polygon ##
-
-.. function:: circle
-
-   | :sl:`draw a circle around a point`
-   | :sg:`circle(Surface, color, pos, radius, width=0) -> Rect`
-
-   Draws a circular shape on the Surface. The pos argument is the center of the
-   circle, and radius is the size. The width argument is the thickness to draw
-   the outer edge. If width is zero then the circle will be filled.
-
-   .. ## pygame.draw.circle ##
-
-.. function:: ellipse
-
-   | :sl:`draw a round shape inside a rectangle`
-   | :sg:`ellipse(Surface, color, Rect, width=0) -> Rect`
-
-   Draws an elliptical shape on the Surface. The given rectangle is the area
-   that the circle will fill. The width argument is the thickness to draw the
-   outer edge. If width is zero then the ellipse will be filled.
-
-   .. ## pygame.draw.ellipse ##
-
-.. function:: arc
-
-   | :sl:`draw a partial section of an ellipse`
-   | :sg:`arc(Surface, color, Rect, start_angle, stop_angle, width=1) -> Rect`
-
-   Draws an elliptical arc on the Surface. The rect argument is the area that
-   the ellipse will fill. The two angle arguments are the initial and final
-   angle in radians, with the zero on the right. The width argument is the
-   thickness to draw the outer edge.
-
-   .. ## pygame.draw.arc ##
-
-.. function:: line
-
-   | :sl:`draw a straight line segment`
-   | :sg:`line(Surface, color, start_pos, end_pos, width=1) -> Rect`
-
-   Draw a straight line segment on a Surface. There are no endcaps, the ends
-   are squared off for thick lines.
-
-   .. ## pygame.draw.line ##
-
-.. function:: lines
-
-   | :sl:`draw multiple contiguous line segments`
-   | :sg:`lines(Surface, color, closed, pointlist, width=1) -> Rect`
-
-   Draw a sequence of lines on a Surface. The pointlist argument is a series of
-   points that are connected by a line. If the closed argument is true an
-   additional line segment is drawn between the first and last points.
-
-   This does not draw any endcaps or miter joints. Lines with sharp corners and
-   wide line widths can have improper looking corners.
-
-   .. ## pygame.draw.lines ##
-
-.. function:: aaline
-
-   | :sl:`draw fine antialiased lines`
-   | :sg:`aaline(Surface, color, startpos, endpos, blend=1) -> Rect`
-
-   Draws an anti-aliased line on a surface. This will respect the clipping
-   rectangle. A bounding box of the affected area is returned returned as a
-   rectangle. If blend is true, the shades will be be blended with existing
-   pixel shades instead of overwriting them. This function accepts floating
-   point values for the end points.
-
-   .. ## pygame.draw.aaline ##
-
-.. function:: aalines
-
-   | :sl:`draw a connected sequence of antialiased lines`
-   | :sg:`aalines(Surface, color, closed, pointlist, blend=1) -> Rect`
-
-   Draws a sequence on a surface. You must pass at least two points in the
-   sequence of points. The closed argument is a simple boolean and if true, a
-   line will be draw between the first and last points. The boolean blend
-   argument set to true will blend the shades with existing shades instead of
-   overwriting them. This function accepts floating point values for the end
-   points.
-
-   .. ## pygame.draw.aalines ##
-
-.. ## pygame.draw ##

docs/_sources/ref/event.txt

-.. include:: common.txt
-
-:mod:`pygame.event`
-===================
-
-.. module:: pygame.event
-   :synopsis: pygame module for interacting with events and queues
-
-| :sl:`pygame module for interacting with events and queues`
-
-Pygame handles all it's event messaging through an event queue. The routines in
-this module help you manage that event queue. The input queue is heavily
-dependent on the pygame display module. If the display has not been initialized
-and a video mode not set, the event queue will not really work.
-
-The queue is a regular queue of Event objects, there are a variety of ways to
-access the events it contains. From simply checking for the existance of
-events, to grabbing them directly off the stack.
-
-All events have a type identifier. This event type is in between the values of
-``NOEVENT`` and ``NUMEVENTS``. All user defined events can have the value of
-``USEREVENT`` or higher. It is recommended make sure your event id's follow
-this system.
-
-To get the state of various input devices, you can forego the event queue and
-access the input devices directly with their appropriate modules; mouse, key,
-and joystick. If you use this method, remember that pygame requires some form
-of communication with the system window manager and other parts of the
-platform. To keep pygame in synch with the system, you will need to call
-``pygame.event.pump()`` to keep everything current. You'll want to call this
-function usually once per game loop.
-
-The event queue offers some simple filtering. This can help performance
-slightly by blocking certain event types from the queue, use the
-``pygame.event.set_allowed()`` and ``pygame.event.set_blocked()`` to work with
-this filtering. All events default to allowed.
-
-The event subsystem should be called from the main thread.  If you want to post
-events into the queue from other threads, please use the fastevent package.
-
-Joysticks will not send any events until the device has been initialized.
-
-An Event object contains an event type and a readonly set of member data. The
-Event object contains no method functions, just member data. Event objects are
-retrieved from the pygame event queue. You can create your own new events with
-the ``pygame.event.Event()`` function.
-
-Your program must take steps to keep the event queue from overflowing. If the
-program is not clearing or getting all events off the queue at regular
-intervals, it can overflow. When the queue overflows an exception is thrown.
-
-All Event objects contain an event type identifier in the ``Event.type``
-member. You may also get full access to the Event's member data through the
-``Event.dict`` method. All other member lookups will be passed through to the
-Event's dictionary values.
-
-While debugging and experimenting, you can print the Event objects for a quick
-display of its type and members. Events that come from the system will have a
-guaranteed set of member items based on the type. Here is a list of the Event
-members that are defined with each type.
-
-::
-
-    QUIT	     none
-    ACTIVEEVENT	     gain, state
-    KEYDOWN	     unicode, key, mod
-    KEYUP	     key, mod
-    MOUSEMOTION	     pos, rel, buttons
-    MOUSEBUTTONUP    pos, button
-    MOUSEBUTTONDOWN  pos, button
-    JOYAXISMOTION    joy, axis, value
-    JOYBALLMOTION    joy, ball, rel
-    JOYHATMOTION     joy, hat, value
-    JOYBUTTONUP      joy, button
-    JOYBUTTONDOWN    joy, button
-    VIDEORESIZE      size, w, h
-    VIDEOEXPOSE      none
-    USEREVENT        code
-
-Events support equality comparison. Two events are equal if they are the same
-type and have identical attribute values. Inequality checks also work.
-
-.. versionadded:: 1.9.2
-
-    On MacOSX, USEREVENT can have `code = pygame.USEREVENT_DROPFILE`. That
-    means the user is trying to open a file with your application. The filename
-    can be found at `event.filename`
-
-.. function:: pump
-
-   | :sl:`internally process pygame event handlers`
-   | :sg:`pump() -> None`
-
-   For each frame of your game, you will need to make some sort of call to the
-   event queue. This ensures your program can internally interact with the rest
-   of the operating system. If you are not using other event functions in your
-   game, you should call ``pygame.event.pump()`` to allow pygame to handle
-   internal actions.
-
-   This function is not necessary if your program is consistently processing
-   events on the queue through the other :mod:`pygame.event` functions.
-
-   There are important things that must be dealt with internally in the event
-   queue. The main window may need to be repainted or respond to the system. If
-   you fail to make a call to the event queue for too long, the system may
-   decide your program has locked up.
-
-   .. ## pygame.event.pump ##
-
-.. function:: get
-
-   | :sl:`get events from the queue`
-   | :sg:`get() -> Eventlist`
-   | :sg:`get(type) -> Eventlist`
-   | :sg:`get(typelist) -> Eventlist`
-
-   This will get all the messages and remove them from the queue. If a type or
-   sequence of types is given only those messages will be removed from the
-   queue.
-
-   If you are only taking specific events from the queue, be aware that the
-   queue could eventually fill up with the events you are not interested.
-
-   .. ## pygame.event.get ##
-
-.. function:: poll
-
-   | :sl:`get a single event from the queue`
-   | :sg:`poll() -> Event`
-
-   Returns a single event from the queue. If the event queue is empty an event
-   of type ``pygame.NOEVENT`` will be returned immediately. The returned event
-   is removed from the queue.
-
-   .. ## pygame.event.poll ##
-
-.. function:: wait
-
-   | :sl:`wait for a single event from the queue`
-   | :sg:`wait() -> Event`
-
-   Returns a single event from the queue. If the queue is empty this function
-   will wait until one is created. The event is removed from the queue once it
-   has been returned. While the program is waiting it will sleep in an idle
-   state. This is important for programs that want to share the system with
-   other applications.
-
-   .. ## pygame.event.wait ##
-
-.. function:: peek
-
-   | :sl:`test if event types are waiting on the queue`
-   | :sg:`peek(type) -> bool`
-   | :sg:`peek(typelist) -> bool`
-
-   Returns true if there are any events of the given type waiting on the queue.
-   If a sequence of event types is passed, this will return True if any of
-   those events are on the queue.
-
-   .. ## pygame.event.peek ##
-
-.. function:: clear
-
-   | :sl:`remove all events from the queue`
-   | :sg:`clear() -> None`
-   | :sg:`clear(type) -> None`
-   | :sg:`clear(typelist) -> None`
-
-   Remove all events or events of a specific type from the queue. This has the
-   same effect as ``pygame.event.get()`` except nothing is returned. This can
-   be slightly more effecient when clearing a full event queue.
-
-   .. ## pygame.event.clear ##
-
-.. function:: event_name
-
-   | :sl:`get the string name from and event id`
-   | :sg:`event_name(type) -> string`
-
-   Pygame uses integer ids to represent the event types. If you want to report
-   these types to the user they should be converted to strings. This will
-   return a the simple name for an event type. The string is in the WordCap
-   style.
-
-   .. ## pygame.event.event_name ##
-
-.. function:: set_blocked
-
-   | :sl:`control which events are allowed on the queue`
-   | :sg:`set_blocked(type) -> None`
-   | :sg:`set_blocked(typelist) -> None`
-   | :sg:`set_blocked(None) -> None`
-
-   The given event types are not allowed to appear on the event queue. By
-   default all events can be placed on the queue. It is safe to disable an
-   event type multiple times.
-
-   If None is passed as the argument, this has the opposite effect and ``ALL``
-   of the event types are allowed to be placed on the queue.
-
-   .. ## pygame.event.set_blocked ##
-
-.. function:: set_allowed
-
-   | :sl:`control which events are allowed on the queue`
-   | :sg:`set_allowed(type) -> None`
-   | :sg:`set_allowed(typelist) -> None`
-   | :sg:`set_allowed(None) -> None`
-
-   The given event types are allowed to appear on the event queue. By default
-   all events can be placed on the queue. It is safe to enable an event type
-   multiple times.
-
-   If None is passed as the argument, ``NONE`` of the event types are allowed
-   to be placed on the queue.
-
-   .. ## pygame.event.set_allowed ##
-
-.. function:: get_blocked
-
-   | :sl:`test if a type of event is blocked from the queue`
-   | :sg:`get_blocked(type) -> bool`
-
-   Returns true if the given event type is blocked from the queue.
-
-   .. ## pygame.event.get_blocked ##
-
-.. function:: set_grab
-
-   | :sl:`control the sharing of input devices with other applications`
-   | :sg:`set_grab(bool) -> None`
-
-   When your program runs in a windowed environment, it will share the mouse
-   and keyboard devices with other applications that have focus. If your
-   program sets the event grab to True, it will lock all input into your
-   program.
-
-   It is best to not always grab the input, since it prevents the user from
-   doing other things on their system.
-
-   .. ## pygame.event.set_grab ##
-
-.. function:: get_grab
-
-   | :sl:`test if the program is sharing input devices`
-   | :sg:`get_grab() -> bool`
-
-   Returns true when the input events are grabbed for this application. Use
-   ``pygame.event.set_grab()`` to control this state.
-
-   .. ## pygame.event.get_grab ##
-
-.. function:: post
-
-   | :sl:`place a new event on the queue`
-   | :sg:`post(Event) -> None`
-
-   This places a new event at the end of the event queue. These Events will
-   later be retrieved from the other queue functions.
-
-   This is usually used for placing ``pygame.USEREVENT`` events on the queue.
-   Although any type of event can be placed, if using the sytem event types
-   your program should be sure to create the standard attributes with
-   appropriate values.
-
-   .. ## pygame.event.post ##
-
-.. function:: Event
-
-   | :sl:`create a new event object`
-   | :sg:`Event(type, dict) -> Event`
-   | :sg:`Event(type, **attributes) -> Event`
-
-   Creates a new event with the given type. The event is created with the given
-   attributes and values. The attributes can come from a dictionary argument
-   with string keys, or from keyword arguments. The event object exposes its
-   dictionary as attribute __dict__, and also as dict for backward
-   compatibility.
-
-   Attributes type, __dict__, and dict are readonly. Other attributes are
-   mutable. There are no methods attached to an Event object.
-
-   Mutable attributes are new to Pygame 1.9.2.
-
-   .. ## pygame.event.Event ##
-
-.. ## pygame.event ##

docs/_sources/ref/examples.txt

-.. include:: common.txt
-
-:mod:`pygame.examples`
-======================
-
-.. module:: pygame.examples
-   :synopsis: module of example programs
-
-| :sl:`module of example programs`
-
-These examples should help get you started with pygame. Here is a brief rundown
-of what you get. The source code for these examples is in the public domain.
-Feel free to use for your own projects.
-
-There are several ways to run the examples. First they can be run as
-stand-alone programs. Second they can be imported and their ``main()`` methods
-called (see below). Finally, the easiest way is to use the python -m option:
-
-::
-
-   python -m pygame.examples.<example name> <example arguments>
-
-eg:
-
-::
-
-   python -m pygame.examples.scaletest someimage.png
-
-Resources such as images and sounds for the examples are found in the 
-pygame/examples/data subdirectory.
-
-You can find where the example files are installed by using the following
-commands inside the python interpreter.
-
-::
-    
-   >>> import pygame.examples.scaletest
-   >>> pygame.examples.scaletest.__file__
-   '/usr/lib/python2.6/site-packages/pygame/examples/scaletest.py'
-
-On each OS and version of python the location will be slightly different.
-For example on windows it might be in 'C:/Python26/Lib/site-packages/pygame/examples/'
-On Mac OS X it might be in '/Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/pygame/examples/'
-
-
-You can also run the examples in the python interpreter by calling each modules main() function.
-
-::
-
-   >>> import pygame.examples.scaletest
-   >>> pygame.examples.scaletest.main()
-
-
-We're always on the lookout for more examples and/or example requests. Code
-like this is probably the best way to start getting involved with python
-gaming.
-
-examples as a package is new to pygame 1.9.0. But most of the examples came with
-pygame much earlier.
-
-.. function:: aliens.main
-
-   | :sl:`play the full aliens example`
-   | :sg:`aliens.main() -> None`
-
-   This started off as a port of the ``SDL`` demonstration, Aliens. Now it has
-   evolved into something sort of resembling fun. This demonstrates a lot of
-   different uses of sprites and optimized blitting. Also transparency,
-   colorkeys, fonts, sound, music, joystick, and more. (PS, my high score is
-   117! goodluck)
-
-   .. ## pygame.examples.aliens.main ##
-
-.. function:: oldalien.main
-
-   | :sl:`play the original aliens example`
-   | :sg:`oldalien.main() -> None`
-
-   This more closely resembles a port of the ``SDL`` Aliens demo. The code is a
-   lot simpler, so it makes a better starting point for people looking at code
-   for the first times. These blitting routines are not as optimized as they
-   should/could be, but the code is easier to follow, and it plays quick
-   enough.
-
-   .. ## pygame.examples.oldalien.main ##
-
-.. function:: stars.main
-
-   | :sl:`run a simple starfield example`
-   | :sg:`stars.main() -> None`
-
-   A simple starfield example. You can change the center of perspective by
-   leftclicking the mouse on the screen.
-
-   .. ## pygame.examples.stars.main ##
-
-.. function:: chimp.main
-
-   | :sl:`hit the moving chimp`
-   | :sg:`chimp.main() -> None`
-
-   This simple example is derived from the line-by-line tutorial that comes
-   with pygame. It is based on a 'popular' web banner. Note there are comments
-   here, but for the full explanation, follow along in the tutorial.
-
-   .. ## pygame.examples.chimp.main ##
-
-.. function:: moveit.main
-
-   | :sl:`display animated objects on the screen`
-   | :sg:`moveit.main() -> None`
-
-   This is the full and final example from the Pygame Tutorial, "How Do I Make
-   It Move". It creates 10 objects and animates them on the screen.
-
-   Note it's a bit scant on error checking, but it's easy to read. :]
-   Fortunately, this is python, and we needn't wrestle with a pile of error
-   codes.
-
-   .. ## pygame.examples.moveit.main ##
-
-.. function:: fonty.main
-
-   | :sl:`run a font rendering example`
-   | :sg:`fonty.main() -> None`
-
-   Super quick, super simple application demonstrating the different ways to
-   render fonts with the font module
-
-   .. ## pygame.examples.fonty.main ##
-
-.. function:: vgrade.main
-
-   | :sl:`display a vertical gradient`
-   | :sg:`vgrade.main() -> None`
-
-   Demonstrates creating a vertical gradient with pixelcopy and NumPy python.
-   The app will create a new gradient every half second and report the time
-   needed to create and display the image. If you're not prepared to start
-   working with the NumPy arrays, don't worry about the source for this one :]
-
-   .. ## pygame.examples.vgrade.main ##
-
-.. function:: eventlist.main
-
-   | :sl:`display pygame events`
-   | :sg:`eventlist.main() -> None`
-
-   Eventlist is a sloppy style of pygame, but is a handy tool for learning
-   about pygame events and input. At the top of the screen are the state of
-   several device values, and a scrolling list of events are displayed on the
-   bottom.
-
-   This is not quality 'ui' code at all, but you can see how to implement very
-   non-interactive status displays, or even a crude text output control.
-
-   .. ## pygame.examples.eventlist.main ##
-
-.. function:: arraydemo.main
-
-   | :sl:`show various surfarray effects`
-   | :sg:`arraydemo.main(arraytype=None) -> None`
-
-   Another example filled with various surfarray effects. It requires the
-   surfarray and image modules to be installed. This little demo can also make
-   a good starting point for any of your own tests with surfarray
-
-   If arraytype is provided then use that array package. Valid values are
-   'numeric' or 'numpy'. Otherwise default to NumPy, or fall back on Numeric if
-   NumPy is not installed. As a program ``surfarray.py`` accepts an optional
-   --numeric or --numpy flag. (New pygame 1.9.0)
-
-   .. ## pygame.examples.arraydemo.main ##
-
-.. function:: sound.main
-
-   | :sl:`load and play a sound`
-   | :sg:`sound.main(file_path=None) -> None`
-
-   Extremely basic testing of the mixer module. Load a sound and play it. All
-   from the command shell, no graphics.
-
-   If provided, use the audio file 'file_path', otherwise use a default file.
-