:mod:`pygame2.sdl.video` -- SDL video display wrapper module.
=============================================================

SDL video display wrapper module.

.. module:: pygame2.sdl.video
   :synopsis: SDL video display wrapper module.

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

  Gets the name of the video driver.

  Gets the name of the video driver or None, if the video system has
  not been initialised or it could not be determined.



.. function:: get_gammaramp () -> (int, int, ...), (int, int, ...), (int, int, ...)

  Gets the color gamma lookup tables for the display.

  Gets the color gamma lookup table for the display. This will
  return three tuples for the red, green and blue gamma values. Each
  tuple contains 256 values.



.. function:: get_info () -> dict

  Gets information about the video hardware.

  Gets information about the video hardware. The returned dictionary
  contains the following entries.

  +------------------+---------------------------------------------+
  | Entry            | Meaning                                     |
  +==================+=============================================+
  | hw_available     | Is it possible to create hardware surfaces? |
  +------------------+---------------------------------------------+
  | wm_available     | Is a window manager available?              |
  +------------------+---------------------------------------------+
  | blit_hw          | Are hardware to hardware blits accelerated? |
  +------------------+---------------------------------------------+
  | blit_hw_CC       | Are hardware to hardware colorkey blits     |
  |                  | accelerated?                                |
  +------------------+---------------------------------------------+
  | blit_hw_A        | Are hardware to hardware alpha blits        |
  |                  | accelerated?                                |
  +------------------+---------------------------------------------+
  | blit_sw          | Are software to hardware blits accelerated? |
  +------------------+---------------------------------------------+
  | blit_sw_CC       | Are software to hardware colorkey blits     |
  |                  | accelerated?                                |
  +------------------+---------------------------------------------+
  | blit_sw_A        | Are software to hardware alpha blits        |
  |                  | accelerated?                                |
  +------------------+---------------------------------------------+
  | blit_fill        | Are color fills accelerated?                |
  +------------------+---------------------------------------------+
  | video_mem        | Total amount of video memory in Kilobytes   |
  +------------------+---------------------------------------------+
  | vfmt             | Pixel format of the video device            |
  +------------------+---------------------------------------------+



.. function:: get_videosurface () -> Surface

  Gets the current display surface or None, if there is no such Surface.



.. function:: init () -> None

  Initializes the video subsystem of the SDL library.



.. function:: is_mode_ok (width, height[, bpp, flags]) -> bool
              is_mode_ok (size[, bpp, flags]) -> bool

  Checks, whether the requested video mode is supported.

  Checks, whether the video mode is supported for the passed *size*,
  bit depth and *flags*. If the bit depth (*bpp*) argument is omitted,
  the current screen bit depth will be used.

  The optional *flags* argument is the same as for :meth:`set_mode`.



.. function:: list_modes ([, format, flags]) -> [rect, rect, ...]

  Returns the supported modes for a specific format and flags.

  Returns the supported modes for a specific *format* and *flags*.
  The optional *format* argument must be a :class:`PixelFormat`
  instance with the desired mode information. The optional *flags*
  argument is the same as for :meth:`set_mode`.

  If both, the *format* and *flags* are omitted, all supported screen
  resolutions for all supported formats and flags are returned.



.. function:: quit () -> None

  Shuts down the video subsystem of the SDL library.

  After calling this function, you should not invoke any class,
  method or function related to the video subsystem as they are
  likely to fail or might give unpredictable results.



.. function:: set_gamma (red, green, blue) -> None

  Sets the gamma values for all three color channels.

  Sets the gamma values for all three color channels. In case
  adjusting the gamma is not supported, an exception will be raised.



.. function:: set_gammaramp (redtable, greentable, bluetable) -> None

  Sets the color gamma lookup tables for the display.

  Sets the color gamma lookup table for the display. The three
  arguments must be sequences with 256 integer value enties for the
  gamma ramps.



