Pygame Surface: Create, Fill and Draw on Surfaces

A Surface is an image in memory. The window is one (set_mode() returns it), every image you load is one, and text becomes one when you render it. You can also make blank Surfaces, draw on them once, and blit them as often as you like.

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 360))
clock = pygame.time.Clock()

# Draw a badge once, on its own Surface
badge = pygame.Surface((80, 80))
badge.fill((40, 120, 220))
pygame.draw.circle(badge, (255, 255, 255), (40, 40), 28)
pygame.draw.circle(badge, (255, 200, 0), (40, 40), 18)

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    screen.fill((20, 22, 34))
    for row in range(3):
        for col in range(4):
            screen.blit(badge, (40 + col * 110, 40 + row * 110))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

The badge is drawn once, before the loop, and copied twelve times every frame. Drawing a complex picture once and blitting it is much faster than drawing it shape by shape each frame.

Making a Surface

plain = pygame.Surface((100, 50))                   # black, no transparency
clear = pygame.Surface((100, 50), pygame.SRCALPHA)  # transparent, per pixel alpha

Useful methods on any Surface:

Three kinds of transparency

Per pixel alpha. A Surface made with pygame.SRCALPHA (or an image loaded with convert_alpha()) stores an alpha value for every pixel. Draw on it with four-number colors such as (255, 255, 255, 100).

Surface alpha. surface.set_alpha(0 to 255) makes the whole Surface see-through when it is blitted, without touching its pixels. It is the easy way to fade:

import pygame

pygame.init()
screen = pygame.display.set_mode((480, 300))
clock = pygame.time.Clock()

card = pygame.Surface((200, 120))
card.fill((250, 250, 250))
pygame.draw.rect(card, (230, 60, 90), (20, 20, 160, 80), border_radius=12)

alpha = 0
running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    alpha = (alpha + 2) % 256
    card.set_alpha(alpha)

    screen.fill((30, 80, 70))
    screen.blit(card, (140, 90))
    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Color key. surface.set_colorkey(color) makes every pixel of one color invisible. Old games used magenta (255, 0, 255) backgrounds for this; PNG images with real transparency have mostly replaced it.

subsurface

sheet.subsurface((x, y, w, h)) returns a Surface that is a window onto part of another Surface, without copying pixels. It is how you cut frames out of a sprite sheet; see animation.

convert() and convert_alpha()

After loading an image, call convert() (no transparency) or convert_alpha() (keeps transparency). They change the pixels to the screen's format, so blitting is several times faster. Both need the window to exist, so call them after pygame.display.set_mode(). Loading images shows them in use.