Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 41 ยท Window, Loop and Events

The Window and Display

Control the Pygame window - size, caption, icon, resizable and fullscreen modes, vsync, scaling a fixed-size game to any window, and flip() versus update().

The pygame.display module owns the window. You already know set_mode(), set_caption() and flip(). This lesson covers the rest of what you need to control: window flags (resizable, fullscreen, borderless), the icon, reading the window size, scaling a game to fit different windows, and the difference between flip() and update().

set_mode and its flags

Python
screen = pygame.display.set_mode((960, 540), flags=0, vsync=0)

The second argument, flags, is a bit mask. Combine flags with |:

Flag Effect
pygame.RESIZABLE The player can drag the window edges
pygame.FULLSCREEN Take over the screen
pygame.NOFRAME No title bar or border
pygame.SCALED Keep a fixed logical size; Pygame scales it to the window or screen
pygame.DOUBLEBUF Double buffering (default on modern systems)
pygame.OPENGL Use OpenGL for 3D (advanced)
Python
# A resizable window whose contents scale automatically
screen = pygame.display.set_mode((320, 180), pygame.RESIZABLE | pygame.SCALED, vsync=1)

vsync=1 asks the graphics driver to synchronize with the monitor refresh, which removes screen tearing. It is only honored together with SCALED or OPENGL in many setups.

Caption and icon

Python
pygame.display.set_caption("Space Dodger")

icon = pygame.image.load("assets/icon.png")
pygame.display.set_icon(icon)        # call BEFORE set_mode for best results on some systems

set_caption(title) changes the title bar. The icon should be a small image (32 by 32 pixels works everywhere) and is shown in the title bar and task bar. Loading images is covered in Images and Transforms.

Reading the window size

Python
width, height = screen.get_size()
print(screen.get_width(), screen.get_height())
rect = screen.get_rect()              # Rect(0, 0, width, height) - great for centering
print(pygame.display.get_window_size())

Using screen.get_rect() is the idiom for positioning things relative to the window: rect.center, rect.midbottom, rect.right.

Resizing

With RESIZABLE you will receive events when the player resizes. In pygame-ce the surface returned by set_mode updates itself, and you get a pygame.WINDOWRESIZED (or VIDEORESIZE) event with the new size:

Python
for event in pygame.event.get():
    if event.type == pygame.VIDEORESIZE:
        print("new size:", event.w, event.h)
        # recompute layouts here

Fullscreen toggling is one call: pygame.display.toggle_fullscreen(). A typical pattern binds it to F11.

Hard-coding positions for a 800 by 600 window breaks when the window changes size. Two good strategies exist:

  1. Layout relative to the window: compute positions from screen.get_width() every frame or on resize.
  2. Fixed logical resolution: draw the game on an off-screen surface of fixed size (say 320 by 180) and scale that surface to the window. Retro and pixel-art games almost always do this, and pygame.SCALED does it for you.

Try it: letterboxing

When the window's aspect ratio differs from your game's, you show the game in the largest centered rectangle that fits and leave bars at the sides. Rect.fit computes it. This runs without a window because it is pure geometry.

Python Fit a 16:9 game into any window

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.

A mouse position in the window must be converted back to game coordinates by subtracting shown.topleft and dividing by scale. pygame.SCALED does this conversion for you.

Try it: render at low resolution, then scale up

This is the fixed-resolution technique in miniature. We draw a tiny scene on a 16 by 8 surface and scale it with pygame.transform.scale. In a real game the scaled surface is blitted to the screen.

Python Draw small, scale up

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.

transform.scale uses nearest-neighbor, which keeps pixel art crisp. smoothscale blends pixels and suits photographs.

flip() versus update()

Pygame draws into a back buffer. Two functions publish it:

  • pygame.display.flip() updates the whole screen. Simple, always correct.
  • pygame.display.update() with no arguments does the same. With a rect or list of rects it refreshes only those regions.
Python
pygame.display.update(player_rect)                 # one region
pygame.display.update([player_rect, enemy_rect])   # several

Updating only changed regions ("dirty rects") used to give big speedups on old computers. On modern hardware-accelerated setups the full flip() is normally fast enough, and partial updates may be ignored or even cause glitches with some drivers, so start with flip().

Try it: how much do dirty rects save?

To see why dirty rects exist, this stand-in compares the pixels in a full update with the pixels in the changed regions only.

Python Area of dirty rects

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.

Useful display functions

Call Meaning
pygame.display.get_surface() The current screen Surface (or None)
pygame.display.Info() Desktop size and driver info (call before set_mode to read the monitor size)
pygame.display.list_modes() Supported fullscreen sizes
pygame.display.toggle_fullscreen() Switch fullscreen on or off
pygame.display.iconify() Minimize the window
pygame.mouse.set_visible(False) Hide the mouse cursor

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you combine two display flags?

    Flags are bit masks, so you combine them with |.
  2. 2. What is a good way to make a pixel-art game look right in any window size?

    A fixed logical resolution keeps layout and gameplay identical, and scaling adapts it to the window.
  3. 3. What does flip() update?

    flip() shows the entire back buffer. update(rects) can limit it to given regions.
  4. 4. Which call returns a rect convenient for centering things on the screen?

    screen.get_rect() gives Rect(0, 0, w, h), so rect.center, rect.midtop and friends are ready to use.

Summary

  • Flags such as RESIZABLE, FULLSCREEN, NOFRAME and SCALED are combined with |.
  • Set the caption and icon; read the size with get_size() or get_rect().
  • A fixed logical resolution scaled to the window keeps games consistent.
  • flip() updates everything; update(rects) can update parts.
  • Rect.fit computes letterbox rectangles.

Next: The Game Loop