pygame documentation | || Home || Help Contents || || pygame || cdrom || constants || display || draw || event || || font || image || joystick || key || mixer || mixer_music || || mouse || movie || sndarray || surfarray || time || transform || || CD || Channel || Clock || Font || Joystick || Movie || || Rect || Sound || Surface || || 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.
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
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

blit
`Surface.blit(source, destpos, [sourcerect]) -> Rect`

The blitting will copy pixels from the source. It will respect any special modes like colorkeying and alpha. If hardware support is available, it will be used. The given source is the Surface to copy from. The destoffset is a 2-number-sequence that specifies where on the destination Surface the blit happens (see below). When sourcerect isn't supplied, the blit will copy the entire source surface. If you would like to copy only a portion of the source, use the sourcerect argument to control what area is copied.
The blit is subject to be clipped by the active clipping rectangle. The return value contains the actual area blitted.
As a shortcut, the destination position can be passed as a rectangle. If a rectangle is given, the blit will use the topleft corner of the rectangle as the blit destination position. The rectangle sizes will be ignored.
Blitting surfaces with pixel alphas onto an 8bit destination will not use the surface alpha values.

convert
`Surface.convert([src_surface] OR depth, [flags] OR masks) -> Surface`

Creates a new copy of the surface with the desired pixel format. Surfaces with the same pixel format will blit much faster than those with mixed formats. The pixel format of the new surface will match the format given as the argument. If no surface is given, the new surface will have the same pixel format as the current display.
convert() will also accept bitsize or mask arguments like the Surface() constructor function. Either pass an integer bitsize or a sequence of color masks to specify the format of surface you would like to convert to. When used this way you may also pass an optional flags argument (whew).

convert_alpha
`Surface.convert_alpha([src_surface]) -> Surface`

Creates a new copy of the surface with the desired pixel format. The new surface will be in a format suited for quick blitting to the given format with per pixel alpha. If no surface is given, the new surface will be optimized for blittint to the current display.
Unlike the convert() method, the pixel format for the new image will not be exactly the same as the requested source, but it will be optimized for fast alpha blitting to the destination.

fill
`Surface.fill(color, [rectstyle])) -> Rect`

Fills the specified area of the Surface with the mapped color value. If no destination rectangle is supplied, it will fill the entire Surface.
The color argument can be a RGBA sequence or a mapped color integer.
The fill is subject to be clipped by the active clipping rectangle. The return value contains the actual area filled.

get_abs_offset
`Surface.get_abs_offset() -> x, y`

Returns the absolute X and Y position a subsurface is positioned inside its top level parent. Will return 0,0 for surfaces that are not a subsurface.

get_abs_parent
`Surface.get_abs_parent() -> Surface`

Returns the top level Surface for this subsurface. If this is not a subsurface it will return a reference to itself. You will always get a valid surface from this method.

get_alpha
`Surface.get_alpha() -> alpha`

Returns the current alpha value for the Surface. If transparency is disabled for the Surface, it returns None.

get_at
`Surface.get_at(position) -> RGBA`

Returns the RGB color values at a given pixel. If the Surface has no per-pixel alpha, the alpha will be 255 (opaque).
This function will need to temporarily lock the surface.

get_bitsize
`Surface.get_bitsize() -> int`

Returns the number of bits used to represent each pixel. This value may not exactly fill the number of bytes used per pixel. For example a 15 bit Surface still requires a full 2 bytes.

get_bytesize
`Surface.get_bytesize() -> int`

Returns the number of bytes used to store each pixel.

get_clip
`Surface.get_clip() -> rect`

Returns the current destination clipping area being used by the Surface. If the clipping area is not set, it will return a rectangle containing the full Surface area.

get_colorkey
`Surface.get_colorkey() -> RGBA`

Returns the current mapped color value being used for colorkeying. If colorkeying is not enabled for this surface, it returns None

get_flags
`Surface.get_flags() -> flags`

Returns the current state flags for the surface.

get_height
`Surface.get_height() -> height`

Returns the height of the Surface.

get_locked
`Surface.get_locked() -> bool`

Returns true if the surface is currently locked.

get_losses
`Surface.get_losses() -> redloss, greenloss, blueloss, alphaloss`

Returns the bitloss for each color plane. The loss is the number of bits removed for each colorplane from a full 8 bits of resolution. A value of 8 usually indicates that colorplane is not used (like the alpha)

get_masks
`Surface.get_masks() -> redmask, greenmask, bluemask, alphamask`

Returns the bitmasks for each color plane. The bitmask is used to isolate each colorplane value from a mapped color value. A value of zero means that colorplane is not used (like alpha)

get_offset
`Surface.get_offset() -> x, y`

Returns the X and Y position a subsurface is positioned inside its parent. Will return 0,0 for surfaces that are not a subsurface.

get_palette
`Surface.get_palette() -> [[r, g, b], ...]`

This will return the an array of all the color indexes in the Surface's palette.

get_palette_at
`Surface.get_palette_at(index) -> r, g, b`

This will retreive an individual color entry from the Surface's palette.

get_parent
`Surface.get_parent() -> Surface`

Returns the Surface that is a parent of this subsurface. Will return None if this is not a subsurface.

