pyglet.image.atlas

Group multiple small images into larger Textures.

This module provides classes to efficiently pack small images into larger Textures. This can have major performance benefits when dealiing with a large number of images.

TextureAtlas maintains one texture; TextureBin manages a collection of atlases of a given size. TextureArrayBin works similarly except for :py:class:`~pyglet.image.TextureArray`s instead of altases.

This module is used internally by the pyglet.resource module.

Example usage:

# Load images from disk
car_image = pyglet.image.load('car.png')
boat_image = pyglet.image.load('boat.png')

# Pack these images into one or more textures
bin = TextureBin()
car_texture = bin.add(car_image)
boat_texture = bin.add(boat_image)

The result of TextureBin.add() is a TextureRegion containing the image. Once added, an image cannot be removed from a bin (or an atlas); nor can a list of images be obtained from a given bin or atlas – it is the application’s responsibility to keep track of the regions returned by the add methods.

Added in version 1.1.

exception AllocatorException: The allocator does not have sufficient free space for the requested image size.

class Allocator

Rectangular area allocation algorithm.

An Allocator is initialized with a specified width and height. The alloc() method can then be called to retrieve free regions of that area (and protect them from future allocations).

Allocator uses a fairly simple strips-based algorithm. It performs best when rectangles are allocated of the same size, or in decreasing height order.

height

strips

used_area

width

class TextureArrayBin

Collection of texture arrays.

TextureArrayBin maintains a collection of texture arrays, and creates new ones as necessary as the depth is exceeded. This works similarly to TextureBin, but it manages TextureArrays instead of TextureAtlases.

class TextureAtlas

A large Texture made up of multiple smaller images.

A TextureAtlas is one maximally sized Texture which is made up of multiple smaller Images. This can improve rendering performance by allowing all the Images to be drawn together with a single Texture bind, rather than multiple tiny Texture binds per draw.

When creating a TextureAtlas instance, a new Texture object will be created at the requested size. If the maximum texture size supported by the OpenGL driver is less than requested, the smaller of the two will be used.

class TextureBin

Collection of TextureAtlases.

TextureBin maintains a collection of TextureAtlases, and creates new ones as necessary to accommodate adding an unbound number of Images. When one TextureAltas is full, a new one is automatically created to fit the next ImageData.