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.


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.