Intro tutorial, basics


I want to write this tutorials about how to blit images onto screen using pygame. To be able to use pygame you will have to use python. Pygame is actually a wrapper for SDL (simple direct media), the cross-platform multi media library. Before you start using pygame I recommend that you learn python a bit, although it is not difficult but it makes things even easier.

top | back to tutorials overview

Where to get help...

If you encounter something you don't understand try to look it up in the help, either in the help for python or the in the pygame documentation. It is possible that the pygame documentation is a bit inaccurate. To get the exact help you can always look it up in the shell like this:
Python 2.4.1 (#65, Mar 30 2005, 09:13:57) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import pygame
>>> help(pygame.event.get)
Help on built-in function get in module pygame.event:

    pygame.event.get([type]) -> list of Events
    get all of an event type from the queue

    Pass this a type of event that you are interested in, and it will
    return a list of all matching event types from the queue. If no
    types are passed, this will return all the events from the queue.
    You may also optionally pass a sequence of event types. For
    example, to fetch all the keyboard events from the queue, you
    would call, 'pygame.event.get([KEYDOWN,KEYUP])'.

Instead of pygame you can use the help() command on any function or class or module, e.g. help(pygame.event.Event) or help(pygame.event).

top | back to tutorials overview

The minimal code

Sure, there are some other tutorials out there and I recommend to take a look at them and I hope, I don't repeat much that has already been said. I recommend to adjust your coding style to the PEP8 guidelines because then you will not have any trouble if you want to publish your code later. I try to write it according to these rules, but if you find anything deviating just tell me. Thanks.
To get us started I will present you the minimal pygame code needed for a program.
# import the pygame module, so you can use it
import pygame

# define a main function
def main():
    # initialize the pygame module
    # load and set the logo
    logo = pygame.image.load("logo32x32.png")
    pygame.display.set_caption("minimal program")
    # create a surface on screen that has the size of 240 x 180
    screen = pygame.display.set_mode((240,180))
    # define a variable to control the main loop
    running = True
    # main loop
    while running:
        # event handling, gets all event from the event queue
        for event in pygame.event.get():
            # only do something if the event is of type QUIT
            if event.type == pygame.QUIT:
                # change the value to False, to exit the main loop
                running = False
# run the main function only if this module is executed as the main script
# (if you import this as a module then nothing is executed)
if __name__=="__main__":
    # call the main function
Function documentation: download source.

This should show you an empty window like the following image.
empty pygame window
It just sits there doing nothing. The only thing you can do is close it. A QUIT event is generated when you click on the close button and since we handle the QUIT event in the main loop it will actually close. Make sure you understand what it is done in this code because I will use it as a basis to all other examples.

Perhaps you ask yourself how to run this script. This is simple: either you can just doubleclick it and it will run or you have to open a shell/command in that directory. Then type either just the name of the "*.py" file you want to run or you can run it by typing "python *.py" where *.py is the file you want to run. I recommend that you open a shell because in case of an error you can see the traceback and find the place where the error happened.

As for any tutorial here, I would appreciate any comments, ideas, suggestions or any feedback. Thanks.

top | back to tutorials overview

What a surface is...

In pygame there is a object called surface for representing an image. The surface is a data structure to hold the information needed for the image. A surface can have different formats. For the different formats refer to the pygame documentation. There are also some ways to improve blitting (term for drawing a surface) speed. Two function exists to do that: convert() and convert_alpha() (if the image has per pixel alpha, transparent areas). They convert the surface to the format of the video surface (the screen surface) because it is faster to blit a surface to another using the same format. I found some info about the blitting speeds here: !broken link:"

top | back to tutorials overview

I think, now you can start with the other, hopefully more interesting tutorials.