Surface

pygame documentation

|| Home || Help Contents ||

|| pygame || cdrom || constants || cursor || display || draw ||
|| event || font || image || joystick || key || mixer ||
|| mixer_music || mouse || movie || sndarray || surfarray || time ||
|| transform ||

|| CD || Channel || Clock || Font || Joystick || Movie ||
|| Overlay || Rect || Sound || Surface ||

|| color || cursors || sprite ||

Surface

Surface objects represent a simple memory buffer of pixels. Surface objects can reside in system memory, or in special hardware memory, which can be hardware accelerated. Surfaces that are 8 bits per pixel use a colormap to represent their color values. All Surfaces with higher bits per pixel use a packed pixels to store their color values.

Creating a new Surface().

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 will use highly optimized software blitting methods.

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.

Also remember that you will want to leave the surface locked for the shortest amount of time needed.

Here is the quick breakdown of how packed pixels work (don't worry if you don't quite understand this, it is only here for informational purposes, it is not needed). Each colorplane mask can be used to isolate the values for a colorplane from the packed pixel color. Therefore PACKED_COLOR & RED_MASK == REDPLANE. Note that the REDPLANE is not exactly the red color value, but it is the red color value bitwise left shifted a certain amount. The losses and masks can be used to convert back and forth between each colorplane and the actual color for that plane. Here are the final formulas used be map and unmap. PACKED_COLOR = RED>>losses[0]<<shifts[0] | GREEN>>losses[1]<<shifts[1] | BLUE>>losses[2]<<shifts[2] RED = PACKED_COLOR & masks[0] >> shifts[0] << losses[0] GREEN = PACKED_COLOR & masks[1] >> shifts[1] << losses[1] BLUE = PACKED_COLOR & masks[2] >> shifts[2] << losses[2] There is also an alpha channel for some Surfaces.

blit	- copy a one Surface to another.
convert	- new copy of surface with different format
convert_alpha	- new copy of surface with different format and per pixel alpha
copy	- creates a new copy of a Surface
fill	- fill areas of a Surface
get_abs_offset	- get absolute offset of subsurface
get_abs_parent	- get the toplevel surface for a subsurface
get_alpha	- query alpha information
get_at	- get a pixel color
get_bitsize	- query size of pixel
get_bytesize	- query size of pixel
get_clip	- query the clipping area
get_colorkey	- query colorkey
get_flags	- query the surface flags
get_height	- query the surface height
get_locked	- check if the surface needs locking
get_losses	- get mapping losses for each colorplane
get_masks	- get mapping bitmasks for each colorplane
get_offset	- get offset of subsurface
get_palette	- get the palette
get_palette_at	- get a palette entry
get_parent	- get a subsurface parent
get_pitch	- query the surface pitch
get_rect	- get a rectangle covering the entire surface
get_shifts	- alphashift
get_size	- query the surface size
get_width	- query the surface width
lock	- locks Surface for pixel access
map_rgb	- convert RGB into a mapped color
mustlock	- check if the surface needs locking
set_alpha	- change alpha information
set_at	- set pixel at given position
set_clip	- assign destination clipping rectangle
set_colorkey	- change colorkey information
set_palette	- set the palette
set_palette_at	- set a palette entry
subsurface	- create a new surface that shares pixel data
unlock	- locks Surface for pixel access
unmap_rgb	- convert mapped color into RGB