Source

pygame / doc / src / sdlexttransform.xml

Full commit
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE module SYSTEM "api.dtd">

<module name="pygame2.sdlext.transform">
  <short>SDL surface transformation algorithms</short>
  <desc>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.)
  </desc>

  <func name="average_color">
    <call>average_color (surface[, rect]) -> Color</call>
    <desc>
      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`.
    </desc>
  </func>
  <func name="average_surfaces">
    <call>average_surfaces ((surface1, surface2, ...)[, destsurface]) -> Surface</call>
    <desc>
      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.
    </desc>
  </func>
  <func name="chop">
    <call>chop (surface, rect) -> Surface</call>
    <desc>
      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.
    </desc>
  </func>
  <func name="flip">
    <call>flip (surface, flipx, flipy) -> Surface</call>
    <desc>
      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. 
    </desc>
  </func>
  <func name="get_filtertype">
    <call>get_filtertype () -> int</call>
    <desc>
      Gets the currently set filter type.
    </desc>
  </func>
  <func name="set_filtertype">
    <call>set_filtertype (type) -> int</call>
    <desc>
      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.
    </desc>
  </func>
  <func name="laplacian">
    <call>laplacian (surface[, destsurface]) -> Surface</call>
    <desc>
      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.
    </desc>
  </func>
  <func name="rotate">
    <call>rotate (surface, angle) -> Surface</call>
    <desc>
      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.
    </desc>
  </func>
  <func name="scale">
    <call>scale (surface, width, height[, destsurface]) -> Surface
      scale (surface, size[, destsurface]) -> Surface
    </call>
    <desc>
       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.
    </desc>
  </func>
  <func name="scale2x">
    <call>scale (surface[, destsurface]) -> Surface</call>
    <desc>
      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.
    </desc>
  </func>
  <func name="smoothscale">
    <call>smoothscale (surface, width, height[, destsurface]) -> Surface
      smoothscale (surface, size[, destsurface]) -> Surface
    </call>
    <desc>
      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.
    </desc>
  </func>
  <func name="threshold">
    <call>threshold (surface, color, threscolor[, destsurface]) -> Surface
      threshold (surface, colorsurface, threscolor[, destsurface]) -> Surface
    </call>
    <desc>TODO</desc>
  </func>
</module>