.. function:: set_mode (width, height[, bpp, flags]) -> Surface
              set_mode (size[, bpp, flags]) -> Surface

  Creates the main display Surface.

  Creates the main display Surface using the specified *size*, bit
  depth and *flags*. If the bit depth (*bpp*) argument is omitted, the
  current screen bit depth will be used.

  The optional *flags* argument can be a bitwise OR'd combination of
  the surface flags from the :mod:`pygame2.sdl.constants`.



.. function:: was_init () -> bool

  Returns, whether the video subsystem of the SDL library is initialized.



Overlay
-------
.. class:: Overlay (surface, width, height, format) -> Overlay
      Overlay (surface, size, format) -> Overlay
    

  Creates a new Overlay for a surface.

  The Overlay objects provide support for accessing hardware video
  overlays. Video overlays do not use standard RGB pixel formats, and can
  use multiple resolutions of data to create a single image.

  The Overlay objects represent lower level access to the display
  hardware. To use the object you should understand the technical details
  of video overlays.

  The Overlay *format* determines the type of pixel data used. Not all
  hardware will support all types of overlay formats. Supported
  *format* types are listed in the :mod:`pygame2.sdl.constants`
  module.

  The *width* and *height* arguments control the size for the overlay image
  data. The overlay image can be displayed at any size, not just the
  resolution of the overlay and are always visible, and always show above
  the regular display contents.


Attributes
^^^^^^^^^^
.. attribute:: Overlay.format

  Gets the format of the Overlay.

.. attribute:: Overlay.h

  Gets the height of the Overlay.

.. attribute:: Overlay.height

  Gets the height of the Overlay.

.. attribute:: Overlay.hw_overlay

  Gets, whether the Overlay is hardware accelerated.

.. attribute:: Overlay.locked

  Gets, whether the Overlay is currently locked.

.. attribute:: Overlay.pitches

  Gets the pitches (length in bytes) for all planes of the
  Overlay.

.. attribute:: Overlay.pixels

  Gets the pixel buffers for all planes of the Overlay.

.. attribute:: Overlay.planes

  Get the amount of planes for the Overlay.

.. attribute:: Overlay.size

  Gets the width and height of the Overlay.

.. attribute:: Overlay.w

  Gets the width of the Overlay.

.. attribute:: Overlay.width

  Gets the width of the Overlay.

Methods
^^^^^^^
.. method:: Overlay.display ([rect]) -> None

  Displays the current overlay data in the SDL overlay plane.


.. method:: Overlay.lock () -> None

  Locks the Overlay for a direct access to its internal pixel data.


.. method:: Overlay.unlock () -> None

  Unlocks the Overlay, releasing the direct access to the pixel data.


PixelFormat
-----------
.. class:: PixelFormat () -> PixelFormat

  Creates a new, empty PixelFormat.

  The PixelFormat typically describes a :class:`Surface`'s pixel buffer
  representation. It contains information about the bit depth, RGBA masks,
  the palette and transparency information.


Attributes
^^^^^^^^^^
.. attribute:: PixelFormat.alpha

  Gets or sets the overall surface alpha value in the
  range [0, 255].

.. attribute:: PixelFormat.bits_per_pixel

  Gets or sets the bits per pixel to use for
  storing a RGBA value.

.. attribute:: PixelFormat.bytes_per_pixel

  Gets or sets the bytes per pixel to use for
  storing a RGBA value.

.. attribute:: PixelFormat.colorkey

  Gets or sets the RGBA value of transparent pixels.

.. attribute:: PixelFormat.losses

  Gets or sets the precision loss of each RGBA color
  component.

.. attribute:: PixelFormat.masks

  Gets or sets the binary masks used to retrieve individual
  color values.

.. attribute:: PixelFormat.palette

  Gets the color palette (if any) used by the PixelFormat. If the
  PixelFormat does not have any palette, None will be returned.

.. attribute:: PixelFormat.readonly

  Gets, whether the PixelFormat is read-only (this cannot be
  changed).

.. attribute:: PixelFormat.shifts

  Gets the binary left shift of each color component in
  the pixel value.

