Hi, here is a minor patch to the surface docs.
//Lorenz
Index: src/surface.doc =================================================================== --- src/surface.doc (revision 2482) +++ src/surface.doc (working copy) @@ -28,8 +28,9 @@ Surfaces can have many extra attributes like alpha planes, colorkeys, source rectangle clipping. These functions mainly effect how the Surface is blitted -to other Surfaces. The blit routines will attempt to use hardware acceleratio - when possible, otherwise will use highly optimized software blitting methods. +to other Surfaces. The blit routines will attempt to use hardware acceleration +when possible, otherwise they will use highly optimized software blitting +methods. There are three types of transparency supported in Pygame: colorkeys, surface alphas, and pixel alphas. Surface alphas can be mixed with colorkeys, Index: docs/ref/surface.html =================================================================== --- docs/ref/surface.html (revision 2482) +++ docs/ref/surface.html (working copy) @@ -109,9 +109,8 @@ SRCALPHA, the pixel format will include a per-pixel alpha </pre><p>Both flags are only a request, and may not be possible for all displays and formats. </p> <p>Advance users can combine a set of bitmasks with a depth value. The masks are a set of 4 integers representing which bits in a pixel will represent each color. Normal Surfaces should not require the masks argument. </p> -<p>Surfaces can have many extra attributes like alpha planes, colorkeys, source rectangle clipping. These functions mainly effect how the Surface is blitted to other Surfaces. The blit routines will attempt to use hardware acceleratio </p> -<pre> when possible, otherwise will use highly optimized software blitting methods. -</pre><p>There are three types of transparency supported in Pygame: colorkeys, surface alphas, and pixel alphas. Surface alphas can be mixed with colorkeys, but an image with per pixel alphas cannot use the other modes. Colorkey transparency makes a single color value transparent. Any pixels matching the colorkey will not be drawn. The surface alpha value is a single value that changes the transparency for the entire image. <tt>A</tt> surface alpha of 255 is opaque, and a value of 0 is completely transparent. </p> +<p>Surfaces can have many extra attributes like alpha planes, colorkeys, source rectangle clipping. These functions mainly effect how the Surface is blitted to other Surfaces. The blit routines will attempt to use hardware acceleration when possible, otherwise they will use highly optimized software blitting methods. </p> +<p>There are three types of transparency supported in Pygame: colorkeys, surface alphas, and pixel alphas. Surface alphas can be mixed with colorkeys, but an image with per pixel alphas cannot use the other modes. Colorkey transparency makes a single color value transparent. Any pixels matching the colorkey will not be drawn. The surface alpha value is a single value that changes the transparency for the entire image. <tt>A</tt> surface alpha of 255 is opaque, and a value of 0 is completely transparent. </p> <p>Per pixel alphas are different because they store a transparency value for every pixel. This allows for the most precise transparency effects, but it also the slowest. Per pixel alphas cannot be mixed with surface alpha and colorkeys. </p> <p>There is support for pixel access for the Surfaces. Pixel access on hardware surfaces is slow and not recommended. Pixels can be accessed using the get_at() and set_at() functions. These methods are fine for simple access, but will be considerably slow when doing of pixel work with them. If you plan on doing a lot of pixel level work, it is recommended to use the <tt>pygame.surfarray</tt> module, which can treat the surfaces like large multidimensional arrays (and it's quite quick). </p> <p>Any functions that directly access a surface's pixel data will need that surface to be lock()'ed. These functions can lock() and unlock() the surfaces themselves without assistance. But, if a function will be called many times, there will be a lot of overhead for multiple locking and unlocking of the surface. It is best to lock the surface manually before making the function call many times, and then unlocking when you are finished. All functions that need a locked surface will say so in their docs. Remember to leave the Surface locked only while necessary. </p>
