pygame / doc / src / sdlextbase.xml

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

<module name="pygame2.sdlext.base">
  <alias>pygame2.sdlext</alias>
  <short>basic extensions for SDL modules</short>
  <desc>
    Extension module for the pygame2 SDL wrapper.
  </desc>

  <class name="PixelArray">
    <constructor>PixelArray (surface) -> PixelArray</constructor>
    <desc>
      Creates a new PixelArray from the specified
      :class:`pygame2.sdl.video.Surface`.

      The :class:`PixelArray` wraps up a
      :class:`pygame2.sdl.video.Surface` and provides a direct 2D array
      access to its pixels using the surface its rows as first and its
      columns as second axis. It supports slicing, row and pixel
      manipluation, slicing and slice assignments while inplace
      operations such as addition, subtraction, multiplication, division
      and so forth are not allowed.

      While it is possible to assign both, integer color values and
      RGB(A) color tuples, the :class:`PixelArray` will only use
      integers for the color representation. Thus, checking for certain
      colors has to be done using the
      :meth:`pygame2.sdl.video.Surface.map_rgb()` method of the surface,
      the :class:`PixelArray` was created for. ::

        pxarray = pygame.PixelArray (surface)
        # Check, if the first pixel at the topleft corner is blue
        if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):
            ...
      
      If you operate on a slice, you also can use arbitrary sequences or
      other PixelArray objects to modify the pixels. They have to match
      the size of the PixelArray however. ::

        pxarray[a:b] = 0xFF00FF                   # set all pixels to 0xFF00FF
        pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # first pixel = 0xFF00FF,
        # second pixel  = 0xAACCEE, ...
        pxarray[a:b] = ((255, 0, 255), (170, 204, 238), ...) # same as above
        pxarray[a:b] = ((255, 0, 255), 0xAACCEE, ...)        # same as above
        pxarray[a:b] = otherarray[x:y]            # slice sizes must match

      Note, that something like ::

        pxarray[2:4][3:5] = ...

      will not cause a rectangular manipulation. Instead it will be
      first sliced to a two-column array, which then shall be sliced by
      columns once more, which will fail due an IndexError. This is
      caused by the slicing mechanisms in python and an absolutely
      correct behaviour. Create a single columned slice first, which you
      can manipulate then: ::

        pxarray[2][3:5] = ...
        pxarray[3][3:5] = ...

      If you want to make a rectangular manipulation or create a view of
      a part of the PixelArray, you also can use the subscript
      abilities. You can easily create different view by creating
      'subarrays' using the subscripts. ::

        # Create some new PixelArray objects providing a different view
        # of the original array/surface.
        newarray = pxarray[2:4,3:5]
        otherarray = pxarray[::2,::2]

      Subscripts also can be used to do fast rectangular pixel
      manipulations instead of iterating over the x or y axis as above. ::

        pxarray[::2,:] = (0, 0, 0)                # Make each second column black.

      During its lifetime, the PixelArray locks the surface, thus you
      explicitly have to delete it once its not used anymore and the
      surface should perform operations in the same scope.
    </desc>
    <method name="compare">
      <call>compare (array, distance=0, weights=(0.299, 0.587, 0.114)) -> PixelArray</call>
      <desc>
        Compares the :class:`PixelArray` with another one.

        Compares the contents of the :class:`PixelArray` with those from the
        passed :class:`PixelArray`. It returns a new :class:`PixelArray` with a
        black/white color mask that indicates the differences (white) of
        both arrays. Both :class:`PixelArray` objects must have indentical bit
        depths and dimensions.

        It uses a simple weighted euclidian distance formula to
        calculate the distance between the colors. The distance space
        ranges from 0.0 to 1.0 and is used as threshold for the color
        detection. This causes the comparision to mark pixels with a
        similar, but not exactly identical color, as black.
      </desc>
    </method>
    <method name="extract">
      <call>extract (color, distance=0, weights=(0.299, 0.587, 0.114)) -> PixelArray</call>
      <desc>
        Extracts the passed color from the :class:`PixelArray`.

        Extracts the passed color by changing all matching pixels to
        white, while non-matching pixels are changed to black. This
        returns a new :class:`PixelArray` with the black/white color mask. It
        uses a simple weighted euclidian distance formula to calculate
        the distance between the colors. The distance space ranges from
        0.0 to 1.0 and is used as threshold for the color detection.
        This causes the extraction to take pixels with a similar, but
        not exactly identical color, into account as well.
      </desc>
    </method>
    <method name="make_surface">
      <call>make_surface () -> pygame2.sdl.Surface</call>
      <desc>
        Creates a new Surface from the current :class:`PixelArray`.

        Creates a new Surface from the current :class:`PixelArray`. Depending on
        the current PixelArray the size, pixel order etc. will be
        different from the original :class:`pygame2.sdl.video.Surface`. ::

          # Create a new surface flipped around the vertical axis.
          sf = pxarray[:,::-1].make_surface ()
      </desc>
    </method>
    <method name="replace">
      <call>replace (color, repcolor, distance=0, weights=(0.299, 0.587, 0.114)) -> None</call>
      <desc>
        Replaces the passed color in the :class:`PixelArray` with another one.

        Replaces the pixels with the passed color in the :class:`PixelArray` by
        changing them them to the passed replacement color. It uses a
        simple weighted euclidian distance formula to calculate the
        distance between the colors. The distance space ranges from 0.0
        to 1.0 and is used as threshold for the color detection. This
        causes the replacement to take pixels with a similar, but not
        exactly identical color, into account as well.

        This is an in place operation that directly affects the pixels
        of the :class:`PixelArray`.
      </desc>
    </method>
    <attr name="surface">
      <desc>Gets the Surface the :class:`PixelArray` uses.</desc>
    </attr>
  </class>

</module>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.