Lesson 2: Drawing Shapes & Surfaces

📐 The Screen Is a Grid

Think of the window as a sheet of graph paper where every square is one pixel. To draw anything you give pygame a pixel's address as (x, y):

• x counts pixels from the left edge, growing to the right.
• y counts pixels from the top edge, growing downward. This is the opposite of the graphs from math class, and it catches everyone at first.
• (0, 0) is the top-left corner. In an 800 × 600 window, x runs from 0 to 799 and y from 0 to 599, so (800, 600) is just past the bottom-right corner.

🎨 Colors and clamp_color()

A screen pixel mixes red, green and blue light. In pygame a color is a tuple of those three amounts, each a whole number from 0 (none) to 255 (full):

Store the colors you use as named constants at the top of your program (SKY = (135, 206, 235)), so a later change happens in one place. pygame also knows several hundred color names: pygame.Color("tomato") is (255, 99, 71).

When a calculated color goes out of range

Games often calculate colors: a sky that darkens at sunset, a hit flash that fades, a health bar that turns from green to red. Math like that can easily produce a channel below 0 or above 255, and pygame refuses it:

seconds = 12
sky = (135 - 12 * seconds, 206 - 18 * seconds, 235 - 16 * seconds)   # (-9, -10, 43)
screen.fill(sky)   # ValueError: invalid color ... each element must be an integer in the range [0, 255]

The fix is a tiny helper that forces every channel into range and turns it into a whole number. You will use it for every color you calculate in this course:

def clamp_color(color):
    """Return color with every channel forced to a whole number from 0 to 255."""
    return tuple(max(0, min(255, int(channel))) for channel in color)


print(clamp_color((-9, -10, 43.8)))      # (0, 0, 43)
print(clamp_color((300, 128, 12)))       # (255, 128, 12)

Read it from the inside out: min(255, ...) caps a channel at 255, max(0, ...) lifts it to at least 0, and int() drops the fraction. The tuple(... for channel in color) part does that to each channel in turn, just like a for loop that builds a new tuple. It works for 4-channel colors too (see Surfaces below).

🔷 The Drawing Functions

Every function in pygame.draw follows the same pattern: where to draw (a Surface, usually screen), what color, then the shape's numbers, then an optional width.

The width argument decides filled or hollow. Leave it out (or pass 0) and the shape is filled; pass 3 and you get a 3-pixel outline drawn just inside the shape's edge. A line has no inside, so its width is simply its thickness. There is also pygame.draw.arc for part of an oval; its angles are given in radians, a unit for angles that this course comes back to later.

Try it: each button draws one random shape and prints the matching pygame.draw call with the same numbers. Switch between filled and outline mode, and notice that each new shape covers the ones drawn before it.

Here is a complete program that uses all five functions. Run it, then change one number at a time and predict what will move.

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 600))
pygame.display.set_caption("Shape Gallery")
clock = pygame.time.Clock()

BACKGROUND = (20, 24, 36)
RED = (255, 107, 107)
GREEN = (74, 222, 128)
BLUE = (96, 165, 250)
YELLOW = (250, 204, 21)
PINK = (244, 114, 182)
WHITE = (240, 240, 240)

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

    screen.fill(BACKGROUND)

    # Rectangles: (x, y, width, height). The second one is a 4-pixel outline.
    pygame.draw.rect(screen, RED, (50, 60, 120, 80))
    pygame.draw.rect(screen, GREEN, (220, 60, 120, 80), 4)

    # Circles: center, radius. Then a 6-pixel ring.
    pygame.draw.circle(screen, BLUE, (470, 100), 45)
    pygame.draw.circle(screen, YELLOW, (640, 100), 45, 6)

    # An ellipse fills the rectangle you give it.
    pygame.draw.ellipse(screen, PINK, (50, 220, 200, 100))

    # A hexagon: six corner points, listed in order around the shape.
    hexagon = [(420, 210), (480, 245), (480, 315), (420, 350), (360, 315), (360, 245)]
    pygame.draw.polygon(screen, WHITE, hexagon, 3)

    # Lines: start, end, thickness. A little fan of them.
    for end_x in range(560, 761, 50):
        pygame.draw.line(screen, YELLOW, (660, 380), (end_x, 230), 2)

    # Draw order matters: the green bar is drawn last, so it sits on top.
    pygame.draw.rect(screen, BLUE, (100, 450, 300, 60))
    pygame.draw.rect(screen, GREEN, (250, 470, 300, 60))

    pygame.display.flip()

pygame.quit()

🧱 Surfaces: Build Once, Draw Many

The screen you draw on is a Surface: a rectangle of pixels in memory. You can make your own Surfaces too, draw on them once, and then copy them onto the screen as often as you like. Copying one Surface onto another is called blitting (from "block transfer"):

