Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 41 ยท Drawing and Images

Surfaces and Blitting

Learn the Pygame Surface and blit(). Create surfaces, copy one onto another, control draw order, use per-pixel alpha, subsurfaces, convert() and fill for fast rendering.

Almost everything you see in a Pygame game is a Surface. The window is one, every loaded image is one, every rendered line of text is one, and you can create as many blank ones as you like. Drawing a game means copying surfaces onto other surfaces, an operation called blitting (from "block image transfer"). Master Surface and blit() and the rest of Pygame's graphics become straightforward.

Creating surfaces

Python
panel = pygame.Surface((200, 120))                    # opaque, black
overlay = pygame.Surface((200, 120), pygame.SRCALPHA) # with a per-pixel alpha channel

A plain Surface has no transparency: every pixel is solid. Adding pygame.SRCALPHA gives each pixel an alpha value from 0 (invisible) to 255 (opaque), which you need for soft shadows, glows and sprites with transparent corners. New SRCALPHA surfaces start fully transparent.

Python
panel.fill((40, 40, 60))                        # solid color
overlay.fill((255, 0, 0, 128))                  # semi-transparent red (4th value = alpha)
print(panel.get_size(), panel.get_width(), panel.get_height())
rect = panel.get_rect()                         # Rect(0, 0, 200, 120)

blit: copying a surface onto another

Python
screen.blit(panel, (50, 40))          # top-left corner of panel at x=50, y=40
screen.blit(panel, panel.get_rect(center=(400, 300)))   # position by a Rect
screen.blit(sheet, (10, 10), area=pygame.Rect(0, 0, 32, 32))   # copy only part of the source

The destination can be a position tuple (the top-left corner) or a Rect (its top-left is used). The area argument selects a region of the source, which is how sprite sheets work.

blit() returns the Rect that changed. That is used for dirty-rect updates.

Draw order: the painter's algorithm

Surfaces are painted in the order you blit them, and later ones cover earlier ones. Draw the background first, then the world, then the interface. There is no depth buffer: to put something in front, draw it later.

Python Layers and draw order

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The overlapping area belongs to whichever surface was blitted last.

Transparency

There are three kinds, and it helps to know which you are using:

  1. Per-pixel alpha (SRCALPHA, or PNG images loaded with convert_alpha()): each pixel has its own opacity. Best quality and the default for sprites.
  2. Surface alpha (surface.set_alpha(128)): one opacity for the whole surface, used for fades.
  3. Color key (surface.set_colorkey((255, 0, 255))): one color becomes fully transparent. Old but still handy.
Python
fade = pygame.Surface((800, 600))
fade.fill((0, 0, 0))
fade.set_alpha(120)           # about 47 percent opaque black
screen.blit(fade, (0, 0))     # darkens everything under it, e.g. for a pause menu

Try it: alpha blending

This puts a semi-transparent red layer over a blue background and reads back the blended pixel, so you can see the blend formula at work: result = source * alpha + destination * (1 - alpha).

Python Per-pixel alpha blending

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The result of 50 percent red over blue is about (100, 0, 100), a purple. White at alpha 64 over black gives roughly 25 percent gray.

convert() and convert_alpha()

When you load an image, Pygame can convert it to the same pixel format as the display, which makes every later blit much faster:

Python
image = pygame.image.load("player.png").convert_alpha()   # keeps transparency
background = pygame.image.load("sky.jpg").convert()       # opaque images

Call them after set_mode() (they need the display format) and only once, at load time, never inside the loop. Forgetting convert() is one of the most common reasons for a slow Pygame game.

Subsurfaces and copies

Python
sheet = pygame.image.load("tiles.png").convert_alpha()
tile = sheet.subsurface(pygame.Rect(32, 0, 32, 32))   # a window onto the sheet, NOT a copy
copy = tile.copy()                                    # independent pixels

A subsurface shares pixels with its parent: drawing on one changes the other. That is cheap and useful for cutting up sprite sheets, but use copy() when you need to modify one tile independently.

Python Subsurface shares pixels, copy does not

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Other useful Surface methods

Method Purpose
fill(color, rect=None) Fill all or part of the surface
get_at((x, y)) / set_at((x, y), color) Read or write one pixel (slow in bulk)
copy() A new independent surface
blits(list) Blit many (surface, pos) pairs at once, faster than a Python loop
set_clip(rect) Restrict drawing to a region, for example a scrolling panel
scroll(dx, dy) Shift the pixels in place
get_bounding_rect() The smallest rect containing non-transparent pixels
pygame.transform.* Return new rotated, scaled or flipped copies (see Images and Transforms)

Performance tips

  • Load and convert() images once, outside the loop.
  • Avoid creating new Surfaces every frame; reuse them.
  • Redraw only what you need onto static layers (for example a pre-rendered background) and blit that once.
  • Use screen.blits(sequence) for many sprites.
  • Do not call get_at for thousands of pixels per frame; use pygame.mask or surfarray for heavy pixel work.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does screen.blit(image, (50, 40)) do?

    Blitting copies the source surface onto the destination at the given position.
  2. 2. Two surfaces overlap. Which one appears in front?

    Pygame paints in call order, so later blits cover earlier ones.
  3. 3. Which flag gives a Surface a per-pixel alpha channel?

    pygame.Surface(size, pygame.SRCALPHA) creates a surface with transparency per pixel.
  4. 4. Why call convert() or convert_alpha() on loaded images?

    A matching pixel format avoids a conversion on every blit.
  5. 5. What is the key difference between subsurface() and copy()?

    Drawing on a subsurface changes the parent, while a copy is independent.

Summary

  • A Surface is a grid of pixels; the window, images and text are all surfaces.
  • dest.blit(source, position, area=None) copies a surface; later blits cover earlier ones.
  • Use SRCALPHA or convert_alpha() for per-pixel transparency, set_alpha() for fades.
  • Call convert() once at load time for speed.
  • subsurface() shares pixels; copy() does not.

Next: Colors and Rects