pyglet.image.atlas

Group multiple small images into larger textures.

This module is used by pyglet.resource to efficiently pack small images into larger textures. TextureAtlas maintains one texture; TextureBin manages a collection of atlases of a given size.

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.

New in version 1.1.

exception AllocatorException

The allocator does not have sufficient free space for the requested image size.

class Allocator(width, height)

Rectangular area allocation algorithm.

Initialise with a given width and height, then repeatedly call alloc to retrieve free regions of the area and protect that area from future allocations.

Allocator uses a fairly simple strips-based algorithm. It performs best when rectangles are allocated in decreasing height order.

alloc(width, height)

Get a free area in the allocator of the given size.

After calling alloc, the requested area will no longer be used. If there is not enough room to fit the given area AllocatorException is raised.

Parameters:
  • width (int) – Width of the area to allocate.
  • height (int) – Height of the area to allocate.
Return type:

int, int
Returns:

The X and Y coordinates of the bottom-left corner of the allocated region.
get_fragmentation()

Get the fraction of area that’s unlikely to ever be used, based on current allocation behaviour.

This method is useful for debugging and profiling only.

Return type:float
get_usage()

Get the fraction of area already allocated.

This method is useful for debugging and profiling only.

Return type:float
height
strips
used_area
width
class TextureAtlas(width=2048, height=2048)

Collection of images within a texture.

add(img, border=0)

Add an image to the atlas.

This method will fail if the given image cannot be transferred directly to a texture (for example, if it is another texture). ImageData is the usual image type for this method.

AllocatorException will be raised if there is no room in the atlas for the image.

Parameters:
  • img (AbstractImage) – The image to add.
  • border (int) – Leaves specified pixels of blank space around each image added to the Atlas.
Return type:

TextureRegion
Returns:

The region of the atlas containing the newly added image.
class TextureBin(texture_width=2048, texture_height=2048)

Collection of texture atlases.

TextureBin maintains a collection of texture atlases, and creates new ones as necessary to accommodate images added to the bin.

add(img, border=0)

Add an image into this texture bin.

This method calls TextureAtlas.add for the first atlas that has room for the image.

AllocatorException is raised if the image exceeds the dimensions of texture_width and texture_height.

Parameters:
  • img (AbstractImage) – The image to add.
  • border (int) – Leaves specified pixels of blank space around each image added to the Atlas.
Return type:

TextureRegion
Returns:

The region of an atlas containing the newly added image.