Surface an object that contain graphic

Surface represents images

Surface contain images but also have dozens (44) routines to match your needs.

Common way to create surface is to load image from file. It will give us a new surface but with resolution and color depth as in file. Usually it wont be a optimized format (current) so PyGame will have to convert it every time when drawing it on the screen. To convert surface to best format use:

optimized_surf = allready_loadaed_surf.convert()
pygame.Surface

Another options are:
pygame.Surface((width, height), flags=0, depth=0, masks=None)
pygame.Surface((width, height), flags=0, Surface)

Only (width, height) are obligatory. If will set only them PyGame will create surface with best (current) color depth and flags. Also PyGame will fill it up with "black" color.

pygame.Surface.blit

To put one image onto another PyGame have destiny_surf.blit(source_surf, rect, source_rect, specialflags) it will return rectangle of affected pixel, copy source_rect part of source_surf onto rect part of destiny_surf. Only source_surf is obligatory. special flags are:
BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAX
BLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX
BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAX

pygame.Surface.convert

To convert surface to specific format use pygame.surface.convert(surface) or convert(depth) or convert(mask) or just convert(). The last one will convert to the fastest format currently used. Others will change to match given surface, depth, mask.

pygame.Surface.convert_alpha

Some images are made for alpha bliting for blending one transparent on opaque one. To optimize surface for this purpose call pygame.surface.convert_apha(surface). If won't to optimize for bliting on display call without any parameters.

pygame.Surface.copy

pygame.Surface.copy(surface) will duplicate surface.

pygame.Surface.fill

pygame.Surface.fill(color, rect=None, special_flags) will fill surface with color. Color can be RGB or RGBA but Alpha is used only when surface have per pixel alpha. Flags are:
BLEND_ADD, BLEND_SUB, BLEND_MULT, BLEND_MIN, BLEND_MAX
BLEND_RGBA_ADD, BLEND_RGBA_SUB, BLEND_RGBA_MULT, BLEND_RGBA_MIN, BLEND_RGBA_MAX
BLEND_RGB_ADD, BLEND_RGB_SUB, BLEND_RGB_MULT, BLEND_RGB_MIN, BLEND_RGB_MAX

pygame.Surface.set_colorkey

2D pictures always are square. How to make parts of them transparent? Use colorkey. Color key says PyGame to not display it. Every picture can have its own color key, but try to use one similar to pink. pygame.Surface.set_colorkey(color, flags=None) where color can be either RGB or RGBA. If none colorkey will be unset. flags can be pygame.RLEACCEL witch improve speed of bliting on non accelerated hardware but slows down time of modification.
Be aware that color key work only with full surface alpha but not with per pixel alpha

pygame.Surface.get_colorkey

pygame.Surface.get_colorkey() returns RGB value or None.

pygame.Surface.set_alpha

pygame.Surface.set_alpha(color, flag=None) sets alpha for whole surface or disable it if None passed. Flag can be pygame.RLEACCEL

pygame.Surface.get_alpha

pygame.Surface.get_alpha() returns current surface alpha or None is disabled.

pygame.Surface.must_lock

To access pixel data in hardware accelerated surface you must get lock. To check if needed use pygame.Surface.must_lock() but simpler and faster will be to lock all surfaces.

pygame.Surface.lock

pygame.Surface.lock will lock surface for pixel data editing. But do it as fast as you can because this surface can't be displayed or managed by PyGame. Also all PyGame functions use it internally but if you will call them many times in a raw try to wrap that block in lock/unlock pair to gain some performance.

pygame.Surface.unlock

Use pygame.Surface.unlock() to unlock Surface. You can nest this two routines it is 100% safe, only final unlock will unlock surf.

pygame.Surface.get_lock

pygame.Surface.get_lock() returns True if surface is locked.

pygame.Surface.get_locks

pygame.Surface.get_locks returns tuple with all locks on current surface.

pygame.Surface.get_at

PyGame can edit single pixels is surface. pygame.Surface.get((x,y)) returns Color of wanted pixel.

