SDL Rendering tcod.sdl.render

SDL2 Rendering functionality.

Added in version 13.4.

class tcod.sdl.render.BlendFactor(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

SDL blend factors.

See also

compose_blend_mode https://wiki.libsdl.org/SDL_BlendFactor

Added in version 13.5.

DST_ALPHA = 9
DST_COLOR = 7
ONE = 2
ONE_MINUS_DST_ALPHA = 10
ONE_MINUS_DST_COLOR = 8
ONE_MINUS_SRC_ALPHA = 6
ONE_MINUS_SRC_COLOR = 4
SRC_ALPHA = 5
SRC_COLOR = 3
ZERO = 1
class tcod.sdl.render.BlendMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

SDL blend modes.

See also

Texture.blend_mode Renderer.draw_blend_mode compose_blend_mode

Added in version 13.5.

ADD = 2
BLEND = 1
INVALID = 2147483647
MOD = 4
NONE = 0
class tcod.sdl.render.BlendOperation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

SDL blend operations.

See also

compose_blend_mode https://wiki.libsdl.org/SDL_BlendOperation

Added in version 13.5.

ADD = 1

dest + source

MAXIMUM = 5

max(dest, source)

MINIMUM = 4

min(dest, source)

REV_SUBTRACT = 3

source - dest

SUBTRACT = 2

dest - source

class tcod.sdl.render.Renderer(sdl_renderer_p: Any)[source]

SDL Renderer.

__eq__(other: object) → bool[source]

Return True if compared to the same renderer.

clear() → None[source]

Clear the current render target with draw_color.

Added in version 13.5.

copy(texture: ~tcod.sdl.render.Texture, source: tuple[float, float, float, float] | None = None, dest: tuple[float, float, float, float] | None = None, angle: float = 0, center: tuple[float, float] | None = None, flip: ~tcod.sdl.render.RendererFlip = <RendererFlip.NONE: 0>) → None[source]

Copy a texture to the rendering target.

Parameters:

  • texture – The texture to copy onto the current texture target.

  • source – The (x, y, width, height) region of texture to copy. If None then the entire texture is copied.

  • dest – The (x, y, width, height) region of the target. If None then the entire target is drawn over.

  • angle – The angle in degrees to rotate the image clockwise.

  • center – The (x, y) point where rotation is applied. If None then the center of dest is used.

  • flip – Flips the texture when drawing it.

Changed in version 13.5: source and dest can now be float tuples. Added the angle, center, and flip parameters.

draw_line(start: tuple[float, float], end: tuple[float, float]) → None[source]

Draw a single line.

Added in version 13.5.

draw_lines(points: NDArray[np.intc | np.float32]) → None[source]

Draw a connected series of lines from an array.

Added in version 13.5.

draw_point(xy: tuple[float, float]) → None[source]

Draw a point.

Added in version 13.5.

draw_points(points: NDArray[np.intc | np.float32]) → None[source]

Draw an array of points.

Added in version 13.5.

draw_rect(rect: tuple[float, float, float, float]) → None[source]

Draw a rectangle outline.

Added in version 13.5.

draw_rects(rects: NDArray[np.intc | np.float32]) → None[source]

Draw multiple outlined rectangles from an array.

Added in version 13.5.

fill_rect(rect: tuple[float, float, float, float]) → None[source]

Fill a rectangle with draw_color.

Added in version 13.5.

fill_rects(rects: NDArray[np.intc | np.float32]) → None[source]

Fill multiple rectangles from an array.

Added in version 13.5.

geometry(texture: Texture | None, xy: NDArray[np.float32], color: NDArray[np.uint8], uv: NDArray[np.float32], indices: NDArray[np.uint8 | np.uint16 | np.uint32] | None = None) → None[source]

Render triangles from texture and vertex data.

Added in version 13.5.

new_texture(width: int, height: int, *, format: int | None = None, access: int | None = None) → Texture[source]

Allocate and return a new Texture for this renderer.

Parameters:

  • width – The pixel width of the new texture.

  • height – The pixel height of the new texture.

  • format – The format the new texture.

  • access – The access mode of the texture. Defaults to TextureAccess.STATIC. See TextureAccess for more options.

present() → None[source]

Present the currently rendered image to the screen.

read_pixels(*, rect: tuple[int, int, int, int] | None = None, format: int | Literal['RGB', 'RGBA'] = 'RGBA', out: NDArray[np.uint8] | None = None) → NDArray[np.uint8][source]

Fetch the pixel contents of the current rendering target to an array.

By default returns an RGBA pixel array of the full target in the shape: (height, width, rgba). The target can be changed with set_render_target

Parameters:

  • rect – The (left, top, width, height) region of the target to fetch, or None for the entire target.

  • format – The pixel format. Defaults to "RGBA".

  • out – The output array. Can be None or must be an np.uint8 array of shape: (height, width, channels). Must be C contiguous along the (width, channels) axes.

This operation is slow due to coping from VRAM to RAM. When reading the main rendering target this should be called after rendering and before present. See https://wiki.libsdl.org/SDL2/SDL_RenderReadPixels

Returns:

(height, width, channels) with the fetched pixels.

Return type:

The output uint8 array of shape

Added in version 15.0.

set_render_target(texture: Texture) → _RestoreTargetContext[source]

Change the render target to texture, returns a context that will restore the original target when exited.

set_vsync(enable: bool) → None[source]

Enable or disable VSync for this renderer.

Added in version 13.5.

upload_texture(pixels: NDArray[Any], *, format: int | None = None, access: int | None = None) → Texture[source]

Return a new Texture from an array of pixels.

Parameters:

  • pixels – An RGB or RGBA array of pixels in row-major order.

  • format – The format of pixels when it isn’t a simple RGB or RGBA array.

  • access – The access mode of the texture. Defaults to TextureAccess.STATIC. See TextureAccess for more options.

property clip_rect: tuple[int, int, int, int] | None

Get or set the clipping rectangle of this renderer.

Set to None to disable clipping.

Added in version 13.5.

property draw_blend_mode: BlendMode

Get or set the active blend mode of this renderer.

Added in version 13.5.

property draw_color: tuple[int, int, int, int]

Get or set the active RGBA draw color for this renderer.

Added in version 13.5.

property integer_scaling: bool

Get or set if this renderer enforces integer scaling.

See also

https://wiki.libsdl.org/SDL_RenderSetIntegerScale

Added in version 13.5.

property logical_size: tuple[int, int]

Get or set a device independent (width, height) resolution.

Might be (0, 0) if a resolution was never assigned.

See also

https://wiki.libsdl.org/SDL_RenderSetLogicalSize

Added in version 13.5.

property output_size: tuple[int, int]

Get the (width, height) pixel resolution of the rendering context.

See also

https://wiki.libsdl.org/SDL_GetRendererOutputSize

Added in version 13.5.

property scale: tuple[float, float]

Get or set an (x_scale, y_scale) multiplier for drawing.

See also

https://wiki.libsdl.org/SDL_RenderSetScale

Added in version 13.5.

property viewport: tuple[int, int, int, int] | None

Get or set the drawing area for the current rendering target.

See also

https://wiki.libsdl.org/SDL_RenderSetViewport

Added in version 13.5.

class tcod.sdl.render.RendererFlip(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Flip parameter for Renderer.copy.

HORIZONTAL = 1

Flip the image horizontally.

NONE = 0

Default value, no flip.

VERTICAL = 2

Flip the image vertically.

class tcod.sdl.render.Texture(sdl_texture_p: Any, sdl_renderer_p: Any = None)[source]

SDL hardware textures.

Create a new texture using Renderer.new_texture or Renderer.upload_texture.

__eq__(other: object) → bool[source]

Return True if compared to the same texture.

update(pixels: NDArray[Any], rect: tuple[int, int, int, int] | None = None) → None[source]

Update the pixel data of this texture.

Added in version 13.5.

access: Final[TextureAccess]

Texture access mode, read only.

Changed in version 13.5: Attribute is now a TextureAccess value.

property alpha_mod: int

Texture alpha modulate value, can be set to 0 - 255.

property blend_mode: BlendMode

Texture blend mode, can be set.

Changed in version 13.5: Property now returns a BlendMode instance.

property color_mod: tuple[int, int, int]

Texture RGB color modulate values, can be set.

format: Final[int]

Texture format, read only.

height: Final[int]

Texture pixel height, read only.

width: Final[int]

Texture pixel width, read only.

class tcod.sdl.render.TextureAccess(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Determines how a texture is expected to be used.

STATIC = 0

Texture rarely changes.

STREAMING = 1

Texture frequently changes.

TARGET = 2

Texture will be used as a render target.

tcod.sdl.render.compose_blend_mode(source_color_factor: BlendFactor, dest_color_factor: BlendFactor, color_operation: BlendOperation, source_alpha_factor: BlendFactor, dest_alpha_factor: BlendFactor, alpha_operation: BlendOperation) → BlendMode[source]

Return a custom blend mode composed of the given factors and operations.

See also

https://wiki.libsdl.org/SDL_ComposeCustomBlendMode

Added in version 13.5.

tcod.sdl.render.new_renderer(window: Window, *, driver: int | None = None, software: bool = False, vsync: bool = True, target_textures: bool = False) → Renderer[source]

Initialize and return a new SDL Renderer.

Parameters:

  • window – The window that this renderer will be attached to.

  • driver – Force SDL to use a specific video driver.

  • software – If True then a software renderer will be forced. By default a hardware renderer is used.

  • vsync – If True then Vsync will be enabled.

  • target_textures – If True then target textures can be used by the renderer.

Example:

# Start by creating a window.
sdl_window = tcod.sdl.video.new_window(640, 480)
# Create a renderer with target texture support.
sdl_renderer = tcod.sdl.render.new_renderer(sdl_window, target_textures=True)

See also

tcod.sdl.video.new_window()