Sprite, texture and pixel surface routines

sdl2.ext.TEXTURE

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

sdl2.ext.SOFTWARE

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

class sdl2.ext.Sprite

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

x

The top-left horizontal offset at which the Sprite resides.

y

The top-left vertical offset at which the Sprite resides.

position

The top-left position (x and y) as tuple.

size

The width and height of the Sprite as tuple.

Note

This is an abstract property and needs to be implemented by inheriting classes.

area

The rectangular area occupied by the Sprite.

depth

The layer depth on which to draw the Sprite. Sprite objects with higher depth values will be drawn on top of other Sprite values by the SpriteRenderSystem.

class sdl2.ext.SoftwareSprite

A simple, visible, pixel-based 2D object, implemented on top of SDL2 software surfaces.

surface

The sdl2.SDL_Surface containing the pixel data.

size

The size of the SoftwareSprite as tuple.

subsprite(area : (int, int, int, int)) → SoftwareSprite

Creates another SoftwareSprite from a part of the SoftwareSprite. 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.

class sdl2.ext.TextureSprite

A simple, visible, pixel-based 2D object, implemented on top of SDL2 textures.

angle

The rotation angle for the TextureSprite.

center

The center to use for rotating the TextureSprite. None will reset the center to the default center of the TextureSprite.

flip

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

size

The size of the TextureSprite as tuple.

texture

The sdl2.SDL_Texture containing the texture data.

class sdl2.ext.SpriteRenderSystem

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.

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. If sortfunc shall be overridden, it must match the callback requirements for sorted().

process(world : World, components : iterable) → None

Renders the passed Sprite objects via the render() method. The Sprite objects are sorted via sortfunc before they are passed to render().

render(sprite : iterable) → None

Renders the Sprite objects.

Note

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

class sdl2.ext.SoftwareSpriteRenderSystem(window : object)

A rendering system for SoftwareSprite components. The SoftwareSpriteRenderSystem class uses a sdl2.SDL_Window as drawing device to display SoftwareSprite surfaces. It uses the internal SDL surface of the window as drawing context, so that GL operations, such as texture handling or the usage of SDL renderers is not possible.

window can be either a sdl2.ext.Window or sdl2.SDL_Window instance.

window

The sdl2.SDL_Window that is used as drawing device.

surface

The sdl2.SDL_Surface that acts as drawing context for window.

render(sprites : object[, x=None[, y=None]]) → None

Draws the passed sprites on the sdl2.ext.Window 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.TextureSpriteRenderSystem(target : object)

A rendering system for TextureSprite components. The TextureSpriteRenderSystem class uses a sdl2.SDL_Renderer as drawing device to display Sprite surfaces.

target can be a sdl2.ext.Window, sdl2.SDL_Window, a:class:sdl2.ext.Renderer or a sdl2.SDL_Renderer. If it is a sdl2.ext.Window or sdl2.SDL_Window instance, it will try to create a sdl2.SDL_Renderer with hardware acceleration for it.

sdlrenderer

The sdl2.SDL_Renderer that is used as drawing context.

rendertarget

The target for which the renderer was created, if any.

render(sprites : object[, x=None[, y=None]]) → None

Renders the passed sprites via the renderer. 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 TextureSprite objects, x and y are relative location values that will be added to each individual sprite’s position. If sprites is a single TextureSprite, x and y denote the absolute position of the TextureSprite, if set.

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

A factory class for creating Sprite objects. 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.

sprite_type

The sprite type created by the factory. This will be either SOFTWARE for SoftwareSprite or TEXTURE for TextureSprite objects.

default_args

The default arguments to use for creating new sprites.

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

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) → Sprite

Creates a Sprite. Depending on the sprite_type, this will return a SoftwareSprite or TextureSprite.

kwargs are the arguments to be passed for the sprite construction and can vary depending on the sprite type. Usually they have to follow the create_software_sprite() and create_texture_sprite() method signatures. kwargs however will be mixed with the set default_args so that one does not necessarily have to provide all arguments, if they are set within the default_args. If kwargs and default_args contain the same keys, the key-value pair of kwargs is chosen.

create_sprite_render_system(*args, **kwargs) → SpriteRenderSystem

