sdl2.ext.sprite - Sprite, texture and pixel surface routines.

Sprite, texture and pixel surface routines.

sdl2.ext.sprite.TEXTURE

int – Indicates that texture-based rendering or sprite creation is wanted.

sdl2.ext.sprite.SOFTWARE

int – Indicates that software-based rendering or sprite creation is wanted.

class sdl2.ext.sprite.Sprite(data, w, h, free)

Bases: sdl2.ext.rect.NonIterableRect

A simple 2D object, implemented as abstract base class.

__init__(data, w, h, free)

Create a new sprite.

depth

int – The layer depth on which to draw the sprite. Objects with higher depth values will be drawn on top of other sprites by the SpriteRenderSystem.

area

The rectangular area occupied by the sprite.

frame_rect

attr – frame_rect.

position

The top-left position of the Sprite as tuple.

class sdl2.ext.sprite.SoftwareSprite(imgsurface, free=True, area=None)

Bases: sdl2.ext.sprite.Sprite

A simple, visible, pixel-based 2D object using software surfaces.

__init__(imgsurface, free=True, area=None)

Create a new SoftwareSprite.

Parameters:

• imgsurface (sdl2.SDL_Surface) – the surface containing pixel data for this sprite.
• free (bool) – when set to True the surface is released when the sprite is deleted/garbage collected.

subsprite(area)

Create another SoftwareSprite from part of the sprite’s surface.

The two sprites share pixel data, so if the parent sprite’s surface is not managed by the sprite (free is False), you will need to keep it alive while the subsprite exists.

Parameters:area (tuple) – x, y, w, h (position and size) of the area, in pixels. Returns:SoftwareSprite

surface

sdl2.SDL_Surface containing pixel data.

class sdl2.ext.sprite.TextureSprite(texture, free=True, area=None, **kwargs)

Bases: sdl2.ext.sprite.Sprite

A simple, visible, texture-based 2D object, using a renderer.

__init__(texture, free=True, area=None, **kwargs)

Create a new TextureSprite.

Parameters:

• texture (sdl2.SDL_Texture) – the texture containing the sprite pixel data.
• free (bool) – when set to True the texture is released when the sprite is deleted/garbage collected.
• kwargs (dict) – additional kwargs are unpacked to the instance __dict__ before processing the other arguments.

angle

int – The rotation angle for the TextureSprite.

flip (sdl2.SDL_FLIP_NONE, sdl2.SDL_FLIP_HORIZONTAL,

sdl2.SDL_FLIP_VERTICAL): Allows the TextureSprite to be flipped over its horizontal or vertical axis via the appropriate SDL_FLIP_* value.

texture

sdl2.SDL_Texture – the texture containing the sprite pixel data.

color_mod

tuple – 3 rgb color int values between 0 and 255, the default color_mod for this sprite.

alpha_mod

int – integer between 0 and 255, the default alpha_mod for this sprite.

alpha_mod = None

color_mod = None

get_alpha_mod()

Get the alpha value multiplier for render copy operations.

This is the value currently set for the texture. If a texture is used by more then one sprite, the modifier as defined on its last copy operation will be returned.

Returns:integer alpha value. Return type:(int)

get_color_mod()

Get the color value multiplier for render copy operations.

This is the value currently set for the texture. If a texture is used by more then one sprite, the modifier as defined on its last copy operation will be returned.

Returns:3-tuple of rgb integer values (RGB). Return type:(int), (int), (int)

sdl_center

The center of the TextureSprite as tuple.

set_alpha_mod(alpha=None)

Set a alpha value multiplier for render copy operations.

When this texture is rendered, during the copy operation the source alpha value is modulated by this alpha value according to the following formula:

srcA = srcA * (alpha / 255)

Parameters:alpha (int) – integer between 0 and 255

set_animation(cols, rows, col_w, row_h, col=0, row=0)

“Set animation frames parameters.

Parameters:

• cols (int) – number of frame columns
• rows (int) – number of frame rows
• col_w (int) – width of each column, in pixels
• row_h (int) – height of each row, in pixels
• col (int) – the column of the desired starting frame
• row (int) – the row of the desired starting frame

Returns:

TextureSprite

