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

Window and Display Management

Name: tessl/pypi-pysdl2
Author: tessl

Comprehensive window creation, display mode handling, and OpenGL context management. PySDL2 provides both low-level window control through direct SDL2 bindings and high-level window classes through the extensions module.

Capabilities

Window Creation and Management

Core window functions for creating, managing, and manipulating windows.

def SDL_CreateWindow(title: bytes, x: int, y: int, w: int, h: int, flags: int) -> SDL_Window:
    """
    Create a window with specified parameters.
    
    Parameters:
    - title: window title as bytes
    - x, y: initial position (or SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_UNDEFINED)
    - w, h: window dimensions in pixels
    - flags: window flags (SDL_WINDOW_OPENGL, SDL_WINDOW_RESIZABLE, etc.)
    
    Returns:
    SDL_Window object or None on failure
    """

def SDL_DestroyWindow(window: SDL_Window) -> None:
    """Destroy a window and free associated resources."""

def SDL_ShowWindow(window: SDL_Window) -> None:
    """Show a window."""

def SDL_HideWindow(window: SDL_Window) -> None:
    """Hide a window."""

def SDL_SetWindowTitle(window: SDL_Window, title: bytes) -> None:
    """Set window title."""

def SDL_GetWindowTitle(window: SDL_Window) -> bytes:
    """Get window title."""

def SDL_SetWindowSize(window: SDL_Window, w: int, h: int) -> None:
    """Set window size."""

def SDL_GetWindowSize(window: SDL_Window, w: ctypes.POINTER(ctypes.c_int), h: ctypes.POINTER(ctypes.c_int)) -> None:
    """Get window size."""

def SDL_SetWindowPosition(window: SDL_Window, x: int, y: int) -> None:
    """Set window position."""

def SDL_GetWindowPosition(window: SDL_Window, x: ctypes.POINTER(ctypes.c_int), y: ctypes.POINTER(ctypes.c_int)) -> None:
    """Get window position."""

Window Flags and States

Constants for window creation and state management.

# Window creation flags
SDL_WINDOW_FULLSCREEN: int = 0x00000001
SDL_WINDOW_OPENGL: int = 0x00000002  
SDL_WINDOW_SHOWN: int = 0x00000004
SDL_WINDOW_HIDDEN: int = 0x00000008
SDL_WINDOW_BORDERLESS: int = 0x00000010
SDL_WINDOW_RESIZABLE: int = 0x00000020
SDL_WINDOW_MINIMIZED: int = 0x00000040
SDL_WINDOW_MAXIMIZED: int = 0x00000080
SDL_WINDOW_INPUT_GRABBED: int = 0x00000100
SDL_WINDOW_INPUT_FOCUS: int = 0x00000200
SDL_WINDOW_MOUSE_FOCUS: int = 0x00000400
SDL_WINDOW_FULLSCREEN_DESKTOP: int = 0x00001001
SDL_WINDOW_FOREIGN: int = 0x00000800
SDL_WINDOW_ALLOW_HIGHDPI: int = 0x00002000
SDL_WINDOW_MOUSE_CAPTURE: int = 0x00004000  
SDL_WINDOW_ALWAYS_ON_TOP: int = 0x00008000
SDL_WINDOW_SKIP_TASKBAR: int = 0x00010000
SDL_WINDOW_UTILITY: int = 0x00020000
SDL_WINDOW_TOOLTIP: int = 0x00040000
SDL_WINDOW_POPUP_MENU: int = 0x00080000
SDL_WINDOW_VULKAN: int = 0x10000000
SDL_WINDOW_METAL: int = 0x20000000

# Window positioning constants
SDL_WINDOWPOS_UNDEFINED: int = 0x1FFF0000
SDL_WINDOWPOS_CENTERED: int = 0x2FFF0000

Display Management

Functions for working with displays and display modes.

def SDL_GetNumVideoDisplays() -> int:
    """Get the number of available video displays."""

def SDL_GetDisplayBounds(displayIndex: int, rect: SDL_Rect) -> int:
    """Get display bounds."""

def SDL_GetCurrentDisplayMode(displayIndex: int, mode: SDL_DisplayMode) -> int:
    """Get current display mode."""

def SDL_GetDesktopDisplayMode(displayIndex: int, mode: SDL_DisplayMode) -> int:
    """Get desktop display mode."""

def SDL_GetNumDisplayModes(displayIndex: int) -> int:
    """Get number of display modes for a display."""

def SDL_GetDisplayMode(displayIndex: int, modeIndex: int, mode: SDL_DisplayMode) -> int:
    """Get specific display mode."""

def SDL_SetWindowDisplayMode(window: SDL_Window, mode: SDL_DisplayMode) -> int:
    """Set window display mode for fullscreen."""

def SDL_GetWindowDisplayMode(window: SDL_Window, mode: SDL_DisplayMode) -> int:
    """Get window display mode."""

High-Level Window Class

The extension module provides a Pythonic Window class for simplified window management.

