Pygame Commands

One of the most common applications of programming is to create games, or at least visual displays.  Pygame is a comprehensive library of commands designed for exactly this purpose.  To create a graphics window, use the following code.

import pygame
pygame.init()
screen = pygame.display.set_mode([601,601])
screen.fill([0,0,0])
pygame.display.flip()

    ...    [graphics program goes here]    ....

raw_input("Press ENTER to close the graphics window")
pygame.quit()

The first two lines load the pygame module and perform some necessary preliminary setup.  The third line will open a window that is 601 pixels wide and high.  This may seem like a strange choice, but this way we can refer to the leftmost position on the screen as 0 and the rightmost position as 600, which is convenient.  Notice that there are 601 numbers from 0 to 600; that's why we use 601 for the width.

In general, pygame refers to each location on a graphics window via a pair of coordinates (x,y), where x and y represent the number of pixels to the right and down from the upper left corner, which serves as the reference point (origin).  Thus the coordinates of the middle of the right edge are (600,300).  HEADS-UP: be aware that the vertical coordinate is the opposite of what you might expect, in that it measures how far down (rather than how far up) from the origin we should move.

The fourth line fills the screen with a particular background color (in this case black), while the fifth line then displays the result.  Separate commands exist so that it becomes possible to make a variety of changes to the screen before updating the screen with the results all at once.  This makes animation more smooth, for instance.

A brief word about color is in order.  Pygame uses the RGB system, in which a color is described by a triple of numbers [red,green,blue], each value an integer from 0 (off) to 255 (fully on).  That's why [0,0,0] corresponds to black, while [255,255,255] gives white.  A few more standard colors are [0,0,255] (pure blue), [150,150,250] (light blue), and [200,200,0] (yellow).  The best way to get used to the RGB system is simply to experiment with different combinations of numbers.

Since a pygame window (usually) automatically closes at the end of the program that created it, we include the last two lines of code above to allow the user to close the window only after having a chance to admire the display.

We will be primarily drawing lines, rectangles, and circles in our graphics windows.  To draw a line segment we must specify its color, the start point, the end point, and the thickness.  This is done by typing

pygame.draw.line(screen, [r,g,b], [x1,y1], [x2,y2], w)

Here the triple [r,g,b] is the color, [x1,y1] are the coordinates of one end of the line segment, [x2,y2] are the coordinates of the other end, and w represents the thickness of the line in pixels.  So to draw a medium-thick green diagonal line from the top right to bottom left of our screen we would use the code

pygame.draw.line(screen, [0,255,0], [600,0], [0,600], 3)
pygame.display.flip()

Predictably, swapping the order of the start and end points has no effect on what is drawn.  Also, it is OK for the start and end points to be off the screen; you will just see the portion of your line segment that does cross within the viewing window.  (This principle applies to circles and rectangles below as well.)  WARNING: one of the most common errors to make is to forget to "flip the display."  Your program will run perfectly, but you won't see anything on the screen!

To obtain a rectangle you must specify the color, the top left corner, the width and height, and the thickness.  (Note that if the thickness is omitted or set to 0 pygame will draw a solid, filled in rectangle.)  The command looks like

pygame.draw.rect(screen, [r,g,b], [x,y,width,height], w)

So to display a solid dark purple rectangle that fills the middle of the left half of the screen, one would use the code

pygame.draw.rect(screen, [255,50,255], [0,200,300,200])
pygame.display.flip()

Finally, a circle is specified by giving the color, coordinates of center, radius, and thickness.  (Just as with rectangles, thickness 0 means a solid circle.)  So we type

pygame.draw.circle(screen, [r,g,b], [x,y], r, w)

Therefore to obtain a small thin light red circle in the upper right part of the screen type

pygame.draw.circle(screen, [255,180,180], [500,100], 40, 1)
pygame.display.flip()