self instance, making it possible to use this method on the object creation (see Usage below) as a one liner.

Example

Here a 10x1 area of 32x32 tiles is used:

>>> sprite = TextureSprite(**kwargs).set_animation(
        10, 1, 32, 32)

set_color_mod(color=None)

Set a color value multiplier for render copy operations.

When this texture is rendered, during the copy operation each source color channel is modulated by the appropriate color value according to the following formula:

srcC = srcC * (color / 255)

Parameters:color (3-tuple of ints) – rgb color with values between 0 and 255

set_current_rect()

Apply the current animation parameters to the frame_rect.

step(col=0, row=0)

...

subsprite(area, **kwargs)

Create another sprite from part of this sprite’s pixel data.

The two sprites share pixel data, so if the parent sprite’s surface is not managed by the sprite (free is False), you will need to keep it alive while the subsprite exists.

Parameters:

• area (tuple) – x, y, w, h (position and size) of the area, in pixels.
• kwargs (dict) – additional kwargs are passed forward to the TextureSprite initialization.

Returns:

TextureSprite

texture

sdl2.SDL_Texture containing pixel data.

class sdl2.ext.sprite.SpriteFactory(sprite_type=0, **kwargs)

Bases: object

A factory class for creating Sprite components.

__init__(sprite_type=0, **kwargs)

Creates a new SpriteFactory.

The SpriteFactory can create TextureSprite or SoftwareSprite instances, depending on the sprite_type being passed to it, which can be SOFTWARE or TEXTURE. The additional kwargs are used as default arguments for creating sprites within the factory methods.

create_software_sprite(size, bpp=32, masks=None)

Creates a software sprite.

A size tuple containing the width and height of the sprite and a bpp value, indicating the bits per pixel to be used, need to be provided.

create_sprite(**kwargs)

Creates an empty Sprite.

This will invoke create_software_sprite() or create_texture_sprite() with the passed arguments and the set default arguments.

create_sprite_render_system(*args, **kwargs)

Create a new SpriteRenderSystem.

For TEXTURE mode, the passed args are ignored. The renderer can be passed as kwarg and defaults to the SDL_Renderer passed to the SpriteFactory during its creation.

create_texture_sprite(renderer, size, pformat=373694468, access=0)

Creates a texture sprite.

A size tuple containing the width and height of the sprite needs to be provided.

TextureSprite objects are assumed to be static by default, making it impossible to access their pixel buffer in favour for faster copy operations. If you need to update the pixel data frequently or want to use the texture as target for rendering operations, access can be set to the relevant SDL_TEXTUREACCESS_* flag.

from_color(color, size=None, bpp=32, masks=None, pos=None, rect=None)

Create a sprite with a certain color.

Either size or rect is required. A sdl.SDL_Surface is first created and then a sprite is created passing it as parameter, using :func: from_surface.

Parameters:

• ( (color) – class: sdl2.ext.color.Color, tuple): color of the sprite to be created. Can be a Color or a tuple of 3-4 int (RGB or RGBA).
• size (tuple) – size (int width, int height) of the sprite to be created, in pixels.
• bpp (int) – the depth of the sprite’s surface, in bits

Raises:

• ValueError if neither size or rect arguments are passed
• SDLError if an error occurs during the creation of the surface

from_image(fname)

Create a Sprite from the passed image file.

from_object(obj)

Create a Sprite from an arbitrary object.

from_surface(tsurface, free=False)

Create a Sprite from the passed SDL_Surface.

If free is set to True, the passed surface will be freed automatically.

from_text(text, **kwargs)

Creates a Sprite from a string of text.

get_char_sprite(char, **kwargs)

Get the passed character from the current tileset, as a sprite.

Parameters:

• char (str) – string of one character to be rendered
• kwargs (dict) – additional kwargs are passed forward to the subsprite functione of the tileset sprite.

load_tileset(sprite, tile_size)

...

sprite_type

The sprite type created by the factory.

class sdl2.ext.sprite.SoftwareSpriteRenderSystem(window)

Bases: sdl2.ext.sprite.SpriteRenderSystem

A rendering system for SoftwareSprite components.

