(For more resources on Python, see here.)

So let's get on with it.

Installation prerequisites

We will cover the prerequisites for the installation of Pyglet in this section.

Pyglet

Pyglet provides an API for multimedia application development using Python. It is an OpenGL-based library, which works on multiple platforms. It is primarily used for developing gaming applications and other graphically-rich applications. Pyglet can be downloaded from http://www.pyglet.org/download.html. Install Pyglet version 1.1.4 or later. The Pyglet installation is pretty straightforward.

Windows platform

For Windows users, the Pyglet installation is straightforward—use the binary distribution Pyglet 1.1.4.msi or later.

You should have Python 2.6 installed. For Python 2.4, there are some more dependencies. We won't discuss them in this article, because we are using Python 2.6 to build multimedia applications.

If you install Pyglet from the source, see the instructions under the next sub-section, Other platforms.

Other platforms

The Pyglet website provides a binary distribution file for Mac OS X. Download and install pyglet-1.1.4.dmg or later.

On Linux, install Pyglet 1.1.4 or later if it is available in the package repository of your operating system. Otherwise, it can be installed from source tarball as follows:

• Download and extractthetarballextractthetarball the tarball pyglet-1.1.4.tar.gz or a later version.
• Make sure that python is a recognizable command in shell. Otherwise, set the PYTHONPATH environment variable to the correct Python executable path.
• In a shell window, change to the mentioned extracted directory and then run the following command:

  python setup.py install

• Review the succeeding installation instructions using the readme/install instruction files in the Pyglet source tarball.

If you have the package setuptools (http://pypi.python.org/pypi/setuptools) the Pyglet installation should be very easy. However, for this, you will need a runtime egg of Pyglet. But the egg file for Pyglet is not available at http://pypi.python.org. If you get hold of a Pyglet egg file, it can be installed by running the following command on Linux or Mac OS X. You will need administrator access to install the package:

$sudo easy_install -U pyglet

Summary of installation prerequisites

Testing the installation

Before proceeding further, ensure that Pyglet is installed properly. To test this, just start Python from the command line and type the following:

>>>import pyglet

If this import is successful, we are all set to go!

A primer on Pyglet

Pyglet provides an API for multimedia application development using Python. It is an OpenGL-based library that works on multiple platforms. It is primarily used for developing gaming and other graphically-rich applications. We will cover some important aspects of Pyglet framework.

Important components

We will briefly discuss some of the important modules and packages of Pyglet that we will use. Note that this is just a tiny chunk of the Pyglet framework. Please review the Pyglet documentation to know more about its capabilities, as this is beyond the scope of this article.

Window

The pyglet.window.Window module provides the user interface. It is used to create a window with an OpenGL context. The Window class has API methods to handle various events such as mouse and keyboard events. The window can be viewed in normal or full screen mode. Here is a simple example of creating a Window instance. You can define a size by specifying width and height arguments in the constructor.

win = pyglet.window.Window()

The background color for the image can be set using OpenGL call glClearColor, as follows:

pyglet.gl.glClearColor(1, 1, 1, 1)

This sets a white background color. The first three arguments are the red, green, and blue color values. Whereas, the last value represents the alpha. The following code will set up a gray background color.

pyglet.gl.glClearColor(0.5, 0.5, 0.5, 1)

The following illustration shows a screenshot of an empty window with a gray background color.

Image

The pyglet.image module enables the drawing of images on the screen. The following code snippet shows a way to create an image and display it at a specified position within the Pyglet window.

img = pyglet.image.load('my_image.bmp')
x, y, z = 0, 0, 0
img.blit(x, y, z)

A later section will cover some important operations supported by the pyglet.image module.

Sprite

This is another important module. It is used to display an image or an animation frame within a Pyglet window discussed earlier. It is an image instance that allows us to position an image anywhere within the Pyglet window. A sprite can also be rotated and scaled. It is possible to create multiple sprites of the same image and place them at different locations and with different orientations inside the window.

Animation

Animation module is a part of pyglet.image package. As the name indicates, pyglet.image.Animation is used to create an animation from one or more image frames. There are different ways to create an animation. For example, it can be created from a sequence of images or using AnimationFrame objects. An animation sprite can be created and displayed within the Pyglet window.

AnimationFrame

This creates a single frame of an animation from a given image. An animation can be created from such AnimationFrame objects. The following line of code shows an example.

animation = pyglet.image.Animation(anim_frames)

anim_frames is a list containing instances of AnimationFrame.

Clock

Among many other things, this module is used for scheduling functions to be called at a specified time. For example, the following code calls a method moveObjects ten times every second.

pyglet.clock.schedule_interval(moveObjects, 1.0/10)

Displaying an image

In the Image sub-section, we learned how to load an image using image.blit. However, image blitting is a less efficient way of drawing images. There is a better and preferred way to display the image by creating an instance of Sprite. Multiple Sprite objects can be created for drawing the same image. For example, the same image might need to be displayed at various locations within the window. Each of these images should be represented by separate Sprite instances. The following simple program just loads an image and displays the Sprite instance representing this image on the screen.

1  import pyglet
2
3  car_img= pyglet.image.load('images/car.png')
4  carSprite = pyglet.sprite.Sprite(car_img)
5  window = pyglet.window.Window()
6  pyglet.gl.glClearColor(1, 1, 1, 1)
7
8  @window.event
9  def on_draw():
10   window.clear()
11   carSprite.draw()
12
13 pyglet.app.run()

On line 3, the image is opened using pyglet.image.load call. A Sprite instance corresponding to this image is created on line 4. The code on line 6 sets white background for the window. The on_draw is an API method that is called when the window needs to be redrawn. Here, the image sprite is drawn on the screen. The next illustration shows a loaded image within a Pyglet window.

In various examples in this article, the file path strings are hardcoded. We have used forward slashes for the file path. Although this works on Windows platform, the convention is to use backward slashes. For example, images/car.png is represented as imagescar.png. Additionally, you can also specify a complete path to the file by using the os.path.join method in Python. Regardless of what slashes you use, the os.path.normpath will make sure it modifies the slashes to fit to the ones used for the platform. The use of oos.path.normpath is illustrated in the following snippet:

import os
original_path = 'C:/images/car.png"
new_path = os.path.normpath(original_path)

The preceding image illustrates Pyglet window showing a still image.

Mouse and keyboard controls

The Window module of Pyglet implements some API methods that enable user input to a playing animation. The API methods such as on_mouse_press and on_key_press are used to capture mouse and keyboard events during the animation. These methods can be overridden to perform a specific operation.

Adding sound effects

The media module of Pyglet supports audio and video playback. The following code loads a media file and plays it during the animation.

1  background_sound = pyglet.media.load(
2           'C:/AudioFiles/background.mp3',
3           streaming=False)
4  background_sound.play()

The second optional argument provided on line 3 decodes the media file completely in the memory at the time the media is loaded. This is important if the media needs to be played several times during the animation. The API method play() starts streaming the specified media file.