class Window:
    """High-level window management class."""
    
    def __init__(self, title: str, size: tuple[int, int] = (800, 600), position: tuple[int, int] = None, flags: int = 0):
        """
        Create a new window.
        
        Parameters:
        - title: window title string
        - size: (width, height) tuple in pixels
        - position: (x, y) position tuple or None for default
        - flags: SDL window flags
        """
    
    def show(self) -> None:
        """Show the window."""
    
    def hide(self) -> None:
        """Hide the window."""
    
    def maximize(self) -> None:
        """Maximize the window."""
    
    def minimize(self) -> None:
        """Minimize the window."""
    
    def restore(self) -> None:
        """Restore the window from minimized/maximized state."""
    
    def refresh(self) -> None:
        """Refresh the window contents."""
    
    @property
    def size(self) -> tuple[int, int]:
        """Get window size as (width, height) tuple."""
    
    @size.setter  
    def size(self, value: tuple[int, int]) -> None:
        """Set window size from (width, height) tuple."""
    
    @property
    def position(self) -> tuple[int, int]:
        """Get window position as (x, y) tuple."""
    
    @position.setter
    def position(self, value: tuple[int, int]) -> None:
        """Set window position from (x, y) tuple."""
    
    @property
    def title(self) -> str:
        """Get window title."""
    
    @title.setter
    def title(self, value: str) -> None:
        """Set window title."""

OpenGL Context Management

Functions for creating and managing OpenGL contexts.

def SDL_GL_CreateContext(window: SDL_Window) -> SDL_GLContext:
    """Create an OpenGL context for use with window."""

def SDL_GL_DeleteContext(context: SDL_GLContext) -> None:
    """Delete an OpenGL context."""

def SDL_GL_MakeCurrent(window: SDL_Window, context: SDL_GLContext) -> int:
    """Set up an OpenGL context for rendering into an OpenGL window."""

def SDL_GL_SwapWindow(window: SDL_Window) -> None:
    """Update a window with OpenGL rendering."""

def SDL_GL_SetAttribute(attr: int, value: int) -> int:
    """Set an OpenGL window attribute before window creation."""

def SDL_GL_GetAttribute(attr: int, value: ctypes.POINTER(ctypes.c_int)) -> int:
    """Get an OpenGL window attribute."""

def SDL_GL_SetSwapInterval(interval: int) -> int:
    """Set the swap interval for the current OpenGL context."""

def SDL_GL_GetSwapInterval() -> int:
    """Get the swap interval for the current OpenGL context."""

Types

class SDL_Window:
    """Opaque structure representing a window."""

class SDL_GLContext:
    """Opaque structure representing an OpenGL context."""

class SDL_DisplayMode:
    """Display mode structure."""
    format: int         # pixel format
    w: int             # width in pixels
    h: int             # height in pixels
    refresh_rate: int  # refresh rate in Hz
    driverdata: ctypes.c_void_p  # driver-specific data

class SDL_Rect:
    """Rectangle structure."""
    x: int  # x coordinate
    y: int  # y coordinate  
    w: int  # width
    h: int  # height

Usage Examples

Basic Window Creation

import sdl2
import sdl2.ext

# Initialize SDL2
sdl2.ext.init()

# Create window using extension class
window = sdl2.ext.Window("My Application", size=(1024, 768))
window.show()

# Main loop
running = True
while running:
    events = sdl2.ext.get_events()
    for event in events:
        if event.type == sdl2.SDL_QUIT:
            running = False

# Cleanup
sdl2.ext.quit()

Low-Level Window Control

import sdl2

# Initialize SDL2 video subsystem
sdl2.SDL_Init(sdl2.SDL_INIT_VIDEO)

# Create window with specific flags
window = sdl2.SDL_CreateWindow(
    b"Low-level Window",
    sdl2.SDL_WINDOWPOS_CENTERED, sdl2.SDL_WINDOWPOS_CENTERED,
    800, 600,
    sdl2.SDL_WINDOW_SHOWN | sdl2.SDL_WINDOW_RESIZABLE
)

# Show window
sdl2.SDL_ShowWindow(window)

# Event loop
event = sdl2.SDL_Event()
running = True
while running:
    while sdl2.SDL_PollEvent(event):
        if event.type == sdl2.SDL_QUIT:
            running = False

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

Fullscreen and Display Modes

import sdl2

# Get display information
num_displays = sdl2.SDL_GetNumVideoDisplays()
print(f"Number of displays: {num_displays}")

# Get desktop display mode
display_mode = sdl2.SDL_DisplayMode()
sdl2.SDL_GetDesktopDisplayMode(0, display_mode)
print(f"Desktop mode: {display_mode.w}x{display_mode.h}@{display_mode.refresh_rate}Hz")

# Create fullscreen window
window = sdl2.SDL_CreateWindow(
    b"Fullscreen Window",
    sdl2.SDL_WINDOWPOS_UNDEFINED, sdl2.SDL_WINDOWPOS_UNDEFINED,
    0, 0,  # Size ignored for fullscreen desktop
    sdl2.SDL_WINDOW_FULLSCREEN_DESKTOP
)

Install with Tessl CLI