From data
to pixels.

Start with a small program that opens a colored window with a title, then closes it a few seconds later. First, you will run it and look at the result. Then you will change one value at a time, predicting what will change on the screen before each run. After each experiment, you will examine the relevant lines of code: where the data comes from, what the program does with it, and why you see that particular result.

Create your first window

Create a new Python file and copy the program below into it. Save the file and run it.

Some lines in the program begin with the # symbol. These are comments, explanations for the person reading the code. Python does not execute them. Comments help explain the purpose of individual actions; throughout this book, the comments in the examples are written in English.

In the preparatory module, you created a window, filled its surface with a color, and displayed the image. Here, you will use those familiar actions but organize the waiting more simply: the program will close the window automatically after a few seconds. Before running it, look at three new calls:

• pg.display.update() shows the prepared image in the window. In preparation, you used pg.display.flip(); for your examples that display the entire surface, both calls let you see the completed frame. You pass no arguments here, so the parentheses are empty.
• pg.event.pump() lets Pygame perform internal event processing and update its state. The call services the window but does not itself define your program's response to the close button.
• pg.time.wait(3000) pauses for approximately 3000 milliseconds. There are 1000 milliseconds in a second, so the window will remain visible for about three seconds.

A note about waiting

The checking program in preparation used a loop to retrieve events regularly and finish when the window was asked to close. Here, there are no loops yet: you call pump once, wait for the specified time, then execute the familiar pg.quit().

For this experiment, wait for the window to close automatically. A single pump() call before a long pause does not replace an event-handling loop. You will return to that loop when you explore loops and conditions in detail.

import pygame as pg
pg.init()

# Set the window size in pixels.
width = 800
height = 600
resolution = (width, height)
screen = pg.display.set_mode(resolution)

title = "Module 0 - A living window"
pg.display.set_caption(title)

# Set the red, green and blue channels.
red = 0
green = 255
blue = 0
background = (red, green, blue)

# Fill the display surface and show the frame.
screen.fill(background)
pg.display.update()

# Process pending system events once, then pause.
pg.event.pump()
pg.time.wait(3000)

pg.quit()

A green window titled Module 0 - A living window should appear on the screen. It will close after about three seconds. If you want another look, just run the program again.

You have produced a visible result using a few numbers, some text, and a sequence of commands. The numbers set the window's dimensions, its color, and how long it stays on the screen. The text appears in the title. The commands determine how to use this data and the order in which to perform the actions.

You can therefore think of a program as a data transformer: it takes input data, processes it according to rules, and produces a result. In your program, that result appears on the screen. In other tasks, it might be a calculated number, new text, a sound, or a file.

In this book, you will learn to follow these transformations: to notice what data a program uses, what it does with that data, and how changing the input values affects the result.

Find the data in the program that determines your window's properties:

• width and height → window size. The values 800 and 600 specify the width and height in pixels.
• red, green, and blue → background color. Together, the values 0, 255, and 0 specify green.
• title → title text. The string Module 0 - A living window appears at the top of the window.
• 3000 → pause duration. The program waits for 3000 milliseconds, about three seconds, then closes the window.

You now have several connections between the code and its visible result. Test them with small experiments: change one value at a time and observe what happens. You will start with the window's width.

Change the window's width

Find the line width = 800 and replace 800 with 400. Before running the program, predict how the window will change. Then run it and compare the result with your prediction.

The window becomes half as wide. Its height stays the same, so the green rectangle is now taller than it is wide. One change was enough to produce a noticeable result.

The names width and height describe the horizontal and vertical dimensions. These names help you understand what the numbers in the program are for.

The statement width = 800 binds the name width to the value 800. Such a name is a variable, and the action performed using the = sign is called assignment. When width appears later in the program, Python uses the value bound to that name.

In your experiment, you replaced width = 800 with width = 400. The next time you ran the program, it used the new value, making the window narrower.

Python does not understand the ordinary meaning of the word width or infer the number's purpose from it. You choose the name to help a human reader. The value becomes the window's width because the program uses it when specifying the window size later on.

Now choose your own width and height values. Make the window square, then wide and short, then narrow and tall. Change one value at a time so you can see what each one controls.