tessl/pypi-pysdl2

Pure Python wrapper around SDL2 libraries for cross-platform multimedia development

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Graphics and Rendering

Name: tessl/pypi-pysdl2
Author: tessl

Comprehensive graphics and rendering capabilities including software and hardware-accelerated rendering, texture management, surface operations, and primitive drawing. PySDL2 supports both low-level SDL2 rendering and high-level extension classes.

Capabilities

Renderer Creation and Management

Core functions for creating and managing renderers.

def SDL_CreateRenderer(window: SDL_Window, index: int, flags: int) -> SDL_Renderer:
    """
    Create a 2D rendering context for a window.
    
    Parameters:
    - window: window to create renderer for
    - index: index of rendering driver (-1 for first supporting flags)
    - flags: renderer flags (SDL_RENDERER_ACCELERATED, etc.)
    
    Returns:
    SDL_Renderer object or None on failure
    """

def SDL_DestroyRenderer(renderer: SDL_Renderer) -> None:
    """Destroy rendering context."""

def SDL_GetRenderer(window: SDL_Window) -> SDL_Renderer:
    """Get renderer associated with window."""

def SDL_GetRendererInfo(renderer: SDL_Renderer, info: SDL_RendererInfo) -> int:
    """Get information about renderer."""

def SDL_CreateSoftwareRenderer(surface: SDL_Surface) -> SDL_Renderer:
    """Create software renderer for surface."""

Renderer Flags and Info

Constants and structures for renderer configuration.

# Renderer flags
SDL_RENDERER_SOFTWARE: int = 0x00000001      # Software fallback
SDL_RENDERER_ACCELERATED: int = 0x00000002   # Hardware accelerated
SDL_RENDERER_PRESENTVSYNC: int = 0x00000004  # Present synchronized with refresh rate
SDL_RENDERER_TARGETTEXTURE: int = 0x00000008 # Supports render to texture

class SDL_RendererInfo:
    """Renderer information structure."""
    name: bytes                    # Name of renderer
    flags: int                     # Supported flags
    num_texture_formats: int       # Number of supported texture formats
    texture_formats: list[int]     # Supported texture formats
    max_texture_width: int         # Maximum texture width
    max_texture_height: int        # Maximum texture height

Basic Rendering Operations

Core rendering functions for clearing, presenting, and drawing.

def SDL_RenderClear(renderer: SDL_Renderer) -> int:
    """Clear rendering target with draw color."""

def SDL_RenderPresent(renderer: SDL_Renderer) -> None:
    """Update screen with rendering performed since last call."""

def SDL_SetRenderDrawColor(renderer: SDL_Renderer, r: int, g: int, b: int, a: int) -> int:
    """Set color for drawing operations."""

def SDL_GetRenderDrawColor(renderer: SDL_Renderer, r: ctypes.POINTER(ctypes.c_uint8), 
                          g: ctypes.POINTER(ctypes.c_uint8), b: ctypes.POINTER(ctypes.c_uint8), 
                          a: ctypes.POINTER(ctypes.c_uint8)) -> int:
    """Get color used for drawing operations."""

def SDL_SetRenderDrawBlendMode(renderer: SDL_Renderer, blendMode: int) -> int:
    """Set blend mode for drawing operations."""

def SDL_GetRenderDrawBlendMode(renderer: SDL_Renderer, blendMode: ctypes.POINTER(ctypes.c_int)) -> int:
    """Get blend mode used for drawing operations."""

Primitive Drawing

Functions for drawing basic shapes and primitives.

def SDL_RenderDrawPoint(renderer: SDL_Renderer, x: int, y: int) -> int:
    """Draw a point."""

def SDL_RenderDrawPoints(renderer: SDL_Renderer, points: ctypes.POINTER(SDL_Point), count: int) -> int:
    """Draw multiple points."""

def SDL_RenderDrawLine(renderer: SDL_Renderer, x1: int, y1: int, x2: int, y2: int) -> int:
    """Draw a line."""

def SDL_RenderDrawLines(renderer: SDL_Renderer, points: ctypes.POINTER(SDL_Point), count: int) -> int:
    """Draw connected lines."""

def SDL_RenderDrawRect(renderer: SDL_Renderer, rect: SDL_Rect) -> int:
    """Draw rectangle outline."""

def SDL_RenderDrawRects(renderer: SDL_Renderer, rects: ctypes.POINTER(SDL_Rect), count: int) -> int:
    """Draw multiple rectangle outlines."""

def SDL_RenderFillRect(renderer: SDL_Renderer, rect: SDL_Rect) -> int:
    """Fill rectangle."""

