242 lines
8.0 KiB
Python
242 lines
8.0 KiB
Python
"""Group multiple small images into larger textures.
|
|
|
|
This module is used by :py:mod:`pyglet.resource` to efficiently pack small
|
|
images into larger textures. :py:class:`~pyglet.image.atlas.TextureAtlas` maintains one texture;
|
|
:py:class:`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 :py:meth:`TextureBin.add` is a :py:class:`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.
|
|
|
|
.. versionadded:: 1.1
|
|
"""
|
|
|
|
import pyglet
|
|
|
|
|
|
class AllocatorException(Exception):
|
|
"""The allocator does not have sufficient free space for the requested
|
|
image size."""
|
|
pass
|
|
|
|
|
|
class _Strip:
|
|
__slots__ = 'x', 'y', 'max_height', 'y2'
|
|
|
|
def __init__(self, y, max_height):
|
|
self.x = 0
|
|
self.y = y
|
|
self.max_height = max_height
|
|
self.y2 = y
|
|
|
|
def add(self, width, height):
|
|
assert width > 0 and height > 0
|
|
assert height <= self.max_height
|
|
|
|
x, y = self.x, self.y
|
|
self.x += width
|
|
self.y2 = max(self.y + height, self.y2)
|
|
return x, y
|
|
|
|
def compact(self):
|
|
self.max_height = self.y2 - self.y
|
|
|
|
|
|
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.
|
|
"""
|
|
__slots__ = 'width', 'height', 'strips', 'used_area'
|
|
|
|
def __init__(self, width, height):
|
|
"""Create an `Allocator` of the given size.
|
|
|
|
:Parameters:
|
|
`width` : int
|
|
Width of the allocation region.
|
|
`height` : int
|
|
Height of the allocation region.
|
|
|
|
"""
|
|
assert width > 0 and height > 0
|
|
self.width = width
|
|
self.height = height
|
|
self.strips = [_Strip(0, height)]
|
|
self.used_area = 0
|
|
|
|
def alloc(self, 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.
|
|
|
|
:rtype: int, int
|
|
:return: The X and Y coordinates of the bottom-left corner of the
|
|
allocated region.
|
|
"""
|
|
for strip in self.strips:
|
|
if self.width - strip.x >= width and strip.max_height >= height:
|
|
self.used_area += width * height
|
|
return strip.add(width, height)
|
|
|
|
if self.width >= width and self.height - strip.y2 >= height:
|
|
self.used_area += width * height
|
|
strip.compact()
|
|
newstrip = _Strip(strip.y2, self.height - strip.y2)
|
|
self.strips.append(newstrip)
|
|
return newstrip.add(width, height)
|
|
|
|
raise AllocatorException('No more space in %r for box %dx%d' % (self, width, height))
|
|
|
|
def get_usage(self):
|
|
"""Get the fraction of area already allocated.
|
|
|
|
This method is useful for debugging and profiling only.
|
|
|
|
:rtype: float
|
|
"""
|
|
return self.used_area / float(self.width * self.height)
|
|
|
|
def get_fragmentation(self):
|
|
"""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.
|
|
|
|
:rtype: float
|
|
"""
|
|
# The total unused area in each compacted strip is summed.
|
|
if not self.strips:
|
|
return 0.0
|
|
possible_area = self.strips[-1].y2 * self.width
|
|
return 1.0 - self.used_area / float(possible_area)
|
|
|
|
|
|
class TextureAtlas:
|
|
"""Collection of images within a texture."""
|
|
|
|
def __init__(self, width=2048, height=2048):
|
|
"""Create a texture atlas of the given size.
|
|
|
|
:Parameters:
|
|
`width` : int
|
|
Width of the underlying texture.
|
|
`height` : int
|
|
Height of the underlying texture.
|
|
|
|
"""
|
|
max_texture_size = pyglet.image.get_max_texture_size()
|
|
width = min(width, max_texture_size)
|
|
height = min(height, max_texture_size)
|
|
|
|
self.texture = pyglet.image.Texture.create(width, height)
|
|
self.allocator = Allocator(width, height)
|
|
|
|
def add(self, 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).
|
|
:py:class:`~pyglet.image.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.
|
|
`border` : int
|
|
Leaves specified pixels of blank space around
|
|
each image added to the Atlas.
|
|
|
|
:rtype: :py:class:`~pyglet.image.TextureRegion`
|
|
:return: The region of the atlas containing the newly added image.
|
|
"""
|
|
x, y = self.allocator.alloc(img.width + border*2, img.height + border*2)
|
|
self.texture.blit_into(img, x+border, y+border, 0)
|
|
return self.texture.get_region(x+border, y+border, img.width, img.height)
|
|
|
|
|
|
class TextureBin:
|
|
"""Collection of texture atlases.
|
|
|
|
:py:class:`~pyglet.image.atlas.TextureBin` maintains a collection of texture atlases, and creates new
|
|
ones as necessary to accommodate images added to the bin.
|
|
"""
|
|
|
|
def __init__(self, texture_width=2048, texture_height=2048):
|
|
"""Create a texture bin for holding atlases of the given size.
|
|
|
|
:Parameters:
|
|
`texture_width` : int
|
|
Width of texture atlases to create.
|
|
`texture_height` : int
|
|
Height of texture atlases to create.
|
|
`border` : int
|
|
Leaves specified pixels of blank space around
|
|
each image added to the Atlases.
|
|
|
|
"""
|
|
max_texture_size = pyglet.image.get_max_texture_size()
|
|
self.texture_width = min(texture_width, max_texture_size)
|
|
self.texture_height = min(texture_height, max_texture_size)
|
|
self.atlases = []
|
|
|
|
def add(self, 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` : `~pyglet.image.AbstractImage`
|
|
The image to add.
|
|
`border` : int
|
|
Leaves specified pixels of blank space around
|
|
each image added to the Atlas.
|
|
|
|
:rtype: :py:class:`~pyglet.image.TextureRegion`
|
|
:return: The region of an atlas containing the newly added image.
|
|
"""
|
|
for atlas in list(self.atlases):
|
|
try:
|
|
return atlas.add(img, border)
|
|
except AllocatorException:
|
|
# Remove atlases that are no longer useful (so that their textures
|
|
# can later be freed if the images inside them get collected).
|
|
if img.width < 64 and img.height < 64:
|
|
self.atlases.remove(atlas)
|
|
|
|
atlas = TextureAtlas(self.texture_width, self.texture_height)
|
|
self.atlases.append(atlas)
|
|
return atlas.add(img, border)
|