pygame  
pygame
documentation
||  Home  ||  Help Contents  ||
 
|| CD || Channel || Font || Joystick || Rect || Sound || Surface ||
|| pygame || cdrom || constants || display || event || font || image ||
|| joystick || key || mixer || mixer_music || mouse || surfarray || time ||

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). Some surfaces need to be locked before they can be used. Surfaces with flags like HWSURFACE and RLEACCEL generally require calls to lock() and unlock() surrounding pixel access. It is safe to lock() and unlock() surfaces that do not require locking. Nonetheless, you can check to see if a Surface really needs to be locked with the mustlock() function.

 

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 (not exactly, heh). PACKED_COLOR = RED>>losses[0]<>losses[1]<>losses[2]<> 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. The alpha channel works this same exact way, and the map_rgba() and unmap_rgba() functions can be used to do the conversion for you.
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_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 width
get_height - query the surface height
get_losses - get mapping losses for each colorplane
get_masks - get mapping bitmasks for each colorplane
get_palette - get the palette
get_palette_at - get a palette entry
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
save - save surface as BMP data
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
unlock - locks Surface for pixel access
unmap_rgb - convert mapped color into RGB

blit
Surface.blit(source, destpos, [sourcerect]) -> Rect
    The blitting will transfer one surface to another. 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.

 
convert
Surface.convert([src_surface]) -> 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_alpha
Surface.convert_alpha([src_surface]) -> Surface

 
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 fill is subject to be clipped by the active clipping rectangle. The return value contains the actual area filled.

 
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([x, y]) -> RGBA
    Returns the RGB color values at a given pixel. If the Surface has no per-pixel alpha, the alpha will be 255 (opaque). The surface must be locked for this to work correctly.

 
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_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_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_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

 
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.

 
save
Surface.save(file) -> None
    This will save your surface in the BMP format. The given file argument can be either a filename or a python file-like object to save the BMP image to.

 
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 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 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_at
Surface.set_at([x, y], RGBA) -> None

 
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([RGBA, [flags]]) -> None
    Set the colorkey for the surface by passing a mapped color value as the color argument. If no arguments are passed, colorkeying will be disabled for this surface.
     
    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.

 
set_palette_at
Surface.set_palette_at(index, [r, g, b]) -> None
    This function sets the palette color at a specific entry.

 
unlock
Surface.unlock() -> None

 
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.