Texture Atlas#

class arcade.texture_atlas.AtlasRegion(atlas: TextureAtlas, x: int, y: int, width: int, height: int, texture_coordinates: Tuple[float, float, float, float, float, float, float, float] | None = None)[source]#

Bases:

Stores information about where a texture is located.

The texture coordinates are stored as a tuple of 8 floats (4 points, 2 floats each) in the following order: upper_left, upper_right, lower_left, lower_right.

Layout:

(0, 1)                                 (1, 1)
+--------------------------------------+
|          Atlas Texture               |
|                                      |
| (2)               (3)                |
+-----------------+                    |
|   Image         |                    |
|                 |                    |
|                 |                    |
|                 |                    |
|                 |                    |
| (0)             | (1)                |
+-----------------+--------------------+
(0, 0)                                 (1, 0)

Parameters:

atlas – The atlas this region belongs to
texture – The arcade texture
x – The x position of the texture
y – The y position of the texture
width – The width of the texture in pixels
height – The height of the texture in pixels
texture_coordinates – The texture coordinates (optional)

verify_image_size(image_data: ImageData)[source]#: Verify the image has the right size. The internal image of a texture can be tampered with at any point causing an atlas update to fail.

height#

texture_coordinates#

width#

x#

y#

class arcade.texture_atlas.TextureAtlas(size: Tuple[int, int], *, border: int = 1, textures: Sequence[Texture] | None = None, auto_resize: bool = True, ctx: ArcadeContext | None = None, capacity: int = 2)[source]#

Bases: TextureAtlasBase

A texture atlas with a size in a context.

A texture atlas is a large texture containing several textures so OpenGL can easily batch draw thousands or hundreds of thousands of sprites on one draw operation.

This is a fairly simple atlas that stores horizontal strips were the height of the strip is the texture/image with the larges height.

Adding a texture to this atlas generates a texture id. This id is used the sprite list vertex data to reference what texture each sprite is using. The actual texture coordinates are located in a float32 texture this atlas is responsible for keeping up to date.

The atlas deals with image and textures. The image is the actual image data. The texture is the arcade texture object that contains the image and other information about such as transforms. Several textures can share the same image with different transforms applied. The transforms are simply changing the order of the texture coordinates to flip, rotate or mirror the image.

Parameters:

size (Tuple[int, int]) – The width and height of the atlas in pixels
border – Currently no effect; Should always be 1 to avoid textures bleeding
textures – The texture for this atlas
auto_resize – Automatically resize the atlas when full
ctx – The context for this atlas (will use window context if left empty)
capacity – The number of textures the atlas keeps track of. This is multiplied by 4096. Meaning capacity=2 is 8192 textures. This value can affect the performance of the atlas.

add(texture: Texture) → Tuple[int, AtlasRegion][source]#

Add a texture to the atlas.

Parameters:: texture – The texture to add
Returns:: texture_id, AtlasRegion tuple
Raises:: AllocatorException – If there are no room for the texture

classmethod calculate_minimum_size(textures: Sequence[Texture], border: int = 1)[source]#

Calculate the minimum atlas size needed to store the the provided sequence of textures

Parameters:

textures – Sequence of textures
border – The border around each texture in pixels

Returns:

An estimated minimum size as a (width, height) tuple

classmethod create_from_texture_sequence(textures: Sequence[Texture], border: int = 1) → TextureAtlas[source]#

Create a texture atlas of a reasonable size from a sequence of textures.

Parameters:

textures – A sequence of textures (list, set, tuple, generator etc.)
border – The border for the atlas in pixels (space between each texture)

get_image_region_info(hash: str) → AtlasRegion[source]#

Get the region info for and image by has

Parameters:: hash – The hash of the image
Returns:: The AtlasRegion for the given texture name

get_texture_id(texture: Texture) → int[source]#

Get the internal id for a Texture in the atlas

Parameters:: atlas_name – The name of the texture in the atlas
Returns:: The texture id for the given texture name
Raises:: Exception – If the texture is not in the atlas

get_texture_region_info(atlas_name: str) → AtlasRegion[source]#

Get the region info for a texture by atlas name

Returns:: The AtlasRegion for the given texture name

has_image(image_data: ImageData) → bool[source]#: Check if a image is already in the atlas

has_texture(texture: Texture) → bool[source]#: Check if a texture is already in the atlas

has_unique_texture(texture: Texture) → bool[source]#: Check if the atlas already have a texture with the same image data and vertex order

read_texture_image_from_atlas(texture: Texture) → Image[source]#

Read the pixel data for a texture directly from the atlas texture on the GPU. The contents of this image can be altered by rendering into the atlas and is useful in situations were you need the updated pixel data on the python side.

Parameters:: texture – The texture to get the image for
Returns:: A pillow image containing the pixel data in the atlas

rebuild() → None[source]#

Rebuild the underlying atlas texture.

This method also tries to organize the textures more efficiently ordering them by size. The texture ids will persist so the sprite list don’t need to be rebuilt.

remove(texture: Texture) → None[source]#

