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

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.

__init__(width: int, height: int) → None

Create an Allocator of the given size.

Parameters:

widthint: Width of the allocation region.
heightint: Height of the allocation region.

alloc(width: int, height: int) → Tuple[int, int]

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:

widthint: Width of the area to allocate.
heightint: 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() → float

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() → float

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 TextureArrayBin

Collection of texture arrays.

TextureArrayBin maintains a collection of texture arrays, and creates new ones as necessary as the depth is exceeded.

__init__( texture_width: int = 2048, texture_height: int = 2048, max_depth: int | None = None, ) → None

add( img: AbstractImage, ) → TextureArrayRegion

Add an image into this texture array bin.

This method calls TextureArray.add for the first array that has room for the image.

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

Parameters:

img~pyglet.image.AbstractImage: The image to add.

Return type:

TextureArrayRegion

Returns:

The region of an array containing the newly added image.

class TextureAtlas

Collection of images within a texture.

__init__(width: int = 2048, height: int = 2048) → None

Create a texture atlas of the given size.

Parameters:

widthint: Width of the underlying texture.
heightint: Height of the underlying texture.

add( img: AbstractImage, border: int = 0, ) → TextureRegion

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~pyglet.image.AbstractImage: The image to add.
borderint: 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

Collection of texture atlases.

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

__init__(texture_width: int = 2048, texture_height: int = 2048) → None

Create a texture bin for holding atlases of the given size.

Parameters:

texture_widthint: Width of texture atlases to create.
texture_heightint: Height of texture atlases to create.
borderint: Leaves specified pixels of blank space around each image added to the Atlases.

add( img: AbstractImage, border: int = 0, ) → TextureRegion

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~pyglet.image.AbstractImage: The image to add.
borderint: 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.