Creates a new SpriteRenderSystem, based on the set sprite_type. If sprite_type is TEXTURE, a TextureSpriteRenderSystem is created with the the renderer from the default_args. Other keyword arguments are ignored in that case.

Otherwise a SoftwareSpriteRenderSystem is created and args and kwargs are passed to it.

create_texture_sprite(renderer : object, size, pformat=sdl2.SDL_PIXELFORMAT_RGBA8888, access=sdl2.SDL_TEXTUREACCESS_STATIC) → TextureSprite

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 : object, size, bpp=32, masks=None) → Sprite

Creates a Sprite with a certain color.

from_image(fname : str) → Sprite

Creates a Sprite from an image file. The image must be loadable via sdl2.ext.load_image().

from_object(obj: object) → Sprite

Creates a Sprite from an object. The object will be passed through sdl2.rwops_from_object() in order to try to load image data from it.

from_surface(surface : SDL_Surface[, free=False]) → Sprite

Creates a Sprite from the passed sdl2.SDL_Surface. If free is set to True, the passed surface will be freed automatically.

from_text(text : str[, **kwargs]) → Sprite

Creates a Sprite from a string of text. This method requires a sdl2.ext.FontManager to be in kwargs or default_args.

class sdl2.ext.Renderer(target : obj[, logical_size=None[, index=-1[, flags=sdl2.SDL_RENDERER_ACCELERATED]])

A rendering context for windows and sprites that can use hardware or software-accelerated graphics drivers.

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

sdlrenderer

The underlying sdl2.SDL_Renderer.

rendertarget

The target for which the Renderer was created.

logical_size

The logical size of the renderer.

Setting this allows you to draw as if your renderer had this size, even though the target may be larger or smaller. When drawing, the renderer will automatically scale your contents to the target, creating letter-boxing or sidebars if necessary.

To reset your logical size back to the target’s, set it to (0, 0).

Setting this to a lower value may be useful for low-resolution effects.

Setting this to a larger value may be useful for antialiasing.

color

The sdl2.ext.Color to use for draw and fill operations.

blendmode

The blend mode used for drawing operations (fill and line). This can be a value of

  • SDL_BLENDMODE_NONE for no blending
  • SDL_BLENDMODE_BLEND for alpha blending
  • SDL_BLENDMODE_ADD for additive color blending
  • SDL_BLENDMODE_MOD for multiplied color blending
scale

The horizontal and vertical drawing scale as two-value tuple.

clear([color=None])

Clears the rendering context with the currently set or passed color.

copy(src : obj[, srcrect=None[, dstrect=None[, angle=0[, center=None[, flip=render.SDL_FLIP_NONE]]]]]) → None

Copies (blits) the passed src, which can be a TextureSprite or sdl2.SDL_Texture, to the target of the Renderer. srcrect is the source rectangle to be used for clipping portions of src. dstrect is the destination rectangle. angle will cause the texture to be rotated around center by the given degrees. flip can be one of the SDL_FLIP_* constants and will flip the texture over its horizontal or vertical middle axis. If src is a TextureSprite, angle, center and flip will be set from src‘s attributes, if not provided.

draw_line(points : iterable[, color=None]) → None

Draws one or multiple lines on the rendering context. If line consists of four values (x1, y1, x2, y2) only, a single line is drawn. If line contains more than four values, a series of connected lines is drawn.

draw_point(points : iterable[, color=None]) → None

Draws one or multiple points on the rendering context. The points argument contains the x and y values of the points as simple sequence in the form (point1_x, point1_y, point2_x, point2_y, ...).

draw_rect(rects : iterable[, color=None]) → None

Draws one or multiple rectangles on the rendering context. rects contains sequences of four values denoting the x and y offset and width and height of each individual rectangle in the form ((x1, y1, w1, h1), (x2, y2, w2, h2), ...).

fill(rects : iterable[, color=None]) → None

Fills one or multiple rectangular areas on the rendering context with the current set or passed color. rects contains sequences of four values denoting the x and y offset and width and height of each individual rectangle in the form ((x1, y1, w1, h1), (x2, y2, w2, h2), ...).

present() → None

Refreshes the rendering context, causing changes to the render buffers to be shown.