Remove a texture from the atlas.

This doesn’t erase the pixel data from the atlas texture itself, but leaves the area unclaimed. The area will be reclaimed when the atlas is rebuilt.

Parameters:: texture – The texture to remove

render_into(texture: Texture, projection: Tuple[float, float, float, float] | None = None)[source]#

Render directly into a sub-section of the atlas. The sub-section is defined by the already allocated space of the texture supplied in this method.

By default the projection will be set to match the texture area size were 0, 0 is the lower left corner and width, height (of texture) is the upper right corner.

This method should should be used with the with statement:

with atlas.render_into(texture):
    # Draw commands here

# Specify projection
with atlas.render_into(texture, projection=(0, 100, 0, 100))
    # Draw geometry

Parameters:

texture – The texture area to render into
projection – The ortho projection to render with. This parameter can be left blank if no projection changes are needed. The tuple values are: (left, right, button, top)

resize(size: Tuple[int, int]) → None[source]#

Resize the atlas on the gpu.

This will copy the pixel data from the old to the new atlas retaining the exact same data. This is useful if the atlas was rendered into directly and we don’t have to transfer each texture individually from system memory to graphics memory.

Parameters:: size – The new size

save(path: str | Path, flip: bool = False, components: int = 4, draw_borders: bool = False, border_color: Tuple[int, int, int] = (255, 0, 0)) → None[source]#

Save the texture atlas to a png.

Borders can also be drawn into the image to visualize the regions of the atlas.

Parameters:

path – The path to save the atlas on disk
flip – Flip the image horizontally
components – Number of components. (3 = RGB, 4 = RGBA)
color – RGB color of the borders

Returns:

A pillow image containing the atlas texture

show(flip: bool = False, components: int = 4, draw_borders: bool = False, border_color: Tuple[int, int, int] = (255, 0, 0)) → None[source]#

Show the texture atlas using Pillow.

Borders can also be drawn into the image to visualize the regions of the atlas.

Parameters:

flip – Flip the image horizontally
components – Number of components. (3 = RGB, 4 = RGBA)
draw_borders – Draw region borders into image
color – RGB color of the borders

to_image(flip: bool = False, components: int = 4, draw_borders: bool = False, border_color: Tuple[int, int, int] = (255, 0, 0)) → Image[source]#

Convert the atlas to a Pillow image.

Borders can also be drawn into the image to visualize the regions of the atlas.

Parameters:

flip – Flip the image horizontally
components – Number of components. (3 = RGB, 4 = RGBA)
draw_borders – Draw region borders into image
color – RGB color of the borders

Returns:

A pillow image containing the atlas texture

update_texture_image(texture: Texture)[source]#

Updates the internal image of a texture in the atlas texture. The new image needs to be the exact same size as the original one meaning the texture already need to exist in the atlas.

This can be used in cases were the image is manipulated in some way and we need a quick way to sync these changes to graphics memory. This operation is fairly expensive, but still orders of magnitude faster than removing the old texture, adding the new one and re-building the entire atlas.

Parameters:: texture – The texture to update

update_texture_image_from_atlas(texture: Texture) → None[source]#

Update the arcade Texture’s internal image with the pixel data content from the atlas texture on the GPU. This can be useful if you render into the atlas and need to update the texture with the new pixel data.

Parameters:: texture – The texture to update

use_uv_texture(unit: int = 0) → None[source]#

Bind the texture coordinate texture to a channel. In addition this method writes the texture coordinate to the texture if the data is stale. This is to avoid a full update every time a texture is added to the atlas.

Parameters:: unit – The texture unit to bind the uv texture

write_image(image: Image, x: int, y: int) → None[source]#

Write a PIL image to the atlas in a specific region.

Parameters:

image – The pillow image
x – The x position to write the texture
y – The y position to write the texture

auto_resize#: Get or set the auto resize flag for the atlas. If enabled the atlas will resize itself when full.

border#: The texture border in pixels

fbo#: The framebuffer object for this atlas

height#: The height of the texture atlas in pixels

image_uv_texture#: Texture coordinate texture for images.

images#

Return a list of all the images in the atlas.

A new list is constructed from the internal weak set of images.

max_height#: The maximum height of the atlas in pixels

max_size#: The maximum size of the atlas in pixels (x, y)

max_width#: The maximum width of the atlas in pixels

size#: The width and height of the texture atlas in pixels

texture#: The atlas texture.

texture_uv_texture#: Texture coordinate texture for textures.

textures#: All textures instance added to the atlas regardless of their internal state. See unique_textures`() for textures with unique image data and transformation.

unique_textures#

All unique textures in the atlas.

These are textures using an image with the same hash and the same vertex order. The full list of all textures can be found in textures().

width#: The width of the texture atlas in pixels

class arcade.texture_atlas.TextureAtlasBase(ctx: 'ArcadeContext' | None)[source]#

Bases: ABC

Generic base for texture atlases.

abstract remove(texture: Texture) → None[source]#: Remove a texture from the atlas.

ctx#