The AbstractImage hierarchy

The following sections deal with the various concrete image classes. All images subclass AbstractImage, which provides the basic interface described in previous sections.

abstract_image.png

The AbstractImage class hierarchy.

An image of any class can be converted into a Texture or ImageData using the get_texture and get_image_data methods defined on AbstractImage. For example, to load an image and work with it as an OpenGL texture:

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

There is no penalty for accessing one of these methods if object is already of the requested class. The following table shows how concrete classes are converted into other classes:

Original class .get_texture() .get_image_data()
Texture No change glGetTexImage2D
TextureRegion No change glGetTexImage2D, crop resulting image.
ImageData glTexImage2D [1] No change
ImageDataRegion glTexImage2D [1] No change
CompressedImageData glCompressedTexImage2D [2] N/A [3]
BufferImage glCopyTexSubImage2D [4] glReadPixels

You should try to avoid conversions which use glGetTexImage2D or glReadPixels, as these can impose a substantial performance penalty by transferring data in the "wrong" direction of the video bus, especially on older hardware.

[1](1, 2) ImageData caches the texture for future use, so there is no performance penalty for repeatedly blitting an ImageData.
[2]If the required texture compression extension is not present, the image is decompressed in memory and then supplied to OpenGL via glTexImage2D.
[3]It is not currently possible to retrieve ImageData for compressed texture images. This feature may be implemented in a future release of pyglet. One workaround is to create a texture from the compressed image, then read the image data from the texture; i.e., compressed_image.get_texture().get_image_data().
[4]BufferImageMask cannot be converted to Texture.