Source

pygame / doc / src / sdlextbase.xml

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

<module name="pygame2.sdlext.base">
  <show>0</show>
  <alias>pygame2.sdlext</alias>
  <short>basic extensions for SDL modules</short>
  <desc>
    Basic extensions 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 PixelArray wraps up a :class:`pygame2.sdl.video.Surface` and provides
      a direct 2D array access to its pixels using the surface's columns as
      first and its rows as second axis. It supports slicing and row and pixel
      manipluation while in place 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 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 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 behavior. 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 views 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 it is 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 PixelArray with another one.

        Compares the contents of the PixelArray with those from the
        passed PixelArray. It returns a new PixelArray with a
        black/white color mask that indicates the differences (white) of
        both arrays. Both 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 PixelArray.

        Extracts the passed *color* by changing all matching pixels to
        white, while non-matching pixels are changed to black. This
        returns a new 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 () -> :class:`pygame2.sdl.video.Surface`</call>
      <desc>
        Creates a new :class:`pygame2.sdl.video.Surface` from the current
        PixelArray.

        Creates a new :class:`pygame2.sdl.video.Surface` from the current
        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 PixelArray with another one.

        Replaces the pixels with the passed *color* in the 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 PixelArray.
      </desc>
    </method>
    <attr name="surface">
      <desc>Gets the :class:`pygame2.sdl.video.Surface` the PixelArray uses.</desc>
    </attr>
  </class>

</module>