Graphical displays with Python and Pygame

Lead Image © andrew grossman,

Game On

As its name implies, Pygame is a set of Python modules designed to write games. However, many Pygame modules are useful for any number of projects. We introduce you to a few Pygame modules that you can use to create custom graphical displays for your project.

Pygame modules load, scale, and display existing graphics in traditional bitmap formats. A Python/Pygame script a dozen lines long will show an image from disk; or, with the draw module, you can create your own charts and graphs, annotate photos you've loaded, or overlay a camera image with calculated information.

In this article, I will look at pygame.display, pygame.rect, pygame.font, along with some typical Pygame classes to make your game programming a little easier.

Setting Up Pygame

Most Pygame modules [1] have to be initialized before you can use them. The pygame.init() submodule can set up absolutely everything, but unless you're actually using everything it is best to initialize modules individually; otherwise, a lot of memory is wasted on unused components.

To initialize individual modules, just call their init() function directly. The display module is the primary pygame interface, so I'll start with that:


Once the display is initialized, you can create your graphics window:

screen = pygame.display.set_mode( ( 1024, 768 ) )

Note that I assigned the result to the variable screen, which is how I'll reference the display window for the rest of the program. If you want a full-screen window, add the argument pygame.FULLSCREEN after the window dimensions:

screen = pygame.display.set_mode( ( 1024, 768 ), pygame.FULLSCREEN )

See the "Raspberry Pi Display" sidebar for special instructions on setting up your Rasp Pi display.

Raspberry Pi Display

Setting up a Pygame display on a Raspberry Pi can be a little different from other environments. If you are running inside the X Window system (i.e., you entered startx on the command line or chose Start desktop on boot? in raspi-config), then carry on as usual; you can safely disregard these instructions.

However, if you are running straight from a command line without X windows, you need to check your console resolution. To do this, look in the /boot/config.txt file for framebuffer_width and framebuffer_height. By removing the # at the beginning of the line (if present), whatever values you enter define the console resolution once you reboot.

In your Python/Pygame program, if your resolution matches the 1024x768 settings used in the code above, you have full-screen resolution. If your settings are smaller, the display is padded with black borders. In most cases, you also need to sudo python to access the framebuffer.

Flipping the Display

Pygame only updates the screen when asked, which allows drawing operations to happen in memory (a relatively fast operation) and only redraws the display (a slow operation) once the program is done drawing. With the command pygame.display.flip(), the contents of the screen variable are drawn to the screen (see the "Glossary" sidebar). It's good practice to do all of your drawing and then call flip() once you are finished. Although flip() will work with animation or on-screen movement, it can be very slow because you redraw the entire screen each time.


  • Surface: Something that represents graphical information.
  • Screen: The surface you see.
  • Blit: Copy one surface onto another.

Pygame provides an alternative display redraw command called update(). On the surface, update() is the same as flip() with one important difference: update() accepts a list of screen areas to redraw. Rather than redrawing the entire screen, it only updates the requested parts, which can create a dramatic speed increase! I've included an example class in which each method that might draw something returns where it drew updates.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Raspberry Pi Geek

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content