get_pitch
`Surface.get_pitch() -> pitch`

The surface pitch is the number of bytes used in each scanline. This function should rarely needed, mainly for any special-case debugging.

get_rect
`Surface.get_rect() -> rect`

Returns a new rectangle covering the entire surface. This rectangle will always start at 0, 0 with a width. and height the same size as the image.

get_shifts
`Surface.get_shifts() -> redshift, greenshift, blueshift,`

Returns the bitshifts used for each color plane. The shift is determine how many bits left-shifted a colorplane value is in a mapped color value.

get_size
`Surface.get_size() -> x, y`

Returns the width and height of the Surface.

get_width
`Surface.get_width() -> width`

Returns the width of the Surface.

lock
`Surface.lock() -> None`

On accelerated surfaces, it is usually required to lock the surface before you can access the pixel values. To be safe, it is always a good idea to lock the surface before entering a block of code that changes or accesses the pixel values. The surface must not be locked when performing other pygame functions on it like fill and blit.
You can doublecheck to really make sure a lock is needed by calling the mustlock() member. This should not be needed, since it is usually recommended to lock anyways and work with all surface types. If the surface does not need to be locked, the operation will return quickly with minute overhead.
On some platforms a necessary lock can shut off some parts of the system. This is not a problem unless you leave surfaces locked for long periouds of time. Only keep the surface locked when you need the pixel access. At the same time, it is not a good too repeatedly lock and unlock the surface inside tight loops. It is fine to leave the surface locked while needed, just don't be lazy.

map_rgb
`Surface.map_rgb(RGBA) -> int`

Uses the Surface format to convert RGBA into a mapped color value.
This function is not as needed as normal C code using SDL. The pygame functions do not used mapped colors, so there is no need to map them.

mustlock
`Surface.mustlock() -> bool`

Returns true if the surface really does need locking to gain pixel access. Usually the overhead of checking before locking outweight the overhead of just locking any surface before access.

set_alpha
`Surface.set_alpha([alpha, [flags]]) -> None`

Set the overall transparency for the surface. If no alpha is passed, alpha blending is disabled for the surface. An alpha of 0 is fully transparent, an alpha of 255 is fully opaque. If no arguments or None is passed, this will disable the surface alpha.
If your surface has a pixel alpha channel, it will override the overall surface transparency. You'll need to change the actual pixel transparency to make changes.
If your image also has pixel alpha values, will be used repeatedly, you will probably want to pass the RLEACCEL flag to the call. This will take a short time to compile your surface, and increase the blitting speed.

set_at
`Surface.set_at(position, RGBA) -> None`

Assigns color to the image at the give position. Color can be a RGBA sequence or a mapped color integer.
In some situations just using the fill() function with a one-pixel sized rectangle will be quicker. Also the fill function does not require the surface to be locked.
This function will need to temporarily lock the surface.

set_clip
`Surface.set_clip([rectstyle]) -> None`

Assigns the destination clipping rectangle for the Surface. When blit or fill operations are performed on the Surface, they are restricted to the inside of the clipping rectangle. If no rectangle is passed, the clipping region is set to the entire Surface area. The rectangle you pass will be clipped to the area of the Surface.

set_colorkey
`Surface.set_colorkey([color, [flags]]) -> None`

Set the colorkey for the surface by passing a mapped color value as the color argument. If no arguments or None is passed, colorkeying will be disabled for this surface.
The color argument can be either a RGBA sequence or a mapped integer.
If your image is nonchanging and will be used repeatedly, you will probably want to pass the RLEACCEL flag to the call. This will take a short time to compile your surface, and increase the blitting speed.

set_palette
`Surface.set_palette([[r, g, b], ...]) -> None`

This will replace the entire palette with color information you provide.
You can pass an incomplete list of RGB values, and this will only change the first colors in the palette.

set_palette_at
`Surface.set_palette_at(index, [r, g, b]) -> None`

This function sets the palette color at a specific entry.

subsurface
`Surface.subsurface(rectstyle) -> Surface`

Creates a new surface that shares pixel data of the given surface. Note that only the pixel data is shared. Things like clipping rectangles and colorkeys will be unique for the new surface.
The new subsurface will inherit the palette, colorkey, and surface alpha values from the base image.
You should not use the RLEACCEL flag for parent surfaces of subsurfaces, for the most part it will work, but it will cause a lot of extra work, every time you change the subsurface, you must decode and recode the RLEACCEL data for the parent surface.
As for using RLEACCEL with the subsurfaces, that will work as you'd expect, but changes the the parent Surface will not always take effect in the subsurface.

unlock
`Surface.unlock() -> None`

After a surface has been locked, you will need to unlock it when you are done.
You can doublecheck to really make sure a lock is needed by calling the mustlock() member. This should not be needed, since it is usually recommended to lock anyways and work with all surface types. If the surface does not need to be locked, the operation will return quickly with minute overhead.

unmap_rgb
`Surface.unmap_rgb(color) -> RGBA`

This function returns the RGBA components for a mapped color value. If Surface has no per-pixel alpha, alpha will be 255 (opaque).
This function is not as needed as normal C code using SDL. The pygame functions do not used mapped colors, so there is no need to unmap them.