tree = pygame.Surface((60, 100))          # a new 60 x 100 picture (black to start)
pygame.draw.rect(tree, (120, 72, 40), (25, 60, 10, 40))   # draw ON the tree, not on the screen
screen.blit(tree, (200, 350))             # copy it so its TOP-LEFT corner lands at (200, 350)

Shapes drawn on a Surface use that Surface's grid, so (0, 0) is the tree's own top-left corner, wherever the tree ends up on screen. That is the big win: you design a thing once, in its own little coordinate grid, then place copies anywhere.

See-through Surfaces with SRCALPHA

A new Surface starts out solid black, so a round tree would sit inside a black box. For shapes with see-through parts, ask for per-pixel alpha with pygame.SRCALPHA. Such a Surface starts fully transparent, and you draw on it with 4-number colors: (red, green, blue, alpha), where alpha 0 is invisible and 255 is solid.

Two details trip people up:

• The alpha only matters on an SRCALPHA Surface. The screen itself has no alpha channel, so pygame.draw.circle(screen, (255, 0, 0, 50), ...) draws a solid red circle. To get a see-through circle, draw it on an SRCALPHA Surface and blit that.
• Drawing does not blend. It writes your color, alpha included, straight into the Surface's pixels. Blending happens when you blit the Surface onto another one. So three overlapping puffs drawn with alpha 170 make one evenly see-through cloud, not a cloud with darker overlaps.

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 600))
pygame.display.set_caption("Build Once, Draw Many")
clock = pygame.time.Clock()


def make_tree():
    """Draw one tree on its own see-through Surface and return it."""
    tree = pygame.Surface((80, 120), pygame.SRCALPHA)       # starts fully transparent
    pygame.draw.rect(tree, (120, 72, 40), (34, 70, 12, 50))                # trunk
    pygame.draw.circle(tree, (34, 139, 34), (40, 45), 38)                  # leaves
    pygame.draw.circle(tree, (60, 170, 60), (28, 32), 14)                  # lighter patch
    return tree


def make_fog():
    """A wide, pale, half-transparent band."""
    fog = pygame.Surface((800, 120), pygame.SRCALPHA)
    fog.fill((220, 225, 235, 110))
    return fog


tree = make_tree()          # built ONCE, before the loop
fog = make_fog()
tree_spots = [(60, 380), (180, 360), (330, 390), (470, 350), (620, 375)]

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

    screen.fill((135, 206, 235))
    pygame.draw.rect(screen, (76, 175, 80), (0, 470, 800, 130))
    for spot in tree_spots:
        screen.blit(tree, spot)         # the same Surface, stamped five times
    screen.blit(fog, (0, 430))          # the trees show through the fog
    pygame.display.flip()

pygame.quit()

If you want a whole Surface to fade in or out, surface.set_alpha(128) makes every pixel half transparent when it is blitted. Per-pixel alpha (SRCALPHA) is for shapes with see-through parts; set_alpha is for fading the whole thing.

🔤 Text on the Screen

pygame can't draw text directly onto the screen. Instead, a Font renders your text into a brand-new Surface, and you blit that Surface like any other:

font = pygame.font.Font(None, 36)         # None = pygame's built-in font, 36 pixels tall

# ...inside the game loop, in the draw step:
label = font.render(f"Score: {score}", True, (255, 255, 255))
screen.blit(label, (10, 10))

• render(text, antialias, color): True for antialias smooths the letter edges. Add a fourth argument, a background color, to put the text on a solid box so it stays readable over a busy scene.
• Create the font once, before the loop. Loading a font reads a font file from disk; doing that 60 times a second is wasted work. Rendering the text each frame is fine, because the score changes.
• pygame.font.SysFont("arial", 24) uses a font installed on the computer, and quietly falls back to the built-in one if it can't find it.
• The built-in font has no emoji, so they show up as empty boxes. Stick to plain letters, digits and punctuation, or draw little icons with shapes.

🏋️ Practice Exercise: Sunset Scene

"""Sunset Scene: Intro Lesson 2 practice exercise (solution).

A sun sinks behind a green hill while the sky slowly darkens. Every color
the program calculates goes through clamp_color(), so no channel can leave
the 0-255 range. Close the window to quit.
"""
import pygame


WIDTH, HEIGHT = 800, 600
FPS = 60

SKY_DAY = (135, 206, 235)      # light blue at the start
SKY_FADE = (12, 18, 16)        # how much red, green and blue drop per second
SUN_COLOR = (255, 200, 60)
SUN_SPEED = 25                 # pixels per second (downward)
HILL_COLOR = (76, 175, 80)
GROUND_COLOR = (56, 142, 60)
HOUSE_COLOR = (205, 133, 63)
OUTLINE_COLOR = (70, 40, 20)
ROOF_COLOR = (165, 42, 42)
WINDOW_COLOR = (255, 235, 150)
TEXT_COLOR = (240, 240, 240)
LABEL_BG = (30, 30, 40)
CLOUD_SPOTS = [(60, 70), (300, 40), (480, 110)]