pygame.Surface.set_at

pygame.Surface.set_at((x,y),Color) sets Color on given pixel

pygame.Surface.map_rgb

pygame.Surface.map_rgb(Color) returns integer with Color mapped into integer

pygame.Surface.unmap_rgb

pygame.Surface.unmap_rgb(integer) map integer into Color.

pygame.Surface.set_clip

Surface have its own clipping area - part that can be modified. pygame.Surface.set_cip(rect) set it to rect if None passed whole Surf is editable.

pygame.Surface.get_clip

pygame.Surface.get_clip() returns clipping rect.

pygame.Surface.subsurface

pygame.Surface.subsurface(rect) creates form rect part of Surface a new one that share pixel date with surface and is considered as child of Surface. One Surface can have multiple subsurfaces and subsubsurfaces, also display surface can have subsurfaces if not hardware mode is set.
Pixel data are common also child inherit alpha, palette, kolorkey but others are separate e.g. clipping rect.

pygame.Surface.get_parent

pygame.Surface.get_parent() finds parent of current surface. If not exist none will be returned.

pygame.Surface.get_abs_parent

pygame.Surface.get_abs_parent() also finds parent but if none exist current surf will be returned.

pygame.Surface.get_offset

pygame.Surface.get_offset returns (x,y) witch are offset position of current surface inside of its parent. (0,0) means no parent.

pygame.Surface.get_abs_offset

pygame.Surface.get_abs_offset() will return offset position but inside of top level parent of surface. (0,0) mean no parent.

pygame.Surface.get_size

pygame.Surface.get_size() returns (width, height)

pygame.Surface.get_width

pygame.Surface.get_width() returns width

pygame.Surface.height

pygame.Surface.get_height() returns height

pygame.Surface.get_rect

pygame.Surface.get_rect(**kwargs): returns Rect that starts at (0,0) and cover all surface. You can pass key arguments the same as names of rect data so get_rect will fill them with given values.

pygame.Surface.get_bitsize

pygame.Surface.get_bitsize() returns number of bits per pixel

pygame.Surface.get_bytesize

pygame.Surface.get_bytesize() returns number of bytes per pixel

pygame.Surface.get_flags

pygame.Surface.get_flags() returns flags:
Here is a more complete list of flags. A full list can be found in SDL_video.h
SWSURFACE 0x00000000 # Surface is in system memory
HWSURFACE 0x00000001 # Surface is in video memory
ASYNCBLIT 0x00000004 # Use asynchronous blits if possible

Available for pygame.display.set_mode - initialize a window or screen for display
ANYFORMAT 0x10000000 # Allow any video depth/pixel-format
HWPALETTE 0x20000000 # Surface has exclusive palette
DOUBLEBUF 0x40000000 # Set up double-buffered video mode
FULLSCREEN 0x80000000 # Surface is a full screen display
OPENGL 0x00000002 # Create an OpenGL rendering context
OPENGLBLIT 0x0000000A # Create an OpenGL rendering context
# and use it for blitting. Obsolete.
RESIZABLE 0x00000010 # This video mode may be resized
NOFRAME 0x00000020 # No window caption or edge frame

Used internally (read-only)
HWACCEL 0x00000100 # Blit uses hardware acceleration
SRCCOLORKEY 0x00001000 # Blit uses a source color key
RLEACCELOK 0x00002000 # Private flag
RLEACCEL 0x00004000 # Surface is RLE encoded
SRCALPHA 0x00010000 # Blit uses source alpha blending
PREALLOC 0x01000000 # Surface uses preallocated memory

pygame.Surface.get_pitch

pygame.Surface.get_pitch() returns bytes per Surface row

pygame.Surface.get_bounding_rect

pygame.Surface.get_bounding_rect(alpha_value=1) will return smallest rest that covers all pixels that have alpha values bigger then alpha_value

pygame.Surface.get_buffer

pygame.Surface.get_buffer() returns BufferProxy witch can be used to manipulate pixel data but it will lock surf until BufferProxy exists