Methods
^^^^^^^
.. method:: PixelFormat.get_rgba (color) -> :class:`pygame2.Color`

  Gets the best matching :class:`pygame2.Color` for the passed color.

  Gets a color value, which fits the PixelFormat best. This means
  that an internal conversion is done (on demand) to match the
  passed color to the PixelFormat's supported value ranges. If
  the PixelFormat does not have alpha transparency support, the
  color's alpha value will be set to fully opaque (255).


.. method:: PixelFormat.map_rgba (r, g, b[, a]) -> long
            PixelFormat.map_rgba (color) -> long

  Converts a color to the best value matching the format.

  Gets a color value, which fits the PixelFormat best. This means
  that an internal conversion is done (on demand) to match the
  passed color to the PixelFormat's supported value ranges.
  Instead of returning a color as in :meth:`get_rgba`, an integer value
  matching the PixelFormat's supported value ranges will be
  returned.


Surface
-------
.. class:: Surface (width, height[, depth, flags, masks]) -> Surface
      Surface (size[, depth, flags, masks]) -> Surface
    

  Creates a new Surface to represent image data.

  Creates a new Surface which represents a rectangular area of pixel
  information, typically displaying some sort of image data. The Surface is
  the central element of the :mod:`pygame2.sdl.video` module and used to
  display image information on an SDL screen window.


Attributes
^^^^^^^^^^
.. attribute:: Surface.clip_rect

  Gets or sets the current clipping rectangle for
  operations on the Surface.

.. attribute:: Surface.flags

  The currently set flags for the Surface.

.. attribute:: Surface.format

  Gets the (read-only) :class:`PixelFormat` for this Surface.

.. attribute:: Surface.h

  Gets the height of the Surface.

.. attribute:: Surface.height

  Gets the height of the Surface.

.. attribute:: Surface.locked

  Gets, whether the Surface is currently locked.

.. attribute:: Surface.pitch

  Get the length of a surface scanline in bytes.

.. attribute:: Surface.pixels

  Gets the pixel buffer of the Surface.

.. attribute:: Surface.size

  Gets the size of the Surface.

.. attribute:: Surface.w

  Gets the width of the Surface.

.. attribute:: Surface.width

  Gets the width of the Surface.

Methods
^^^^^^^
.. method:: Surface.blit (srcsurface[, destrect, srcrect, blendargs]) -> Rect

  Draws the passed source surface onto this surface.

  Draws the passed source surface onto this surface. The *destrect* and
  *srcrect* arguments are used for clipping the destination area (on this
  surface) and source area (on the source surface). For the destination
  rectangle, the width and height are ignored, only the position is taken
  into account. For the source rectangle, all values, position as well as
  the size are used for clipping.

  The optional *blendargs* for the drawing operation perform  certain
  specialised pixel manipulations. For those, pixels on the same
  position are evaluated and the result manipulated according to the
  argument.

  For all supported blending operations take a look at the blending
  constants in the :mod:`pygame2.sdl.constants` module.


.. method:: Surface.copy () -> Surface

  Creates an exact copy of the Surface and its image data.


.. method:: Surface.convert ([pixelformat, flags]) -> Surface

  Converts the Surface to the desired pixel format.

  Converts the Surface to the desired pixel format. If no format
  is given, the active display format is used, which will be the fastest
  for blit operations to the screen. The flags are the same as for surface
  creation.

  This creates a new, converted surface and leaves the original one
  untouched.


.. method:: Surface.fill (color[, dstrect, blendargs]) -> None

  Fills the Surface with a color.

  Fills the Surface with the desired color. The color does not
  need to  match the Surface's format, it will be converted
  implicitly to the nearest appropriate color for its format.

  The optional destination rectangle limits the color fill to the
  specified area. The blendargs are the same as for the :meth:`blit`
  operation, but compare the color with the specific Surface pixel value.


.. method:: Surface.flip () -> None

  Swaps the screen buffers for the Surface.

  Swaps screen buffers for the Surface, causing a full update and redraw
  of its whole area.


.. method:: Surface.get_alpha () -> int

  Gets the current overall alpha value of the Surface.

  Gets the current overall alpha value of the Surface. In case the
  surface does not support alpha transparency (SRCALPHA flag not set),
  None will be returned.


