sdl2.ext.renderer - Accelerated 2D Rendering¶

The sdl2.ext.renderer module implements a Pythonic interface for working with the SDL Renderer API, which allows for easy hardware-accelerated 2D rendering with backends for a number of platforms (e.g. OpenGL, Direct3D, Metal) as well as a software-accelerated fallback.

sdl2.ext.renderer.set_texture_scale_quality(method)[source]¶

Sets the default scaling quailty for Texture objects.

By default, SDL2 uses low-quality nearest-neighbour scaling for all new textures. This method lets you change the default scaling method to one of the following options:

Method	Description
Nearest	Nearest-neighbour pixel scaling (no filtering)
Linear	Linear filtering
Best	Anisotropic filtering (falls back to linear if not available)

This function does not apply retroactively, and will only affect textures created after it is called.

Parameters:	method (str) – The default scaling method to use for SDL textures. Must be one of ‘nearest’, ‘linear’, or ‘best’.

class sdl2.ext.renderer.Texture(renderer, surface)[source]¶

A 2D texture to be used with a Renderer.

In SDL2, textures are 2D images that have been prepared for fast rendering with a given renderer. For example, if an SDL surface is converted into a texture with a Renderer using the OpenGL backend, the pixel data for the surface will internally be converted into an OpenGL texture.

Once a surface has been converted into a Texture, the surface can be safely deleted if no longer needed.

Parameters:	renderer (`Renderer`) – The renderer associated with the texture. surface (`SDL_Surface`) – An SDL surface from which the texture will be created.

tx¶

The underlying base SDL texture object. Can be used to perform operations with the texture using the base PySDL2 bindings.

Type:	`SDL_Texture`

size¶

The width and height (in pixels) of the texture.

Type:	tuple

destroy()[source]¶

Deletes the texture and frees its associated memory.

When a texture is no longer needed, it should be destroyed using this method to free up memory for new textures. After being destroyed, a texture can no longer be used.

scale_mode¶

The current scaling mode to use for rendering the texture. Can be ‘nearest’, ‘linear’, ‘best’, or ‘unknown’.

See set_texture_scale_quality() for more information.

Note

For SDL versions older than 2.0.12, the scaling mode will always be ‘unknown’.

Type:	str

set_scale_mode(mode)[source]¶

Sets a custom scaling method to use for rendering the texture.

This method overrides the default texture scaling method specified by set_texture_scale_quality(), the documentation for which describes the different possible scaling modes.

Note

Support for custom per-texture scaling modes is only available in SDL2 2.0.12 and up. As such, this method has no effect when used with earlier releases of SDL2.

Parameters:	mode (str) – The scaling method to use for the current texture. Must be one of ‘nearest’, ‘linear’, or ‘best’.

class sdl2.ext.renderer.Renderer(target, backend=-1, logical_size=None, flags=2)[source]¶

A rendering context for SDL2 windows and sprites.

A Renderer can be created from an SDL window, an SDL Surface, or a SoftwareSprite. Depending on the settings and operating system, this rendering context can use either hardware or software acceleration.

A useful feature of SDL renderers is that that the logical size of the rendering context can be different than the actual size (in pixels) of its target window or surface. For example, the renderer for a 1024x768 window can be set to have a logical size of 640x480, improving performance at the cost of image quality. The rendered content will be automatically scaled to fit the target, and will be centered with black bars on either side in the case of an aspect ratio mismatch.

If creating a rendering context from a window, you can customize the renderer using flags to request different settings:

Flag	Description
`SDL_RENDERER_SOFTWARE`	Requests a software-accelerated renderer.
`SDL_RENDERER_ACCELERATED`	Requests a hardware-accelerated renderer.
`SDL_RENDERER_PRESENTVSYNC`	Enables vsync support for `present()`.
`SDL_RENDERER_TARGETTEXTURE`	Requests support for rendering to texture.

To combine multiple flags, you can use a bitwise OR to combine two or more together before passing them to the flags argument:

render_flags = (
    sdl2.SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC
)
sdl2.ext.Renderer(window, flags=render_flags)

By default, SDL2 will choose the first renderer backend that supports all the requested flags. However, you can also request a specific rendering backend by name (e.g. ‘opengl’, ‘opengles2’, ‘metal’, ‘direct3d’, etc.), giving you more control but likely making your code less cross-platform.

Parameters:

target (Window, SDL_Surface) – The target window or surface from which to create the rendering context.
backend (str or int, optional) – The name of the specific backend to use for the new rendering context (e.g. ‘opengl’). Defaults to letting SDL2 decide. If target is not an SDL window, this argument has no effect.
logical_size (tuple, optional) – The initial logical size (in pixels) of the rendering context as a (w, h) tuple. Defaults to the size of the target window or surface.
flags (int, optional) – The requested features and settings for the new rendering context. Defaults to requesting a hardware-accelerated context. If target is not an SDL window, this argument has no effect.

Raises:

RuntimeError – If a requested rendering backend is not available.

sdlrenderer¶

The underlying base SDL renderer object. Can be used to perform operations with the renderer using the base PySDL2 bindings.

Type:	`SDL_Renderer`

logical_size¶

The logical size of the rendering context (in pixels), as a (width, height) tuple.

Type:	tuple

color¶

The current drawing color of the renderer.

