[pygame] Help: improve new module documentation. Read this, and give me comments.

["René Dudfield" <renesd@xxxxxxxxx>]

Hello,

There is a new module going into pygame called mask - for per pixel
collision detection and 1 bit per pixel representation of Surfaces.

However the documentation could do with some more work.  So comments please?

Here it is, at this link:
http://rene.f0o.com/~rene/stuff/mask.txt


Or I've pasted the docs it below.


Cheers!





pygame.mask
pygame module for image masks.

Useful for fast pixel perfect collision detection.  A Mask uses 1bit per
pixel to store which parts collide.

New in pygame 1.8.

<SECTION>


pygame.mask.from_surface
Returns a Mask from the given surface.
pygame.mask.from_surface(Surface, threshold = 127) -> Mask

Makes the transparent parts of the Surface not set, and the opaque parts set.

The alpha of each pixel is checked to see if it is greater than the
given threshold.

If the Surface is color keyed, then threshold is not used.

<END>


pygame.Mask
pygame object for representing 2d bitmasks
pygame.Mask((width, height): return Mask
<END>


get_size
Returns the size of the mask.
Mask.get_size() -> width,height
<END>


get_at
Returns nonzero if the bit at (x,y) is set.
Mask.get_at((x,y)) -> int

Coordinates start at (0,0) is top left - just like Surfaces.
<END>


set_at
Sets the position in the mask given by x and y.
Mask.set_at((x,y),value)


<END>



overlap
Returns the point of intersection if the masks overlap with the given
offset - or None if it does not overlap.
Mask.overlap(othermask, offset) -> x,y

The overlap tests uses the following offsets (which may be negative):

   +----+----------..
   |A   | yoffset
   |  +-+----------..
   +--|B
   |xoffset
   |  |
   :  :

<END>


overlap_area
Returns the number of overlapping 'pixels'.
Mask.overlap_area(othermask, offset) -> numpixels

You can see how many pixels overlap with the other mask given.
This can be used to see in which direction things collide, or to see
how much the two masks collide.

<END>


get_bounding_rects
Returns a list of bounding rects of regions of set pixels.
Mask.get_bounding_rects() -> Rects

This gets a bounding rect of connected regions of set pixels.
A bounding rect is one for which each of the connected pixels is
inside the rect.

<END>




<END>