.. method:: Surface.get_at (x, y) -> Color
            Surface.get_at (point) -> Color

  Gets the Surface pixel value at the specified point.


.. method:: Surface.get_colorkey () -> Color

  Gets the colorkey for the Surface.

  Gets the colorkey for the Surface or None in case it has no colorkey
  (SRCCOLORKEY flag not set).


.. method:: Surface.get_palette () -> (Color, Color, ...)

  Gets the palette colors used by the Surface.

  Gets the palette colors used by the Surface or None, if the Surface
  does not use any palette.


.. method:: Surface.lock () -> None

  Locks the Surface for a direct access to its internal pixel data.


.. method:: Surface.save (file[, type]) -> None

  Saves the Surface to a file.

  Saves the Surface to a file. The file argument can be either a
  file name or a file-like object to save the Surface to. The
  optional type argument is required, if the file type cannot be
  determined by the suffix.

  Currently supported file types (suitable to pass as string for
  the type argument) are:

  * BMP
  * TGA
  * PNG
  * JPEG (JPG)

  If no type information is supplied and the file type cannot be
  determined either, it will use TGA.

  .. note::

            The file object *must* support binary read and write
            access. This is especially important for Python 3.x users.


.. method:: Surface.scroll ([dx, dy]) -> None

  Scrolls the Surface in place.

  Move the Surface contents by *dx* pixels right and *dy* pixels
  down. dx and dy may be negative for left and up scrolls
  respectively. Areas of the surface that are not overwritten
  retain their original pixel values. Scrolling is contained by
  the Surface clip area. It is safe to have *dx* and *dy* values
  that exceed the surface size.


.. method:: Surface.set_alpha (alpha[, flags]) -> None

  Adjusts the alpha properties of the Surface.

  TODO


.. method:: Surface.set_at (x, y, color) -> None
            Surface.set_at (point, color) -> None

  Sets the Surface pixel value at the specified point.


.. method:: Surface.set_colorkey (color[, flags]) -> None

  Adjusts the colorkey of the Surface.

  Sets the colorkey of the Surface to the passed value. if *flags* is
  omitted, SRCCOLORKEY will be used, if *flags* is set to 0, the colorkey
  will be reset.

  The colorkey denotes a certain :class:`pygame2.Color`, which will be
  used for emulating transparency. Each pixel on the Surface matching the
  set color will be ignored on blit operations.


.. method:: Surface.set_colors ((color1, color2, ...)[, first]) -> bool

  Sets a portion of the colormap palette for the 8-bit Surface.

  Sets a portion of the colormap palette for the 8-bit Surface,
  starting at the desired first position. If the first position
  plus length of the passed colormap exceeds the Surface palette
  size, the palette will be unchanged and False returned.

  If any other error occurs, False will be returned and the
  Surface palette should be inspected for any changes.


.. method:: Surface.set_palette ((color1, color2, ...)[, flags, first]) -> bool

  Sets a portion of the palette for the given 8-bit surface.

  Sets a portion of the color palette for the 8-bit Surface,
  starting at the desired *first* position. If the *first* position
  plus length of the passed colormap exceeds the Surface palette
  size, the palette will be unchanged and False returned.

  If *flags* is omitted and a Surface with hardware palette used, both
  the physical and logical palettes will be modified. Otherwise, *flags*
  can be set to LOGPAL or PHYSPAL or a combination to modify either the
  logical, physical or both palettes.

  If any other  error occurs, False will be returned and the Surface
  palette should be inspected for any changes.


.. method:: Surface.unlock () -> None

  Unlocks the Surface, releasing the direct access to the pixel data.


.. method:: Surface.update ([rect]) -> None
            Surface.update ([(rect1, rect2, ...)]) -> None

  Updates the given area on the Surface.

  Upates the given area (or areas, if a list of rects is passed)
  on the Surface, performing partial screen buffer swaps.
  For smaller portions of the Surface, this is much faster than running
  :meth:`flip`.