Type:	`Color`

blendmode¶

The blend mode used for fill() and line() drawing operations. This value can be any of the following constants:

Flag	Description
`SDL_BLENDMODE_NONE`	No blending
`SDL_BLENDMODE_BLEND`	Alpha channel blending
`SDL_BLENDMODE_ADD`	Additive blending
`SDL_BLENDMODE_MOD`	Color modulation
`SDL_BLENDMODE_MUL`	Color multiplication (SDL >= 2.0.12)

Type:	int

scale¶

The x/y scaling factors applied to all drawing coordinates before rendering, in the format (scale_x, scale_y). These can be used to facilitate resolution-independent drawing.

Type:	tuple

destroy()[source]¶

Destroys the renderer and any associated textures.

When a renderer is no longer needed, it should be destroyed using this method to free up its associated memory. After being destroyed, a renderer can no longer be used.

reset_logical_size()[source]¶: Resets the logical size of the renderer to its original value.

clear(color=None)[source]¶

Clears the rendering surface with a given color.

Parameters:	color (`Color`, optional) – The color with which to clear the entire rendering context. If not specified, the renderer’s current `color` will be used.

copy(src, srcrect=None, dstrect=None, angle=0, center=None, flip=0)[source]¶

Copies (blits) a texture to the rendering context.

If the source texture is an SDL_Surface, you will need to convert it into a Texture first before it can be copied to the rendering surface.

The source texture can be flipped horizontally or vertically when being copied to the rendering context using one of the following flags:

Flag	Description
`SDL_FLIP_NONE`	Does not flip the source (default)
`SDL_FLIP_HORIZONTAL`	Flips the source horizontally
`SDL_FLIP_VERTICAL`	Flips the source vertically

Note

Subpixel rendering (i.e. using floats as pixel coordinates) requires SDL 2.0.10 or newer.

Parameters:

src (Texture, SDL_Texture) – The source texture to copy to the rendering surface.
srcrect (tuple, optional) – An (x, y, w, h) rectangle defining the subset of the source texture to copy to the rendering surface. Defaults to copying the entire source texture.
dstrect (tuple, optional) – An (x, y, w, h) rectangle defining the region of the rendering surface to which the source texture will be copied. Alternatively, if only (x, y) coordinates are provided, the width and height of the source rectangle will be used. Defaults to stretching the source across the entire rendering context.
angle (float, optional) – The clockwise rotation (in degrees) to apply to the destination rectangle. Defaults to no rotation.
center (tuple, optional) – The point around with the destination rectangle will be rotated. Defaults to the center of the destination rectangle.
flip (int, optional) – A flag indicating whether the source should be flipped (horizontally or vertically) when rendering to the render context. Defaults to no flipping.

blit(src, srcrect=None, dstrect=None, angle=0, center=None, flip=0)[source]¶

Copies a texture to the rendering context.

An alias for the copy() method.

present()[source]¶

Presents the current rendering surface to the screen.

Because SDL renderers use batch rendering (i.e. they have a separate backbuffer that is drawn to and buffer shown on screen which are switched when this function is called), any drawing operations performed with the renderer will not take effect until this method is called.

It is recommended that you clear and redraw the contents of the rendering context every time before this method is called, as the contents of the buffers are not guaranteed to remain the same between repeat presentations.

draw_line(points, color=None)[source]¶

Draws one or more connected lines on the rendering context.

Note

Subpixel rendering (i.e. using floats as pixel coordinates) requires SDL 2.0.10 or newer.

Parameters:	points (list) – A list of 2 or more `(x, y)` coordinates or `SDL_Point` objects defining the set of connected lines to draw. color (`Color`, optional) – The color with which to draw the lines. If not specified, the renderer’s current `color` will be used.

draw_point(points, color=None)[source]¶

Draws one or more points on the rendering context.

Note

Subpixel rendering (i.e. using floats as pixel coordinates) requires SDL 2.0.10 or newer.

Parameters:	points (list) – A list of `(x, y)` coordinates or `SDL_Point` objects defining the set of points to draw. color (`Color`, optional) – The color with which to draw the points. If not specified, the renderer’s current `color` will be used.

draw_rect(rects, color=None)[source]¶

Draws one or more rectangles on the rendering context.

Rectangles can be specified as 4-item (x, y, w, h) tuples, SDL_Rect objects, or a list containing multiple rectangles in either format.

Note

Subpixel rendering (i.e. using floats as pixel coordinates) requires SDL 2.0.10 or newer.

Parameters:	rects (tuple, `SDL_Rect`, list) – The rectangle(s) to draw to the rendering context. color (`Color`, optional) – The color with which to draw the rectangle(s). If not specified, the renderer’s current `color` will be used.

fill(rects, color=None)[source]¶

Fills one or more rectangular regions the rendering context.

Fill regions can be specified as 4-item (x, y, w, h) tuples, SDL_Rect objects, or a list containing multiple rectangles in either format.

Note

Subpixel rendering (i.e. using floats as pixel coordinates) requires SDL 2.0.10 or newer.

Parameters:	rects (tuple, `SDL_Rect`, list) – The rectangle(s) to fill within the rendering context. color (`Color`, optional) – The color with which to fill the rectangle(s). If not specified, the renderer’s current `color` will be used.