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.

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.

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.

__init__(width: int, height: int) → None: Create an Allocator of the given size.

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

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

If a suitable position can be found for the requested size, the position will be marked as in-use and returned. (The same position will never be returned twice). If there is not enough room to fit the given area, AllocatorException is raised.

Return type:: tuple[int, int]

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. This works similarly to TextureBin, but it manages TextureArrays instead of TextureAtlases.

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

add(img: ImageData) → TextureArrayRegion

Add an image into this texture array bin.

This method calls 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.

Return type:: TextureArrayRegion

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.

__init__(width: int = 2048, height: int = 2048) → None: Create a Texture Atlas of the given size.

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

Add ImageData to the atlas.

Given ImageData, add it to the Atlas and return a new TextureRegion object. An optional border argument can be passed, which will leave the specified number of blank pixels around the added ImageData. This can be useful in certain situations and blend modes, where neighboring pixel data can “bleed” into the edges.

This method will fail if the given image cannot be transferred directly to a texture (for example, if it is not an instance of ImageData, such as another Texture). AllocatorException will be raised if there is no room in the atlas for the image.

Return type:: TextureRegion

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.

__init__(texture_width: int = 2048, texture_height: int = 2048) → None: Create a texture bin for holding atlases of the given size.

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

Add an image into this texture bin.

This method calls 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.

Return type:: TextureRegion