def clamp_color(color):
    """Return color with every channel forced to a whole number from 0 to 255."""
    return tuple(max(0, min(255, int(channel))) for channel in color)


def sky_color(seconds):
    """The sky color after the sunset has run for this many seconds."""
    r, g, b = SKY_DAY
    fade_r, fade_g, fade_b = SKY_FADE
    return clamp_color((r - fade_r * seconds, g - fade_g * seconds, b - fade_b * seconds))


def make_cloud():
    """Build a see-through cloud once. The caller blits it as often as it likes."""
    cloud = pygame.Surface((160, 70), pygame.SRCALPHA)     # starts fully transparent
    puff = (255, 255, 255, 170)                            # alpha 170: partly see-through
    pygame.draw.ellipse(cloud, puff, (0, 20, 90, 50))
    pygame.draw.ellipse(cloud, puff, (45, 0, 80, 60))
    pygame.draw.ellipse(cloud, puff, (80, 20, 80, 50))
    return cloud


def draw_house(screen):
    """A house standing on the ground: body, outline, roof, door and window."""
    pygame.draw.rect(screen, HOUSE_COLOR, (300, 360, 200, 150))
    pygame.draw.rect(screen, OUTLINE_COLOR, (300, 360, 200, 150), 4)      # width 4 = outline
    pygame.draw.polygon(screen, ROOF_COLOR, [(285, 360), (515, 360), (400, 270)])
    pygame.draw.rect(screen, OUTLINE_COLOR, (380, 440, 40, 70))            # door
    pygame.draw.rect(screen, WINDOW_COLOR, (320, 390, 45, 40))             # window
    pygame.draw.rect(screen, OUTLINE_COLOR, (320, 390, 45, 40), 3)


def main():
    pygame.init()
    screen = pygame.display.set_mode((WIDTH, HEIGHT))
    pygame.display.set_caption("Sunset Scene")
    clock = pygame.time.Clock()
    font = pygame.font.Font(None, 30)       # fonts are created once, before the loop
    cloud = make_cloud()                    # so is the cloud Surface

    seconds = 0.0
    running = True
    while running:
        dt = clock.tick(FPS) / 1000

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

        seconds += dt
        sun_y = 120 + SUN_SPEED * seconds

        # Draw back to front: whatever is drawn later covers what is already there.
        screen.fill(sky_color(seconds))
        pygame.draw.circle(screen, SUN_COLOR, (620, sun_y), 60)
        pygame.draw.ellipse(screen, HILL_COLOR, (-200, 380, 1200, 440))    # hides the setting sun
        pygame.draw.rect(screen, GROUND_COLOR, (0, 500, WIDTH, 100))
        draw_house(screen)
        for spot in CLOUD_SPOTS:
            screen.blit(cloud, spot)

        label = font.render(f"Sunset: {seconds:.1f} s", True, TEXT_COLOR, LABEL_BG)
        screen.blit(label, (10, 10))
        pygame.display.flip()

    pygame.quit()
    print(f"Final sky color: {sky_color(seconds)}")


if __name__ == "__main__":
    main()

📓 Learning Journal

📝 Summary

You learned to see the window as a grid of pixels with (0, 0) at the top-left and y growing downward, and you filled it with rectangles, circles, ellipses, lines, polygons and text. Colors are RGB tuples, and any color you calculate goes through clamp_color() so it never leaves the 0 to 255 range. You also built your own Surfaces, including see-through SRCALPHA ones, drew on them once, and blitted them as many times as you liked. That build-once, blit-many idea is exactly how images and sprites work later in the course.

🔭 Looking Ahead

Your scene looks good, but you can't touch it yet. In the next lesson, Keyboard, Mouse & Gamepad, you read the player's keys, clicks, mouse wheel and controllers, and make a square run and jump.

❓ Common Questions

🎯 Quick Quiz

🌟 Going Further

• Gradient sky: instead of one fill(), draw 60 horizontal lines, each 10 pixels thick, whose color gets a little darker toward the top. Use clamp_color() for every one.
• Stars at night: once the sky is dark, draw a few small white circles. Make them fade in by drawing them on an SRCALPHA Surface and raising its set_alpha() value over time.
• Rounded corners: pygame.draw.rect takes a border_radius= keyword. Give your house's windows rounded corners.
• Drifting clouds: give each cloud its own x position and add 20 * dt to it every frame, wrapping back to the left when it leaves the screen, as the square did in The Game Loop.
• Read the docs: skim the pygame-ce pages for pygame.draw, pygame.Surface and pygame.font. Find one drawing function or argument you haven't used yet.