Texture Management#
arcade.ImageData#
- class arcade.ImageData(image: Image, hash: Optional[str] = None)[source]#
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. It’s important that all hashes are of the same type. 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.
- Parameters:
image (PIL.Image.Image) – The image for this texture
hash (str) – The hash of the image
arcade.SolidColorTexture#
- class arcade.SolidColorTexture(name, width, height, image)[source]#
Used internally in Arcade to make colored textures. This is not indented to be used by the end user.
This texture variant is mainly here it override the width and height property to fake texture size for sprites. The internal texture is always a fixed sized white texture that is colored by the sprite’s color property.
arcade.Texture#
- class arcade.Texture(name: str, image: Union[Image, ImageData], hit_box_algorithm: Optional[str] = 'default', hit_box_detail: float = 4.5, hit_box_points: Optional[Sequence[Tuple[float, float]]] = None)[source]#
An arcade.Texture is simply a wrapper for image data as a Pillow image and the hit box data for this image used in collision detection. Usually created by the
load_texture
orload_textures
commands.- Parameters:
name (str) – Globally unique name for this texture. This is used internally for caching and texture atlas.
image (PIL.Image.Image) – The image for this texture
hit_box_algorithm (str) –
One of None, ‘None’, ‘Simple’ or ‘Detailed’. Defaults to ‘Simple’. Use ‘Simple’ for the
PhysicsEngineSimple
,PhysicsEnginePlatformer
and ‘Detailed’ for thePymunkPhysicsEngine
.hit_box_algorithm = “None”#
hit_box_algorithm = “Simple”#
hit_box_algorithm = “Detailed”#
hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box
hit_box_points (PointList) – List of points for the hit box (Optional). Completely overrides the hit box algorithm.
- classmethod create_empty(name: str, size: Tuple[int, int], color: Union[Tuple[int, int, int], Tuple[int, int, int, int]] = (0, 0, 0, 0)) Texture [source]#
Create a texture with all pixels set to transparent black.
The hit box of the returned Texture will be set to a rectangle with the dimensions in
size
because there is no non-blank pixel data to calculate a hit box.- Parameters:
This function has multiple uses, including:
Allocating space in texture atlases
Generating custom cached textures from component images
The internal image can be altered with Pillow draw commands and then written/updated to a texture atlas. This works best for infrequent changes such as generating custom cached sprites. For frequent texture changes, you should instead render directly into the texture atlas.
Warning
If you plan to alter images using Pillow, read its documentation thoroughly! Some of the functions can have unexpected behavior.
For example, if you want to draw one or more images that contain transparency onto a base image that also contains transparency, you will likely need to use PIL.Image.alpha_composite as part of your solution. Otherwise, blending may behave in unexpected ways.
This is especially important for customizable characters.
Be careful of your RAM usage when using this function. The Texture this method returns will have a new internal RGBA Pillow image which uses 4 bytes for every pixel in it. This will quickly add up if you create many large Textures.
If you want to create more than one blank texture with the same dimensions, you can save CPU time and RAM by calling this function once, then passing the
image
attribute of the resulting Texture object to the class constructor for each additional blank Texture instance you would like to create. This can be especially helpful if you are creating multiple large Textures.
- classmethod create_filled(name: str, size: Tuple[int, int], color: Union[Tuple[int, int, int], Tuple[int, int, int, int]]) Texture [source]#
Create a filled texture. This is an alias for
create_empty()
.
- crop(x: int, y: int, width: int, height: int) Texture [source]#
Create a new texture from a crop of this texture.
- draw_scaled(center_x: float, center_y: float, scale: float = 1.0, angle: float = 0.0, alpha: int = 255)[source]#
Draw the texture.
Warning
This is a very slow method of drawing a texture, and should be used sparingly. The method simply creates a sprite internally and draws it.
- draw_sized(center_x: float, center_y: float, width: float, height: float, angle: float = 0.0, alpha: int = 255)[source]#
Draw a texture with a specific width and height.
Warning
This is a very slow method of drawing a texture, and should be used sparingly. The method simply creates a sprite internally and draws it.
- flip_diagonally() Texture [source]#
Returns 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).
- Returns:
Texture
- flip_left_to_right() Texture [source]#
Flip the texture left to right / horizontally.
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).
- Returns:
Texture
- flip_top_to_bottom() Texture [source]#
Flip the texture top to bottom / vertically.
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).
- Returns:
Texture
- property hit_box_algorithm: Optional[str]#
(read only) The algorithm used to calculate the hit box for this texture.
- property hit_box_points: Sequence[Tuple[float, float]]#
Get the hit box points for this texture.
Custom hit box points must be supplied during texture creation and should ideally not be changed after creation.
- Returns:
PointList
- 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.
- Parameters:
image (PIL.Image.Image) – The image to set
- 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.
- Returns:
ImageData
- rotate(count: int) Texture [source]#
Rotate the texture by a given number of 90 degree steps.
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 (int) – Number of 90 degree steps to rotate.
- Returns:
Texture
- transpose() Texture [source]#
Returns 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).
- Returns:
Texture
- transverse() Texture [source]#
Returns 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).
- Returns:
Texture
arcade.cleanup_texture_cache#
arcade.load_spritesheet#
- arcade.load_spritesheet(file_name: Union[str, Path], sprite_width: int, sprite_height: int, columns: int, count: int, margin: int = 0, hit_box_algorithm: Optional[str] = 'Simple', hit_box_detail: float = 4.5) List[Texture] [source]#
- Parameters:
file_name (str) – Name of the file to that holds the texture.
sprite_width (int) – Width of the sprites in pixels
sprite_height (int) – Height of the sprites in pixels
columns (int) – Number of tiles wide the image is.
count (int) – Number of tiles in the image.
margin (int) – Margin between images
hit_box_algorithm (str) – One of None, ‘None’, ‘Simple’ (default) or ‘Detailed’.
hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box
- Returns List:
List of
Texture
objects.
arcade.load_texture#
- arcade.load_texture(file_name: Union[str, Path], x: int = 0, y: int = 0, width: int = 0, height: int = 0, flipped_horizontally: bool = False, flipped_vertically: bool = False, flipped_diagonally: bool = False, hit_box_algorithm: Optional[str] = 'Simple', hit_box_detail: float = 4.5) Texture [source]#
Load an image from disk and create a texture.
Note: If the code is to load only part of the image, the given x, y coordinates will start with the origin (0, 0) in the upper left of the image. When drawing, Arcade uses (0, 0) in the lower left corner. Be careful with this reversal.
For a longer explanation of why computers sometimes start in the upper left, see: http://programarcadegames.com/index.php?chapter=introduction_to_graphics&lang=en#section_5
- Parameters:
file_name (str) – Name of the file to that holds the texture.
x (float) – X position of the crop area of the texture.
y (float) – Y position of the crop area of the texture.
width (float) – Width of the crop area of the texture.
height (float) – Height of the crop area of the texture.
flipped_horizontally (bool) – Mirror the sprite image. Flip left/right across vertical axis.
flipped_vertically (bool) – Flip the image up/down across the horizontal axis.
flipped_diagonally (bool) – Transpose the image, flip it across the diagonal.
mirrored (bool) – Deprecated.
hit_box_algorithm (str) –
One of None, ‘None’, ‘Simple’ or ‘Detailed’. Defaults to ‘Simple’. Use ‘Simple’ for the
PhysicsEngineSimple
,PhysicsEnginePlatformer
and ‘Detailed’ for thePymunkPhysicsEngine
.hit_box_algorithm = “None”#
hit_box_algorithm = “Simple”#
hit_box_algorithm = “Detailed”#
hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box
- Returns:
New
Texture
object.- Raises:
ValueError
arcade.load_texture_pair#
arcade.load_textures#
- arcade.load_textures(file_name: Union[str, Path], image_location_list: Union[Tuple[Union[Tuple[float, float, float, float], List[float]], ...], List[Union[Tuple[float, float, float, float], List[float]]]], mirrored: bool = False, flipped: bool = False, hit_box_algorithm: Optional[str] = 'Simple', hit_box_detail: float = 4.5) List[Texture] [source]#
Load a set of textures from a single image file.
Note: If the code is to load only part of the image, the given x, y coordinates will start with the origin (0, 0) in the upper left of the image. When drawing, Arcade uses (0, 0) in the lower left corner. Be careful with this reversal.
For a longer explanation of why computers sometimes start in the upper left, see: http://programarcadegames.com/index.php?chapter=introduction_to_graphics&lang=en#section_5
- Parameters:
file_name (str) – Name of the file.
image_location_list (List) – List of image sub-locations. Each rectangle should be a List of four floats: [x, y, width, height].
mirrored (bool) – If set to True, the image is mirrored left to right.
flipped (bool) – If set to True, the image is flipped upside down.
hit_box_algorithm (str) – One of None, ‘None’, ‘Simple’ (default) or ‘Detailed’.
hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box
- Returns:
List of
Texture
’s.- Raises:
ValueError
arcade.make_circle_texture#
arcade.make_soft_circle_texture#
- arcade.make_soft_circle_texture(diameter: int, color: Union[Tuple[int, int, int], Tuple[int, int, int, int]], center_alpha: int = 255, outer_alpha: int = 0, name: Optional[str] = None) Texture [source]#
Return a
Texture
of a circle with the given diameter and color, fading out at its edges.- Parameters:
diameter (int) – Diameter of the circle and dimensions of the square
Texture
returned.color (Color) – Color of the circle.
center_alpha (int) – Alpha value of the circle at its center.
outer_alpha (int) – Alpha value of the circle at its edges.
name (str) – Custom or pre-chosen name for this texture
- Returns:
New
Texture
object.- Return type:
arcade.make_soft_square_texture#
- arcade.make_soft_square_texture(size: int, color: Union[Tuple[int, int, int], Tuple[int, int, int, int]], center_alpha: int = 255, outer_alpha: int = 0, name: Optional[str] = None) Texture [source]#
Return a
Texture
of a square with the given diameter and color, fading out at its edges.- Parameters:
- Returns:
New
Texture
object.