def SDL_RenderFillRects(renderer: SDL_Renderer, rects: ctypes.POINTER(SDL_Rect), count: int) -> int:
    """Fill multiple rectangles."""

Texture Management

Functions for creating, managing, and rendering textures.

def SDL_CreateTexture(renderer: SDL_Renderer, format: int, access: int, w: int, h: int) -> SDL_Texture:
    """
    Create texture for rendering context.
    
    Parameters:
    - renderer: rendering context
    - format: pixel format (SDL_PIXELFORMAT_*)
    - access: texture access pattern (SDL_TEXTUREACCESS_*)
    - w, h: texture dimensions
    
    Returns:
    SDL_Texture object or None on failure
    """

def SDL_CreateTextureFromSurface(renderer: SDL_Renderer, surface: SDL_Surface) -> SDL_Texture:
    """Create texture from existing surface."""

def SDL_DestroyTexture(texture: SDL_Texture) -> None:
    """Destroy texture."""

def SDL_QueryTexture(texture: SDL_Texture, format: ctypes.POINTER(ctypes.c_uint32), 
                    access: ctypes.POINTER(ctypes.c_int), w: ctypes.POINTER(ctypes.c_int), 
                    h: ctypes.POINTER(ctypes.c_int)) -> int:
    """Query texture properties."""

def SDL_SetTextureColorMod(texture: SDL_Texture, r: int, g: int, b: int) -> int:
    """Set texture color modulation."""

def SDL_GetTextureColorMod(texture: SDL_Texture, r: ctypes.POINTER(ctypes.c_uint8), 
                          g: ctypes.POINTER(ctypes.c_uint8), b: ctypes.POINTER(ctypes.c_uint8)) -> int:
    """Get texture color modulation."""

def SDL_SetTextureAlphaMod(texture: SDL_Texture, alpha: int) -> int:
    """Set texture alpha modulation."""

def SDL_GetTextureAlphaMod(texture: SDL_Texture, alpha: ctypes.POINTER(ctypes.c_uint8)) -> int:
    """Get texture alpha modulation."""

def SDL_SetTextureBlendMode(texture: SDL_Texture, blendMode: int) -> int:
    """Set texture blend mode."""

def SDL_GetTextureBlendMode(texture: SDL_Texture, blendMode: ctypes.POINTER(ctypes.c_int)) -> int:
    """Get texture blend mode."""

Texture Rendering

Functions for copying and rendering textures.

def SDL_RenderCopy(renderer: SDL_Renderer, texture: SDL_Texture, srcrect: SDL_Rect, dstrect: SDL_Rect) -> int:
    """
    Copy texture to rendering target.
    
    Parameters:
    - renderer: rendering context
    - texture: source texture
    - srcrect: source rectangle (None for entire texture)
    - dstrect: destination rectangle (None for entire target)
    """

def SDL_RenderCopyEx(renderer: SDL_Renderer, texture: SDL_Texture, srcrect: SDL_Rect, 
                    dstrect: SDL_Rect, angle: float, center: SDL_Point, flip: int) -> int:
    """
    Copy texture to rendering target with rotation and flipping.
    
    Parameters:
    - angle: rotation angle in degrees
    - center: point around which to rotate (None for texture center)
    - flip: flipping options (SDL_FLIP_NONE, SDL_FLIP_HORIZONTAL, SDL_FLIP_VERTICAL)
    """

def SDL_RenderGeometry(renderer: SDL_Renderer, texture: SDL_Texture, vertices: ctypes.POINTER(SDL_Vertex), 
                      num_vertices: int, indices: ctypes.POINTER(ctypes.c_int), num_indices: int) -> int:
    """Render list of triangles with optional texture and vertex colors."""

Texture Access Constants

SDL_TEXTUREACCESS_STATIC: int = 0     # Changes rarely, not lockable
SDL_TEXTUREACCESS_STREAMING: int = 1  # Changes frequently, lockable
SDL_TEXTUREACCESS_TARGET: int = 2     # Can be used as render target

# Texture flip constants
SDL_FLIP_NONE: int = 0x00000000
SDL_FLIP_HORIZONTAL: int = 0x00000001
SDL_FLIP_VERTICAL: int = 0x00000002

Surface Operations

Functions for software surface manipulation.

def SDL_CreateRGBSurface(flags: int, width: int, height: int, depth: int, 
                        Rmask: int, Gmask: int, Bmask: int, Amask: int) -> SDL_Surface:
    """Create RGB surface."""

def SDL_CreateRGBSurfaceWithFormat(flags: int, width: int, height: int, depth: int, format: int) -> SDL_Surface:
    """Create RGB surface with specific pixel format."""

