Texture Atlas


class arcade.AtlasRegion(atlas: TextureAtlas, texture: Texture, x: int, y: int, width: int, height: int)[source]

Stores information about where a texture is located

  • atlas (str) – The atlas this region belongs to

  • texture (str) – The arcade texture

  • x (int) – The x position of the texture

  • y (int) – The y position of the texture

  • width (int) – The width of the texture in pixels

  • height (int) – The height of the texture in pixels


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.


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

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.

  • size (Tuple[int, int]) – The width and height of the atlas in pixels

  • border (int) – Currently no effect; Should always be 1 to avoid textures bleeding

  • textures (Sequence[arcade.Texture]) – The texture for this atlas

  • auto_resize (bool) – Automatically resize the atlas when full

  • ctx (Context) – The context for this atlas (will use window context if left empty)

add(texture: Texture) Tuple[int, arcade.texture_atlas.AtlasRegion][source]

Add a texture to the atlas.


texture (Texture) – The texture to add


texture_id, AtlasRegion tuple

allocate(texture: Texture) Tuple[int, int, int, arcade.texture_atlas.AtlasRegion][source]

Attempts to allocate space for a texture in the atlas. This doesn’t write the texture to the atlas texture itself. It only allocates space.


The x, y texture_id, TextureRegion

property auto_resize: bool

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

Return type


property border: int

The texture border in pixels

Return type


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

  • textures (Sequence[Texture]) – Sequence of textures

  • border


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

clear(texture_ids: bool = True, texture: bool = True) None[source]

Clear and reset the texture atlas. Note that also clearing “texture_ids” makes the atlas lose track of the old texture ids. This means the sprite list must be rebuild from scratch.

  • texture_ids (bool) – Clear the assigned texture ids

  • texture (bool) – Clear the contents of the atlas texture itself

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.

  • textures (Sequence[Texture]) – A sequence of textures (list, set, tuple, generator etc.)

  • border (int) – The border for the atlas in pixels (space between each texture)

property fbo: arcade.gl.framebuffer.Framebuffer

The framebuffer object for this atlas

get_region_info(name: str) arcade.texture_atlas.AtlasRegion[source]

Get the region info for a texture


The AtlasRegion for the given texture name

get_texture_id(name: str) int[source]

Get the uv slot for a texture name


The texture id for the given texture name

has_texture(texture: Texture) bool[source]

Check if a texture is already in the atlas

property height: int

The height of the texture atlas in pixels

Return type


property max_height: int

The maximum height of the atlas in pixels

Return type


property max_size: Tuple[int, int]

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

Return type


property max_width: int

The maximum width of the atlas in pixels

Return type


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 remove the image from the underlying texture. To physically remove the data you need to rebuild().


texture (Texture) – The texture to remove

render_into(texture: Texture, projection: Tuple[float, float, float, float] = 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
  • texture (Texture) – The texture area to render into

  • projection (Tuple[float,float,float,float]) – 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.


size (Tuple[int,int]) – The new size

save(path: str) None[source]

Save the texture atlas to a png.


path (str) – The path to save the atlas on disk

show() None[source]

Show the texture atlas using Pillow

property size: Tuple[int, int]

The width and height of the texture atlas in pixels

Return type


property texture: GLTexture

The atlas texture

Return type


to_image() PIL.Image.Image[source]

Convert the atlas to a Pillow image


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.


texture (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.


unit (int) – The texture unit to bind the uv texture

property uv_texture: GLTexture

Texture coordinate texture.

Return type


property width: int

The width of the texture atlas in pixels

Return type


write_image(image: PIL.Image.Image, x: int, y: int) None[source]

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

  • image (PIL.Image.Image) – The pillow image

  • x (int) – The x position to write the texture

  • y (int) – The y position to write the texture

write_texture(texture: Texture, x: int, y: int)[source]

Writes an arcade texture to a subsection of the texture atlas