Loading an image

Images can be loaded using the pyglet.image.load function:

kitten = pyglet.image.load('kitten.png')

If the image is distributed with your application, consider using the pyglet.resource module (see Application resources).

Without any additional arguments, load will attempt to load the filename specified using any available image decoder. This will allow you to load PNG, GIF, JPEG, BMP and DDS files, and possibly other files as well, depending on your operating system and additional installed modules (see the next section for details). If the image cannot be loaded, an ImageDecodeException will be raised.

You can load an image from any file-like object providing a read method by specifying the file keyword parameter:

kitten_stream = open('kitten.png', 'rb')
kitten = pyglet.image.load('kitten.png', file=kitten_stream)

In this case the filename kitten.png is optional, but gives a hint to the decoder as to the file type (it is otherwise unused).

pyglet provides the following image decoders:

Module Class Description
pyglet.image.codecs.dds DDSImageDecoder Reads Microsoft DirectDraw Surface files containing compressed textures
pyglet.image.codecs.gdiplus GDIPlusDecoder Uses Windows GDI+ services to decode images.
pyglet.image.codecs.gdkpixbuf2 GdkPixbuf2ImageDecoder Uses the GTK-2.0 GDK functions to decode images.
pyglet.image.codecs.pil PILImageDecoder Wrapper interface around PIL Image class.
pyglet.image.codecs.png PNGImageDecoder PNG decoder written in pure Python.
pyglet.image.codecs.quicktime QuickTimeImageDecoder Uses Mac OS X QuickTime to decode images.

Each of these classes registers itself with pyglet.image with the filename extensions it supports. The load function will try each image decoder with a matching file extension first, before attempting the other decoders. Only if every image decoder fails to load an image will ImageDecodeException be raised (the origin of the exception will be the first decoder that was attempted).

You can override this behaviour and specify a particular decoding instance to use. For example, in the following example the pure Python PNG decoder is always used rather than the operating system's decoder:

from pyglet.image.codecs.png import PNGImageDecoder
kitten = pyglet.image.load('kitten.png', decoder=PNGImageDecoder())

This use is not recommended unless your application has to work around specific deficiences in an operating system decoder.