def SDL_FreeSurface(surface: SDL_Surface) -> None:
    """Free surface."""

def SDL_LoadBMP(file: bytes) -> SDL_Surface:
    """Load BMP image from file."""

def SDL_SaveBMP(surface: SDL_Surface, file: bytes) -> int:
    """Save surface as BMP image."""

def SDL_BlitSurface(src: SDL_Surface, srcrect: SDL_Rect, dst: SDL_Surface, dstrect: SDL_Rect) -> int:
    """Blit surface to another surface."""

def SDL_BlitScaled(src: SDL_Surface, srcrect: SDL_Rect, dst: SDL_Surface, dstrect: SDL_Rect) -> int:
    """Blit surface with scaling."""

def SDL_FillRect(dst: SDL_Surface, rect: SDL_Rect, color: int) -> int:
    """Fill rectangle on surface with color."""

def SDL_FillRects(dst: SDL_Surface, rects: ctypes.POINTER(SDL_Rect), count: int, color: int) -> int:
    """Fill multiple rectangles on surface with color."""

High-Level Renderer Class

Extension module renderer class for simplified rendering.

class Renderer:
    """High-level renderer class for simplified graphics operations."""
    
    def __init__(self, target: Window, index: int = -1, flags: int = SDL_RENDERER_ACCELERATED):
        """
        Create renderer for window.
        
        Parameters:
        - target: Window object to render to
        - index: rendering driver index (-1 for default)
        - flags: renderer flags
        """
    
    def clear(self, color: tuple[int, int, int] = (0, 0, 0)) -> None:
        """
        Clear rendering target with color.
        
        Parameters:
        - color: RGB color tuple (0-255 each component)
        """
    
    def present(self) -> None:
        """Present rendered frame to screen."""
    
    def copy(self, texture: Texture, srcrect: SDL_Rect = None, dstrect: SDL_Rect = None) -> None:
        """
        Copy texture to rendering target.
        
        Parameters:
        - texture: Texture object to copy
        - srcrect: source rectangle (None for entire texture)
        - dstrect: destination rectangle (None for entire target)
        """
    
    def draw_line(self, start: tuple[int, int], end: tuple[int, int], color: tuple[int, int, int] = (255, 255, 255)) -> None:
        """
        Draw line between two points.
        
        Parameters:
        - start: (x, y) start point
        - end: (x, y) end point
        - color: RGB color tuple
        """
    
    def draw_rect(self, rect: tuple[int, int, int, int], color: tuple[int, int, int] = (255, 255, 255)) -> None:
        """
        Draw rectangle outline.
        
        Parameters:
        - rect: (x, y, width, height) rectangle
        - color: RGB color tuple
        """
    
    def fill_rect(self, rect: tuple[int, int, int, int], color: tuple[int, int, int] = (255, 255, 255)) -> None:
        """
        Fill rectangle.
        
        Parameters:
        - rect: (x, y, width, height) rectangle
        - color: RGB color tuple
        """
    
    @property
    def logical_size(self) -> tuple[int, int]:
        """Get logical rendering size."""
    
    @logical_size.setter
    def logical_size(self, value: tuple[int, int]) -> None:
        """Set logical rendering size."""

class Texture:
    """High-level texture class."""
    
    def __init__(self, renderer: Renderer, surface: SDL_Surface):
        """
        Create texture from surface.
        
        Parameters:
        - renderer: Renderer object
        - surface: SDL_Surface to create texture from
        """
    
    @property
    def size(self) -> tuple[int, int]:
        """Get texture size as (width, height) tuple."""

Blend Modes

Constants for alpha blending operations.

SDL_BLENDMODE_NONE: int = 0x00000000     # No blending
SDL_BLENDMODE_BLEND: int = 0x00000001    # Alpha blending
SDL_BLENDMODE_ADD: int = 0x00000002      # Additive blending
SDL_BLENDMODE_MOD: int = 0x00000004      # Color modulate
SDL_BLENDMODE_MUL: int = 0x00000008      # Color multiply

Types

class SDL_Renderer:
    """Opaque structure representing rendering context."""

class SDL_Texture:
    """Opaque structure representing texture."""

class SDL_Surface:
    """Surface structure for software rendering."""
    flags: int                    # Surface flags
    format: SDL_PixelFormat      # Pixel format
    w: int                       # Width in pixels
    h: int                       # Height in pixels
    pitch: int                   # Bytes per row
    pixels: ctypes.c_void_p      # Pixel data pointer
    userdata: ctypes.c_void_p    # User data pointer
    locked: int                  # Surface lock count
    list_blitmap: ctypes.c_void_p # Blit mapping info
    clip_rect: SDL_Rect          # Clipping rectangle
    map: ctypes.c_void_p         # Mapping info
    refcount: int                # Reference count

