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

## pygame.image

This module contains functions to transfer images in and out of Surfaces. At the minimum the included load() function will support BMP files. If SDL_image is properly installed when pygame is installed, it will support all the formats included with SDL_image. You can call the get_extended() function to test if the SDL_image support is available.
Some functions that communicate with other libraries will require that those libraries are properly installed. For example, the save() function can only save OPENGL surfaces if pyopengl is available.

frombuffer | - create a surface from a python memory buffer
fromstring | - create a surface from a raw string buffer
get_extended | - returns true if SDL_image formats are available
load | - load an image to a new Surface
save | - save surface data
tostring | - create a raw string buffer of the surface data

frombuffer
`pygame.image.frombuffer(string, size, format) -> Surface`

This works like the fromstring() method, but uses Python buffer objects. It is about 20 times faster than fromstring(). Strings and memory maps are examples of buffers in Python.
See the fromstring() function for information about the size and format arguments.

fromstring
`pygame.image.fromstring(string, size, format, flipped=0) -> Surface`

This will create a new Surface from a copy of raw data in a string. This can be used to transfer images from other libraries like PIL's fromstring().
In most cases you can use the frombuffer() which accepts strings and is about 20 times faster.
The flipped argument should be set to true if the image in the string is.
The format argument is a string representing which type of string data you need. It can be one of the following, \"P\" for 8bit palette indices. \"RGB\" for 24bit RGB data, \"RGBA\" for 32bit RGB and alpha, or \"RGBX\" for 32bit padded RGB colors. \"ARGB\" is a popular format for big endian platforms.
These flags are a subset of the formats supported the PIL Python Image Library. Note that the \"P\" format only create an 8bit surface, but the colormap will be all black.

get_extended
`pygame.image.get_extended() -> int`

This will return a true value if the extended image formats from SDL_image are available for loading.

load
`pygame.image.load(file, [namehint]) -> Surface`

This will load an image into a new surface. You can pass it either a filename, or a python file-like object to load the image from. If you pass a file-like object that isn't actually a file (like the StringIO class), then you might want to also pass either the filename or extension as the namehint string. The namehint can help the loader determine the filetype.
If pygame was installed without SDL_image support, the load will only work with BMP images. You can test if SDL_image is available with the get_extended() function. These extended file formats usually include GIF, PNG, JPG, PCX, TGA, and more.
If the image format supports colorkeys and pixel alphas, the load() function will properly load and configure these types of transparency.

save
`pygame.image.save(Surface, file) -> None`

This will save your surface as a BMP or TGA image. The given file argument can be either a filename or a python file-like object. This will also work under OPENGL display modes.
The image will default to save with the TGA format. If the filename has the BMP extension, it will use the BMP format.

tostring
`pygame.image.tostring(Surface, format, flipped=0) -> string`

This will copy the image data into a large string buffer. This can be used to transfer images to other libraries like PIL's fromstring() and PyOpenGL's glTexImage2D().
The flipped argument will cause the output string to have it's contents flipped vertically.
The format argument is a string representing which type of string data you need. It can be one of the following, \"P\" for 8bit palette indices. \"RGB\" for 24bit RGB data, \"RGBA\" for 32bit RGB and alpha, or \"RGBX\" for 32bit padded RGB colors. \"ARGB\" is a popular format for big endian platforms.
These flags are a subset of the formats supported the PIL Python Image Library. Note that the \"P\" format only will work for 8bit Surfaces.
If you ask for the \"RGBA\" format and the image only has colorkey data. An alpha channel will be created from the colorkey values.