Contains the Surface object.


  • Surface.get_at((x, y)) -> int
  • - get a pixel color
  • Surface.set_at((x, y), pixel) -> None
  • -
  • map_rgb((r, g, b)) -> int
  • - map_rgb(r, g, b) -> int
  • unmap_rgb(color) -> (r, g, b)
  • - convert mapped color into RGB
  • map_rgba((r, g, b, a)) -> int
  • - convert RGBA into a mapped color
  • unmap_rgba(color) -> (r, g, b, a)
  • - convert mapped color into RGBA
  • Surface.lock() -> None
  • - locks Surface for pixel access
  • Surface.unlock() -> None
  • - locks Surface for pixel access
  • Surface.mustlock() -> bool
  • - check if the surface needs locking
  • Surface.get_palette() -> [(r, g, b), ...]
  • - get the palette
  • Surface.get_palette_at(index) -> (r, g, b)
  • - get a palette entry
  • Surface.set_palette([(r, g, b), ...]) -> None
  • - set the palette
  • Surface.set_palette_at(index, (r, g, b)) -> None
  • - set a palette entry
  • Surface.set_colorkey([color, [flags]]) -> None
  • - change colorkey information
  • Surface.get_colorkey() -> color
  • - query colorkey
  • Surface.set_alpha([alpha, [flags]]) -> None
  • - change alpha information
  • Surface.get_alpha() -> alpha
  • - query alpha information
  • Surface.convert([src_surface]) -> Surface
  • - new copy of surface with different format
  • Surface.convert_alpha([src_surface]) -> Surface
  • - new copy of surface with different format and per
  • Surface.set_clip([rectstyle])) -> Rect
  • - assign destination clipping rectangle
  • Surface.get_clip() -> rect
  • - query the clipping area
  • Surface.fill(color, [rectstyle])) -> Rect
  • - fill areas of a Surface
  • Surface.blit(source, destoffset, [srcoffset,
  • - [size]]) -> Rect
  • Surface.get_size() -> (x, y)
  • - query the surface size
  • Surface.get_bitsize() -> int
  • - query size of pixel
  • Surface.get_bytesize() -> int
  • - query size of pixel
  • Surface.get_masks() -> (redmask, greenmask,
  • - bluemask, alphamask)
  • Surface.get_shifts() -> (redshift, greenshift,
  • - blueshift, alphashift)
  • Surface.get_losses() -> (redloss, greenloss,
  • - blueloss, alphaloss)
  • pygame.surface(size, [flags, [depth|Surface,
  • - [masks]]]) -> Surface


    Surface.get_at((x, y)) -> int

    Returns the mapped pixel color at the coordinates given point.


    Surface.set_at((x, y), pixel) -> None

    give position.


    map_rgb((r, g, b)) -> int

    Uses the Surface format to convert RGB into a mapped color value.


    unmap_rgb(color) -> (r, g, b)

    This function returns the RGB components for a mapped color value.


    map_rgba((r, g, b, a)) -> int

    Uses the Surface format to convert RGBA into a mapped color value. It is safe to call this on a surface with no pixel alpha. The alpha will simply be ignored.


    unmap_rgba(color) -> (r, g, b, a)

    This function returns the RGB components for a mapped color value. For surfaces with no alpha, the alpha will always be 255.


    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.


    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.


    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.


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

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


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

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


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

    This will replace the entire palette with color information you provide.


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

    This function sets the palette color at a specific entry.


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


    Surface.get_colorkey() -> color

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


    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.


    Surface.get_alpha() -> alpha

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


    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.


    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.


    Surface.set_clip([rectstyle])) -> Rect

    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.


    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.


    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.


    Surface.blit(source, destoffset, [srcoffset,

    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. Without srcoffset and size supplied, the blit will copy the entire source surface. If you would like to copy only a portion of the source, use the srcoffset and size arguements 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.


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

    Returns the width and height of the Surface.


    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.


    Surface.get_bytesize() -> int

    Returns the number of bytes used to store each pixel.


    Surface.get_masks() -> (redmask, greenmask,

    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)


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

    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.


    Surface.get_losses() -> (redloss, greenloss,

    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)


    pygame.surface(size, [flags, [depth|Surface,

    Creates a new surface object. Size is a 2-int-sequence containing width and height. Depth is the number of bits used per pixel. If omitted, depth will use the current display depth. Masks is a four item sequence containing the bitmask for r,g,b, and a. If omitted, masks will default to the usual values for the given bitdepth. Flags is a mix of the following flags: SWSURFACE, HWSURFACE, ASYNCBLIT, SRCCOLORKEY, or SRCALPHA. (flags = 0 is the same as SWSURFACE). depth and masks can be substituted for another surface object which will create the new surface with the same format as the given one. When using default masks, alpha will always be ignored. Note, if you pass SRCOLORKEY and/or SRCALPHA, the surface won't immediately have these features enabled. SDL will use these flags to help optimize the surface for use with the blitters. Also, for a plain software surface, 0 can be used for the flag. A plain hardware surface can just use 1 for the flag.