SDL Rendering `tcod.sdl.render`¶

SDL2 Rendering functionality.

Added in version 13.4.

class tcod.sdl.render.BlendFactor(value)[source]¶

SDL blend factors.

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)[source]¶

SDL blend modes.

Added in version 13.5.

ADD = 2¶

BLEND = 1¶

INVALID = 2147483647¶

MOD = 4¶

NONE = 0¶

class tcod.sdl.render.BlendOperation(value)[source]¶

SDL blend operations.

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.LogicalPresentation(value)[source]¶

SDL logical presentation modes.

See https://wiki.libsdl.org/SDL3/SDL_RendererLogicalPresentation

Added in version 19.0.

DISABLED = 0¶

INTEGER_SCALE = 4¶

LETTERBOX = 2¶

OVERSCAN = 3¶

STRETCH = 1¶

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.number] | Sequence[tuple[float, float]]) → None[source]¶

Draw a connected series of lines from an array.

Parameters:: points – A sequence or array of (x, y) points.

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.number] | Sequence[tuple[float, float]]) → None[source]¶

Draw an array of points.

Parameters:: points – A sequence or array of (x, y) 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.number] | Sequence[tuple[float, float, float, float]]) → None[source]¶

Draw multiple outlined rectangles from an array.

Parameters:: rects – A sequence or array of (x, y, width, height) rectangles.

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.number] | Sequence[tuple[float, float, float, float]]) → None[source]¶

Fill multiple rectangles from an array.

Parameters:: rects – A sequence or array of (x, y, width, height) rectangles.

Added in version 13.5.

Render triangles from texture and vertex data.

Parameters:

texture – The SDL texture to render from.
xy – A sequence of (x, y) points to buffer.
color – A sequence of (r, g, b, a) colors to buffer.
uv – A sequence of (x, y) coordinates to buffer.
indices – A sequence of indexes referring to the buffered data, every 3 indexes is a triangle to render.

Added in version 13.5.

Changed in version 19.0: color now takes float values instead of 8-bit integers.

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: 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/SDL3/SDL_RenderReadPixels

Returns:: (height, width, channels) with the fetched pixels.
Return type:: The output uint8 array of shape

Added in version 15.0.

Changed in version 19.0: format no longer accepts int values.

set_logical_presentation(resolution: tuple[int, int], mode: LogicalPresentation) → None[source]¶: Set this renderers device independent resolution.

See also

https://wiki.libsdl.org/SDL3/SDL_SetRenderLogicalPresentation

Added in version 19.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 logical_size: tuple[int, int]¶

Get current independent (width, height) resolution.

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

Added in version 13.5.

Changed in version 19.0: Setter is deprecated, use set_logical_presentation instead.

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)[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)[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: str | None = None, vsync: int = True) → 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.
vsync – If True then Vsync will be enabled.

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)

See also

tcod.sdl.video.new_window()

Changed in version 19.0: Removed software and target_textures parameters. vsync now takes an integer. driver now take a string.

SDL Rendering tcod.sdl.render¶

SDL Rendering `tcod.sdl.render`¶