class SDL_Vertex:
    """Vertex structure for geometry rendering."""
    position: SDL_FPoint         # Vertex position
    color: SDL_Color            # Vertex color
    tex_coord: SDL_FPoint       # Texture coordinates

class SDL_Rect:
    """Rectangle structure."""
    x: int  # X coordinate
    y: int  # Y coordinate
    w: int  # Width
    h: int  # Height

class SDL_FRect:
    """Floating point rectangle structure."""
    x: float  # X coordinate
    y: float  # Y coordinate
    w: float  # Width
    h: float  # Height

class SDL_Point:
    """Point structure."""
    x: int  # X coordinate
    y: int  # Y coordinate

class SDL_FPoint:
    """Floating point structure."""
    x: float  # X coordinate
    y: float  # Y coordinate

class SDL_Color:
    """Color structure."""
    r: int  # Red component (0-255)
    g: int  # Green component (0-255)
    b: int  # Blue component (0-255)
    a: int  # Alpha component (0-255)

Usage Examples

Basic Rendering with Extensions

import sdl2.ext

# Initialize and create window
sdl2.ext.init()
window = sdl2.ext.Window("Rendering Example", size=(800, 600))
window.show()

# Create hardware-accelerated renderer
renderer = sdl2.ext.Renderer(window)

# Main rendering loop
running = True
while running:
    events = sdl2.ext.get_events()
    for event in events:
        if event.type == sdl2.SDL_QUIT:
            running = False
    
    # Clear screen with dark blue
    renderer.clear((0, 50, 100))
    
    # Draw some shapes
    renderer.fill_rect((100, 100, 200, 150), (255, 100, 100))  # Red rectangle
    renderer.draw_rect((350, 100, 200, 150), (100, 255, 100))  # Green outline
    renderer.draw_line((400, 300), (600, 450), (100, 100, 255))  # Blue line
    
    # Present the frame
    renderer.present()

sdl2.ext.quit()

Low-Level Rendering

import sdl2
import ctypes

# Initialize SDL2
sdl2.SDL_Init(sdl2.SDL_INIT_VIDEO)

# Create window
window = sdl2.SDL_CreateWindow(
    b"Low-level Rendering",
    sdl2.SDL_WINDOWPOS_CENTERED, sdl2.SDL_WINDOWPOS_CENTERED,
    800, 600,
    sdl2.SDL_WINDOW_SHOWN
)

# Create renderer
renderer = sdl2.SDL_CreateRenderer(window, -1, sdl2.SDL_RENDERER_ACCELERATED)

# Main loop
running = True
event = sdl2.SDL_Event()

while running:
    while sdl2.SDL_PollEvent(event):
        if event.type == sdl2.SDL_QUIT:
            running = False
    
    # Set draw color to dark blue
    sdl2.SDL_SetRenderDrawColor(renderer, 0, 50, 100, 255)
    sdl2.SDL_RenderClear(renderer)
    
    # Draw red rectangle
    rect = sdl2.SDL_Rect(100, 100, 200, 150)
    sdl2.SDL_SetRenderDrawColor(renderer, 255, 100, 100, 255)
    sdl2.SDL_RenderFillRect(renderer, rect)
    
    # Draw green line
    sdl2.SDL_SetRenderDrawColor(renderer, 100, 255, 100, 255)
    sdl2.SDL_RenderDrawLine(renderer, 400, 300, 600, 450)
    
    # Present frame
    sdl2.SDL_RenderPresent(renderer)

# Cleanup
sdl2.SDL_DestroyRenderer(renderer)
sdl2.SDL_DestroyWindow(window)
sdl2.SDL_Quit()

Texture Rendering

import sdl2
import sdl2.ext

# Initialize and create window/renderer
sdl2.ext.init()
window = sdl2.ext.Window("Texture Example", size=(800, 600))
window.show()
renderer = sdl2.ext.Renderer(window)

# Load image as surface then create texture
surface = sdl2.SDL_LoadBMP(b"image.bmp")
if surface:
    texture = sdl2.ext.Texture(renderer, surface)
    sdl2.SDL_FreeSurface(surface)
    
    # Main loop
    running = True
    while running:
        events = sdl2.ext.get_events()
        for event in events:
            if event.type == sdl2.SDL_QUIT:
                running = False
        
        # Clear and render texture
        renderer.clear((0, 0, 0))
        renderer.copy(texture, dstrect=sdl2.SDL_Rect(100, 100, 200, 200))
        renderer.present()

sdl2.ext.quit()

Install with Tessl CLI