Texture Management
- class arcade.texture.texture.ImageData(image: Image, hash: str | None = None, **kwargs)[source]
Bases:
A class holding the image for a texture with other metadata such as the hash. This information is used internally by the texture atlas to identify unique textures.
If a hash is not provided, it will be calculated. By default, the hash is calculated using the sha256 algorithm.
The ability to provide a hash directly is mainly there for ensuring we can load and save texture atlases to disk and for users to be able to allocate named regions in texture atlases.
- Parameters:
image – The image for this texture
hash – The hash of the image
- classmethod calculate_hash(image: Image) str [source]
Calculates the hash of an image.
The algorithm used is defined by the
hash_func
class variable.- Parameters:
image – The Pillow image to calculate the hash for
- hash
The hash of the image
- hash_func = 'sha256'
- image
The pillow image
- class arcade.Texture(image: Image | ImageData, *, hit_box_algorithm: HitBoxAlgorithm | None = None, hit_box_points: Sequence[tuple[float | int, float | int] | Vec2] | None = None, hash: str | None = None, **kwargs)[source]
Bases:
A Texture is wrapper for image data as a Pillow image, hit box data for this image used in collision detection and transformations like rotation and flipping if applied.
Textures are by definition immutable. If you want to change the image data, you should create a new texture with the desired changes. There are some exceptions to this rule if you know the inner workings of the library.
- Parameters:
image – The image or ImageData for this texture
hit_box_algorithm – The algorithm to use for calculating the hit box.
hit_box_points – A list of hitbox points for the texture to use (Optional). Completely overrides the hit box algorithm.
hash – Optional unique name for the texture. Can be used to make this texture globally unique. By default the hash of the pixel data is used.
- classmethod create_atlas_name(hash: str, vertex_order: tuple[int, int, int, int] = (0, 1, 2, 3))[source]
Create a name for the texture in a texture atlas.
- Parameters:
hash – The hash of the image data
vertex_order – The current vertex order of the texture
- classmethod create_cache_name(*, hash: str, hit_box_algorithm: HitBoxAlgorithm, vertex_order: tuple[int, int, int, int] = (0, 1, 2, 3)) str [source]
Create a cache name for the texture.
- Parameters:
hash – The hash of the image data
hit_box_algorithm – The hit box algorithm for this texture
vertex_order – The current vertex order of the texture
- classmethod create_empty(name: str, size: tuple[int, int], color: tuple[int, int, int, int] = (0, 0, 0, 0), hit_box_points: Sequence[tuple[float | int, float | int] | Vec2] | None = None) Texture [source]
Create a texture with all pixels set to the given color.
The hit box of the returned Texture will be set to a rectangle with the dimensions in
size
unless hit_box_points are provided.- Parameters:
name – The unique name for this texture. This is used for caching and uniqueness in texture atlases.
size – The xy size of the internal image
color (optional) – The color to fill the texture with
hit_box_points (optional) – A list of hitbox points for the texture
- classmethod create_image_cache_name(path: str | Path, crop: tuple[int, int, int, int] = (0, 0, 0, 0))[source]
Create a cache name for an image.
- Parameters:
path – The path to the image file
crop – The crop values used to create the texture
- crop(x: int, y: int, width: int, height: int) Texture [source]
Create a new texture from a sub-section of this texture.
If the crop is the same size as the original texture or the crop is 0 width or height, the original texture is returned.
- Parameters:
x – X position to start crop
y – Y position to start crop
width – Width of crop
height – Height of crop
- property crop_values: tuple[int, int, int, int] | None
The crop values used to create this texture, This is used to track the real origin of the pixel data.
- flip_diagonally() Texture [source]
Creates a new texture that is flipped diagonally from this texture. This is an alias for
transpose()
.This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- flip_horizontally() Texture [source]
Create a new texture that is flipped horizontally from this texture.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- flip_left_right() Texture [source]
Create a new texture that is flipped left to right from this texture.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- flip_top_bottom() Texture [source]
Create a new texture that is flipped top to bottom from this texture.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- flip_vertically() Texture [source]
Create a new texture that is flipped vertically from this texture.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- property height: int
The virtual width of the texture in pixels.
This can be different from the actual height of the image if set manually. It can be used to trick sprites into believing the texture us much larger than it is.
- property hit_box_algorithm: HitBoxAlgorithm
(read only) The algorithm used to calculate the hit box for this texture.
- property hit_box_points: Sequence[tuple[float | int, float | int] | Vec2]
Get the hit box points for this texture (read only).
Custom hit box points must be supplied during texture creation and should ideally not be changed after creation.
- property image: Image
Get or set the image of the texture.
Warning
This is an advanced function. Be absolutely sure you know the consequences of changing the image. It can cause problems with the texture atlas and hit box points.
- property image_cache_name: str | None
Get the image cache name for this texture. Returns
None
if not loaded from a file.
- property image_data: ImageData
The image data of the texture (read only).
This is a simple wrapper around the image containing metadata like hash and is used to determine the uniqueness of the image in texture atlases.
- property properties: dict[str, Any]
A dictionary of properties for this texture. This can be used to store any data you want.
- rotate_180() Texture [source]
Create a new texture that is rotated 180 degrees from this texture.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- rotate_270() Texture [source]
Create a new texture that is rotated 270 degrees from this texture.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- rotate_90(count: int = 1) Texture [source]
Create a new texture that is rotated 90 degrees from this texture.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Parameters:
count – Number of 90 degree steps to rotate.
- property size: tuple[int, int]
The virtual size of the texture in pixels.
This can be different from the actual size of the image if set manually. It can be used to trick sprites into believing the texture us much larger than it is.
- transform(transform: type[Transform]) Texture [source]
Create a new texture with the given transform applied.
- Parameters:
transform – Transform to apply
- transpose() Texture [source]
Creates a new texture that is transposed from this texture. This flips the texture diagonally from lower right to upper left.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- transverse() Texture [source]
Creates a new texture that is transverse from this texture. This flips the texture diagonally from lower left to upper right.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- arcade.load_texture(file_path: str | Path, *, hit_box_algorithm: HitBoxAlgorithm | None = None, hash: str | None = None) Texture [source]
Load a texture from disk (no caching).
When loading a texture a set of hit box points will be generated by default based on the pixel data. The default hit box algorithm is a simple 4 to 8 point hit box. This can be overridden by passing a different hit box or the global default can be set in the hitbox module.
Examples:
# We can load a texture using resource handles, string path or Path object texture = load_texture(":resources:image.png") texture = load_texture("image.png") texture = load_texture(Path("image.png")) # We can also specify a hit box algorithm to use for this texture texture = load_texture( ":resources:images/enemies/slimeBlock.png", hit_box_algorithm=arcade.hitbox.algo_detailed. )
- Parameters:
file_path – Path to the image file
hit_box_algorithm (optional) – The hit box algorithm to use for this texture. If not specified the global default will be used.
hash – (advanced) Optional custom hash/name for the loaded image. This is used for texture caching and global uniqueness in texture atlases.
- arcade.load_image(file_path: str | Path, *, mode: str = 'RGBA') Image [source]
Load a Pillow image from disk (no caching).
Normally you would use
load_texture
instead of this function. This function is useful when you want to load an image and then manipulate it before creating a texture.Note that Arcade mainly works with RGBA images. If you override the mode you might need to convert the final image to RGBA.
- Parameters:
file_path – Path to the image file
mode – The desired mode for the image (default: “RGBA”)
- arcade.load_spritesheet(file_name: str | Path) SpriteSheet [source]
Loads an image from disk returning a sprite sheet that can further be used to slice out smaller images.
- Parameters:
file_name – Path to the image file
- arcade.make_circle_texture(diameter: int, color: tuple[int, int, int, int], name: str | None = None, hit_box_algorithm: HitBoxAlgorithm | None = None) Texture [source]
Creates a
Texture
of a circle with the given diameter and color.- Parameters:
diameter – Diameter of the circle and dimensions of the square
Texture
returned.color – Color of the circle as a
Color
instance a 3 or 4 tuple.name (optional) – A unique name for the texture. If not provided, a name will be generated. This is used for caching and unique identifier for texture atlases.
hit_box_algorithm (optional) – The hit box algorithm to use for this texture. If not provided, the default hit box algorithm will be used.
- arcade.make_soft_circle_texture(diameter: int, color: tuple[int, int, int, int], center_alpha: int = 255, outer_alpha: int = 0, name: str | None = None, hit_box_algorithm: HitBoxAlgorithm | None = None) Texture [source]
Creates a
Texture
of a circle with the given diameter and color, fading out at its edges.- Parameters:
diameter – Diameter of the circle and dimensions of the square
Texture
returned.color – Color of the circle as a 4-length tuple or
Color
instance.center_alpha – Alpha value of the circle at its center.
outer_alpha – Alpha value of the circle at its edges.
name (optional) – A unique name for the texture. If not provided, a name will be generated. This is used for caching and unique identifier for texture atlases.
hit_box_algorithm (optional) – The hit box algorithm to use for this texture. If not provided, the default hit box algorithm will be used.
- arcade.make_soft_square_texture(size: int, color: tuple[int, int, int, int], center_alpha: int = 255, outer_alpha: int = 0, name: str | None = None) Texture [source]
Creates a
Texture
of a square with the given diameter and color, fading out at its edges.- Parameters:
size – Diameter of the square and dimensions of the square Texture returned.
color – Color of the square.
center_alpha – Alpha value of the square at its center.
outer_alpha – Alpha value of the square at its edges.
name (optional) – A unique name for the texture. If not provided, a name will be generated. This is used for caching and unique identifier for texture atlases.
- class arcade.TextureCacheManager(hit_box_cache: HitBoxCache | None = None, image_data_cache: ImageDataCache | None = None, texture_cache: TextureCache | None = None)[source]
Bases:
A simple manager wrapping texture, image data and hit box caches with convenient methods for loading textures and sprite sheets.
- Parameters:
hit_box_cache – Optional hit box cache to use. If not specified, a new cache will be created.
image_data_cache – Optional image data cache to use. If not specified, a new cache will be created.
texture_cache – Optional texture cache to use. If not specified, a new cache will be created
- flush(sprite_sheets: bool = True, textures: bool = True, image_data: bool = True, hit_boxes: bool = False)[source]
Remove contents from the texture manager.
- Parameters:
sprite_sheets – If
True
, sprite sheets will be flushed.textures – If
True
, textures will be flushed.image_data – If
True
, image data will be flushed.hit_boxes – If
True
, hit boxes will be flushed.
- property hit_box_cache: HitBoxCache
Get or set the current hit box cache.
- property image_data_cache: ImageDataCache
Cache for image data.
- load_or_get_image(path: str | Path, hash: str | None = None, mode='RGBA') ImageData [source]
Loads a complete image from disk or return a cached version.
- Parameters:
path – Path of the file to load.
hash – Optional override for image hash
mode – The mode to use for the image. Default is “RGBA”.
- load_or_get_spritesheet(path: str | Path) SpriteSheet [source]
Load a sprite sheet from disk, or return a cached version.
Note that any texture sliced from the sprite sheet will be cached. if this is not the desirable behavior, use
load_or_get_spritesheet_texture()
.- Parameters:
path – Path to the sprite sheet image
- load_or_get_spritesheet_texture(path: str | Path, rect: Rect, hit_box_algorithm: HitBoxAlgorithm | None = None) Texture [source]
Slice out a texture slice from a sprite sheet.
If the spritesheet is not already loaded, it will be loaded and cached.
If the sliced texture is already cached, it will be returned instead.
- Parameters:
path – Path to the sprite sheet image
rect – Slice of the texture in the sprite sheet.
hit_box_algorithm (optional) – Hit box algorithm to use. If not specified, the global default will be used.
- load_or_get_texture(file_path: str | Path, *, x: int = 0, y: int = 0, width: int = 0, height: int = 0, hit_box_algorithm: HitBoxAlgorithm | None = None) Texture [source]
Load an image from disk and create a texture. If the image is already loaded, return the cached version.
The
x
,y
,width
, andheight
parameters are used to specify a sub-rectangle of the image to load. If not specified, the entire image is loaded.- Parameters:
file_path – Path to the image file.
x (optional) – X coordinate of the texture in the image.
y (optional) – Y coordinate of the texture in the image.
width (optional) – Width of the texture in the image.
height (optional) – Height of the texture in the image.
hit_box_algorithm (optional) – The hit box algorithm to use for this texture. If not specified, the global default will be used.
- property texture_cache: TextureCache
Cache for textures.
- class arcade.SpriteSheet(path: str | Path | None = None, image: Image | None = None)[source]
Bases:
A sprite sheet is a single image containing multiple smaller images, or frames. The class is used to load the image providing methods to slice out parts of the image as separate images or textures.
Note that the default coordinate system used for slicing is using image coordinates (0, 0) in the upper left corner. This matches the coordinate system used by PIL.
- Parameters:
path (optional)
image (optional) – PIL image to use.
- property flip_flags: tuple[bool, bool]
Query the orientation of the sprite sheet. This can be used to determine if the sprite sheet needs to be flipped.
Default values are
(False, False)
. Will be modified whenflip_left_right()
orflip_top_bottom()
is called.Tuple of booleans
(flip_left_right, flip_top_bottom)
.
- classmethod from_image(image: Image) SpriteSheet [source]
Create a sprite sheet from a PIL image.
- Parameters:
image – PIL image to use.
- get_image(rect: Rect, y_up=False) Image [source]
Slice out an image from the sprite sheet.
- Parameters:
rect – The rectangle to crop out.
y_up – Sets the coordinate space of the image to assert (0, 0) in the bottom left.
- get_image_grid(size: tuple[int, int], columns: int, count: int, margin: tuple[int, int, int, int] = (0, 0, 0, 0)) list[Image] [source]
Slice a grid of textures from the sprite sheet.
- Parameters:
size – Size of each texture
(width, height)
columns – Number of columns in the grid
count – Number of textures to crop
margin – The margin around each texture
(left, right, bottom, top)
- get_texture(rect: Rect, hit_box_algorithm: HitBoxAlgorithm | None = None, y_up=False) Texture [source]
Slice out texture from the sprite sheet.
- Parameters:
rect – The rectangle to crop out.
hit_box_algorithm – Hit box algorithm to use for the texture. If not provided, the default hit box algorithm will be used.
y_up – Sets the coordinate space of the image to assert (0, 0) in the bottom left.
- get_texture_grid(size: tuple[int, int], columns: int, count: int, margin: tuple[int, int, int, int] = (0, 0, 0, 0), hit_box_algorithm: HitBoxAlgorithm | None = None) list[Texture] [source]
Slice a grid of textures from the sprite sheet.
- Parameters:
size – Size of each texture
(width, height)
columns – Number of columns in the grid
count – Number of textures to crop
margin – The margin around each texture
(left, right, bottom, top)
hit_box_algorithm – Hit box algorithm to use for the textures. If not provided, the default hit box algorithm will be used.