# 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`(imgsurface : sdl2.SDL_Surface, free : boolean)

  A simple, visible, pixel-based 2D object, implemented on top of SDL2 software surfaces. free indicates, whether imgsurface shall be automatically freed on deleting the SoftwareSprite.

  `free`

    Indicates, if the bound `surface` shall be freed on deleting the `SoftwareSprite`.

  `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`(texture : sdl2.SDL_Texture[, free=True])

  A simple, visible, pixel-based 2D object, implemented on top of SDL2 textures. free indicates, whether texture shall be automatically freed on deleting the TextureSprite.

  `free`

    Indicates, if the bound `texture` shall be freed on deleting the `TextureSprite`.

  `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 `sdlrenderer` 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.