:mod:`pygame2.sdlext.transform` -- SDL surface transformation algorithms
========================================================================

SDL surface transformation algorithms

A surface transform is an operation that moves or resizes the pixels. All
these functions take a surface to operate on and return a new surface with
the results.

Some of the transforms are considered destructive. This means every time
they are performed they lose pixel data. Common examples of this are
resizing and rotating. For this reason, it is better to retransform the
original surface than to keep transforming an image multiple times.
(For example, suppose you are animating a bouncing spring which expands and
contracts. If you applied the size changes incrementally to the previous
images, you would lose detail. Instead, always begin with the original
image and scale to the desired size.)


.. module:: pygame2.sdlext.transform
   :synopsis: SDL surface transformation algorithms

Module Functions
----------------
.. function:: average_color (surface[, rect]) -> Color

  Finds the average color of a surface.

  Finds the average color of a :class:`pygame2.sdl.video.Surface` and
  returns it. The optional *rect* argument can be used to find the average
  color for a specific region on the :class:`pygame2.sdl.video.Surface`.



.. function:: average_surfaces ((surface1, surface2, ...)[, destsurface]) -> Surface

  Creates a new surface with the average colors from a list of surfaces.

  This finds the average color for each of the passed surfaces and creates
  a new :class:`pygame2.sdl.video.Surface` with those colors. If a
  destination surface is passed, it will be used instead of creating a new
  :class:`pygame2.sdl.video.Surface`.

  .. note::

          The destination surface must have the same size as the largest
          :class:`pygame2.sdl.video.Surface` of the passed list.



.. function:: chop (surface, rect) -> Surface

  Extracts a portion of a surface.

  Extracts a portion of a *surface*. All vertical and horizontal pixels
  surrounding the given rectangle area are removed. The corner areas
  (diagonal to the *rect*) are then brought together and the result will be
  returned as a new :class:`pygame2.sdl.video.Surface`

  .. note::

          If you want a "crop" that returns the part of an image within a
          rect, you can blit with a rect to a new surface.



.. function:: flip (surface, flipx, flipy) -> Surface

  Flips a surface horizontically, vertically or over both axes.

  This can flip a *surface* either vertically, horizontally, or both.
  Flipping a Surface is nondestructive and returns a new
  :class:`pygame2.sdl.video.Surface` with the same dimensions.



.. function:: get_filtertype () -> int

  Gets the currently set filter type.



.. function:: set_filtertype (type) -> int

  Tries to apply a certain filter mechanism to use.

  Tries to apply a certain filter mechanism for the :func:`smoothscale`
  function. Depending on which architecture and how Pygame2 was built,
  not all available filters from :mod:`pygame2.sdlext.constants` might
  be supported. In case the passed *type* is not supported for the
  executing system, the filter type will be automatically set back to
  :const:`FILTER_C`.

  The return value will be the effective filter type used.



.. function:: laplacian (surface[, destsurface]) -> Surface

  Finds the edges in a surface using the laplacian algorithm.

  Finds the edges in a *surface* using the laplacian algorithm. If a
  destination surface is provided, it will be used for drawing the results
  instead of creating a new :class:`pygame2.sdl.video.Surface`.

  .. note::

          The destination surface must have the same size as the *surface* to
          find the edges in.



.. function:: rotate (surface, angle) -> Surface

  Rotates a surface.

  Rotates a *surface* using the specified *angle* in degrees. For positive
  angles, the rotation will be counterclockwise, negative angles will cause
  a clockwise rotation.

  Unless rotating by 90 degree increments, the *surface* will be padded
  larger to hold the new size. If the image has pixel alphas, the padded
  area will be transparent. Otherwise a color will picked that matches the
  surface colorkey or the topleft pixel value.



.. function:: scale (surface, width, height[, destsurface]) -> Surface
              scale (surface, size[, destsurface]) -> Surface

  Resizes the surface to a new resolution.

  This is a fast scale operation that does not sample the results. An
  optional destination surface can be used, rather than have it create a
  new one. This is faster if you want to repeatedly scale something.

  .. note::

           The destination surface must cover the size of the scaled result
           and feature the same format.



.. function:: scale (surface[, destsurface]) -> Surface

  Scales a surface to the double of its original size.

  This will return a new :class:`pygame2.sdl.video.Surface` that is double
  the size of the original. It uses the AdvanceMAME Scale2X algorithm which
  does a 'jaggie-less' scale of bitmap graphics.

  This really only has an effect on simple images with solid colors. On
  photographic and antialiased images it will look like a regular
  unfiltered scale. An optional destination surface can be used, rather
  than to have it create a new one. This is faster if you want to
  repeatedly scale something.

  .. note::

           The destination surface must be twice the size of the *surface*
           passed in and feature the same format.



.. function:: smoothscale (surface, width, height[, destsurface]) -> Surface
              smoothscale (surface, size[, destsurface]) -> Surface

  Resizes the surface to a new resolution using smoothing algorithms.

  Uses one of two different algorithms for scaling each dimension of the
  input surface as required. For shrinkage, the output pixels are area
  averages of the colors they cover. For expansion, a bilinear filter is
  used.

  For AMD64 and i686 architectures, optimized MMX and SSE filter routines
  are included and will run much faster than other machine types. The filter
  routines can be get and set using :func:`get_filtertype` and
  :func:`set_filtertype`

  This function only works for 24-bit or 32-bit surfaces. An exception will
  be thrown if the input surface bit depth is less than 24.

  .. note::

          The destination surface must cover the size of the scaled result
          and feature the same format.



.. function:: threshold (surface, color, threscolor[, destsurface]) -> Surface
              threshold (surface, colorsurface, threscolor[, destsurface]) -> Surface

  TODO