The SoftwareSpriteRenderSystem class uses a Window as drawing device to display Sprite surfaces. It uses the Window’s internal SDL surface as drawing context, so that GL operations, such as texture handling or using SDL renderers is not possible.

__init__(window)

Creates a new SoftwareSpriteRenderSystem for a specific Window.

render(sprites, x=None, y=None)

Draws the passed sprites (or sprite) on the Window’s surface.

x and y are optional arguments that can be used as relative drawing location for sprites. If set to None, the location information of the sprites are used. If set and sprites is an iterable, such as a list of SoftwareSprite objects, x and y are relative location values that will be added to each individual sprite’s position. If sprites is a single SoftwareSprite, x and y denote the absolute position of the SoftwareSprite, if set.

class sdl2.ext.sprite.SpriteRenderSystem

Bases: sdl2.ext.ebs.System

A rendering system for Sprite components.

This is a base class for rendering systems capable of drawing and displaying Sprite-based objects. Inheriting classes need to implement the rendering capability by overriding the render() method.

__init__()

process(world, components)

Draws the passed SoftSprite objects on the Window’s surface.

render(sprites, x=None, y=None)

Renders the passed sprites.

This is a no-op function and needs to be implemented by inheriting classes.

sortfunc

Sort function for the component processing order.

The default sort order is based on the depth attribute of every sprite. Lower depth values will cause sprites to be drawn below sprites with higher depth values.

class sdl2.ext.sprite.TextureSpriteRenderSystem(target, present=True, *args, **kwargs)

Bases: sdl2.ext.sprite.SpriteRenderSystem

A rendering system for TextureSprite components.

The TextureSpriteRenderSystem class uses a SDL_Renderer as drawing device to display TextureSprite objects.

__init__(target, present=True, *args, **kwargs)

Creates a new TextureSpriteRenderSystem.

target can be a Window, SDL_Window, Renderer or SDL_Renderer. If it is a Window or SDL_Window instance, a Renderer will be created to acquire the SDL_Renderer.

render(sprites, x=None, y=None, present=None)

Draw the passed sprites (or sprite).

Parameters:

• sprites (sdl2.ext.sprite.Sprite, iterable) – the sprite(s) to be rendered.
• x (int) – if None, the sprites position will be used; if not None and sprites is an iterable, it will be considered as a relative position, added to the sprite position; if not None and sprites is a single sprite, will be considered as absolute position.
• y (int) – same as x, for vertical position.
• present (bool) – if True the rendered data will be presented at the end of the method. Defaults to None.

Raises:

SDLError (if sdl2.render.SDL_RenderCopyEx fails)

class sdl2.ext.sprite.Renderer(target, index=-1, logical_size=None, flags=2)

Bases: object

SDL2-based renderer for windows and sprites.

__init__(target, index=-1, logical_size=None, flags=2)

Create a new Renderer for the given target.

If target is a Window or SDL_Window, index and flags are passed to the relevant sdl.render.create_renderer() call. If target is a SoftwareSprite or SDL_Surface, the index and flags arguments are ignored.

blendmode

The blend mode used for drawing operations (fill and line).

clear(color=None)

Clears the renderer with the currently set or passed color.

color

The drawing color of the Renderer.

copy(src, srcrect=None, dstrect=None, angle=0, center=None, flip=0)

Copy (blit) the passed source to the target of the Renderer.

Parameters:src (TextureSprite, sdl2.SDL_Texture) – source to be copied

Kwargs:

srcrect (rect): rectangle to be used for clipping portions of src dstrect (rect): destination rectangle, where to blit angle (float): rotate around center by the given degrees

Raises:TypeError, SDLError

Example

>>> copy(src=tileset, srcrect=(0, 0, 32, 32),
         dstrect=(128, 64, 32, 32))

draw_line(points, color=None)

Draws one or multiple connected lines on the renderer.

draw_point(points, color=None)

Draws one or multiple points on the renderer.

draw_rect(rects, color=None)

Draws one or multiple rectangles on the renderer.

fill(rects, color=None)

Fills one or multiple rectangular areas on the renderer.

logical_size

The logical pixel size of the Renderer

present()

Refreshes the target of the Renderer.

renderer

scale

The horizontal and vertical drawing scale.