Drawing Basics

The Screen Object

While the pygame API and documentation is quite clear (see the pygame.draw documentation, for example), most of the pygame drawing operations take place on a screen, which is rendered on a specific display.

The way that the code we entered in the previous page works is it initializes the display in the __init__ function, and it then allows us to access a field named 'screen', where all of the actual drawing and graphics work is done in pygame (you pass a reference to this screen to most drawing functions).

You can see how this works by looking at the 'test' function we added and called:
Download: file
# Fill the screen with red (255, 0, 0)
red = (255, 0, 0)
self.screen.fill(red)
# Update the display
pygame.display.update()
This code references the 'screen' provided in the class (self.screen since we're referencing it from inside the class), and calls the fill method.  Once we are done all of our drawing, we tell pygame to update the entire display to take into account these changes, which is done with:
Download: file
pygame.display.update()
This is actually an important point about pygame:
No drawing will take place on the display until pygame.display.update() is called!
This is both an intentional and an intelligent choice.  By doing all of your drawing code at once,and only updating the screen when the drawing is complete, you can benefit from something called double-buffering, which makes all of your drawing appear instant, rather than seeing controls get rendered one at a time in a sequential, sluggish-feeling way.

Accessing the Screen

Since we made a wrapper class called pyscope which takes care of the low-level framebuffer initialisation, etc., how do you access the screen object from outside the class?  It's easy ... any time you want to do any drawing, you just need to access the screen as follows:
Download: file
# Create an instance of the PyScope class
scope = pyscope()
# Fill the screen with yellow
scope.screen.fill((255, 255, 0))
# Update the display
pygame.display.update()

# Wait 10 seconds
time.sleep(10)
You can test this out by placing it at the bottom of your file with no indents, and you should see a yellow screen for ten seconds when you run it.
This guide was first published on Oct 19, 2012. It was last updated on Oct 19, 2012. This page (Drawing Basics) was last updated on Nov 17, 2019.