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: int, height: int)
Rectangular area allocation algorithm.
Initialise with a given
width
andheight
, 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: 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.
- 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
- get_usage() float
Get the fraction of area already allocated.
This method is useful for debugging and profiling only.
- Return type
- height
- strips
- used_area
- width
- class TextureArrayBin(texture_width: int = 2048, texture_height: int = 2048, max_depth: Optional[int] = None)
Collection of texture arrays.
TextureArrayBin
maintains a collection of texture arrays, and creates new ones as necessary as the depth is exceeded.- 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
andtexture_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(width: int = 2048, height: int = 2048)
Collection of images within a 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
- Returns
The region of the atlas containing the newly added image.
- class TextureBin(texture_width: int = 2048, texture_height: int = 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: 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
andtexture_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
- Returns
The region of an atlas containing the newly added image.