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
Both flags are only a request, and may not be possible for all
displays and formats.
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.
-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.
-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. A surface alpha of 255
is opaque, and a value of 0 is completely transparent.
+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.
+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. A surface alpha of 255
is opaque, and a value of 0 is completely transparent.
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.
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
pygame.surfarray module, which can treat the surfaces like large
multidimensional arrays (and it's quite quick).
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.