0
# Graphics and Rendering
1

2
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.
3

4
## Capabilities
5

6
### Renderer Creation and Management
7

8
Core functions for creating and managing renderers.
9

10
```python { .api }
11
def SDL_CreateRenderer(window: SDL_Window, index: int, flags: int) -> SDL_Renderer:
12
    """
13
    Create a 2D rendering context for a window.
14
    
15
    Parameters:
16
    - window: window to create renderer for
17
    - index: index of rendering driver (-1 for first supporting flags)
18
    - flags: renderer flags (SDL_RENDERER_ACCELERATED, etc.)
19
    
20
    Returns:
21
    SDL_Renderer object or None on failure
22
    """
23

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

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

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

33
def SDL_CreateSoftwareRenderer(surface: SDL_Surface) -> SDL_Renderer:
34
    """Create software renderer for surface."""
35
```
36

37
### Renderer Flags and Info
38

39
Constants and structures for renderer configuration.
40

41
```python { .api }
42
# Renderer flags
43
SDL_RENDERER_SOFTWARE: int = 0x00000001      # Software fallback
44
SDL_RENDERER_ACCELERATED: int = 0x00000002   # Hardware accelerated
45
SDL_RENDERER_PRESENTVSYNC: int = 0x00000004  # Present synchronized with refresh rate
46
SDL_RENDERER_TARGETTEXTURE: int = 0x00000008 # Supports render to texture
47

48
class SDL_RendererInfo:
49
    """Renderer information structure."""
50
    name: bytes                    # Name of renderer
51
    flags: int                     # Supported flags
52
    num_texture_formats: int       # Number of supported texture formats
53
    texture_formats: list[int]     # Supported texture formats
54
    max_texture_width: int         # Maximum texture width
55
    max_texture_height: int        # Maximum texture height
56
```
57

58
### Basic Rendering Operations
59

60
Core rendering functions for clearing, presenting, and drawing.
61

62
```python { .api }
63
def SDL_RenderClear(renderer: SDL_Renderer) -> int:
64
    """Clear rendering target with draw color."""
65

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

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

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

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

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

84
### Primitive Drawing
85

86
Functions for drawing basic shapes and primitives.
87

88
```python { .api }
89
def SDL_RenderDrawPoint(renderer: SDL_Renderer, x: int, y: int) -> int:
90
    """Draw a point."""
91

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

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

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

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

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

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

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

114
### Texture Management
115

116
Functions for creating, managing, and rendering textures.
117

118
```python { .api }
119
def SDL_CreateTexture(renderer: SDL_Renderer, format: int, access: int, w: int, h: int) -> SDL_Texture:
120
    """
121
    Create texture for rendering context.
122
    
123
    Parameters:
124
    - renderer: rendering context
125
    - format: pixel format (SDL_PIXELFORMAT_*)
126
    - access: texture access pattern (SDL_TEXTUREACCESS_*)
127
    - w, h: texture dimensions
128
    
129
    Returns:
130
    SDL_Texture object or None on failure
131
    """
132

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

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

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

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

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

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

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

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

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

164
### Texture Rendering
165

166
Functions for copying and rendering textures.
167

168
```python { .api }
169
def SDL_RenderCopy(renderer: SDL_Renderer, texture: SDL_Texture, srcrect: SDL_Rect, dstrect: SDL_Rect) -> int:
170
    """
171
    Copy texture to rendering target.
172
    
173
    Parameters:
174
    - renderer: rendering context
175
    - texture: source texture
176
    - srcrect: source rectangle (None for entire texture)
177
    - dstrect: destination rectangle (None for entire target)
178
    """
179

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

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

196
### Texture Access Constants
197

198
```python { .api }
199
SDL_TEXTUREACCESS_STATIC: int = 0     # Changes rarely, not lockable
200
SDL_TEXTUREACCESS_STREAMING: int = 1  # Changes frequently, lockable
201
SDL_TEXTUREACCESS_TARGET: int = 2     # Can be used as render target
202

203
# Texture flip constants
204
SDL_FLIP_NONE: int = 0x00000000
205
SDL_FLIP_HORIZONTAL: int = 0x00000001
206
SDL_FLIP_VERTICAL: int = 0x00000002
207
```
208

209
### Surface Operations
210

211
Functions for software surface manipulation.
212

213
```python { .api }
214
def SDL_CreateRGBSurface(flags: int, width: int, height: int, depth: int, 
215
                        Rmask: int, Gmask: int, Bmask: int, Amask: int) -> SDL_Surface:
216
    """Create RGB surface."""
217

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

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

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

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

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

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

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

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

243
### High-Level Renderer Class
244

245
Extension module renderer class for simplified rendering.
246

247
```python { .api }
248
class Renderer:
249
    """High-level renderer class for simplified graphics operations."""
250
    
251
    def __init__(self, target: Window, index: int = -1, flags: int = SDL_RENDERER_ACCELERATED):
252
        """
253
        Create renderer for window.
254
        
255
        Parameters:
256
        - target: Window object to render to
257
        - index: rendering driver index (-1 for default)
258
        - flags: renderer flags
259
        """
260
    
261
    def clear(self, color: tuple[int, int, int] = (0, 0, 0)) -> None:
262
        """
263
        Clear rendering target with color.
264
        
265
        Parameters:
266
        - color: RGB color tuple (0-255 each component)
267
        """
268
    
269
    def present(self) -> None:
270
        """Present rendered frame to screen."""
271
    
272
    def copy(self, texture: Texture, srcrect: SDL_Rect = None, dstrect: SDL_Rect = None) -> None:
273
        """
274
        Copy texture to rendering target.
275
        
276
        Parameters:
277
        - texture: Texture object to copy
278
        - srcrect: source rectangle (None for entire texture)
279
        - dstrect: destination rectangle (None for entire target)
280
        """
281
    
282
    def draw_line(self, start: tuple[int, int], end: tuple[int, int], color: tuple[int, int, int] = (255, 255, 255)) -> None:
283
        """
284
        Draw line between two points.
285
        
286
        Parameters:
287
        - start: (x, y) start point
288
        - end: (x, y) end point
289
        - color: RGB color tuple
290
        """
291
    
292
    def draw_rect(self, rect: tuple[int, int, int, int], color: tuple[int, int, int] = (255, 255, 255)) -> None:
293
        """
294
        Draw rectangle outline.
295
        
296
        Parameters:
297
        - rect: (x, y, width, height) rectangle
298
        - color: RGB color tuple
299
        """
300
    
301
    def fill_rect(self, rect: tuple[int, int, int, int], color: tuple[int, int, int] = (255, 255, 255)) -> None:
302
        """
303
        Fill rectangle.
304
        
305
        Parameters:
306
        - rect: (x, y, width, height) rectangle
307
        - color: RGB color tuple
308
        """
309
    
310
    @property
311
    def logical_size(self) -> tuple[int, int]:
312
        """Get logical rendering size."""
313
    
314
    @logical_size.setter
315
    def logical_size(self, value: tuple[int, int]) -> None:
316
        """Set logical rendering size."""
317

318
class Texture:
319
    """High-level texture class."""
320
    
321
    def __init__(self, renderer: Renderer, surface: SDL_Surface):
322
        """
323
        Create texture from surface.
324
        
325
        Parameters:
326
        - renderer: Renderer object
327
        - surface: SDL_Surface to create texture from
328
        """
329
    
330
    @property
331
    def size(self) -> tuple[int, int]:
332
        """Get texture size as (width, height) tuple."""
333
```
334

335
### Blend Modes
336

337
Constants for alpha blending operations.
338

339
```python { .api }
340
SDL_BLENDMODE_NONE: int = 0x00000000     # No blending
341
SDL_BLENDMODE_BLEND: int = 0x00000001    # Alpha blending
342
SDL_BLENDMODE_ADD: int = 0x00000002      # Additive blending
343
SDL_BLENDMODE_MOD: int = 0x00000004      # Color modulate
344
SDL_BLENDMODE_MUL: int = 0x00000008      # Color multiply
345
```
346

347
## Types
348

349
```python { .api }
350
class SDL_Renderer:
351
    """Opaque structure representing rendering context."""
352

353
class SDL_Texture:
354
    """Opaque structure representing texture."""
355

356
class SDL_Surface:
357
    """Surface structure for software rendering."""
358
    flags: int                    # Surface flags
359
    format: SDL_PixelFormat      # Pixel format
360
    w: int                       # Width in pixels
361
    h: int                       # Height in pixels
362
    pitch: int                   # Bytes per row
363
    pixels: ctypes.c_void_p      # Pixel data pointer
364
    userdata: ctypes.c_void_p    # User data pointer
365
    locked: int                  # Surface lock count
366
    list_blitmap: ctypes.c_void_p # Blit mapping info
367
    clip_rect: SDL_Rect          # Clipping rectangle
368
    map: ctypes.c_void_p         # Mapping info
369
    refcount: int                # Reference count
370

371
class SDL_Vertex:
372
    """Vertex structure for geometry rendering."""
373
    position: SDL_FPoint         # Vertex position
374
    color: SDL_Color            # Vertex color
375
    tex_coord: SDL_FPoint       # Texture coordinates
376

377
class SDL_Rect:
378
    """Rectangle structure."""
379
    x: int  # X coordinate
380
    y: int  # Y coordinate
381
    w: int  # Width
382
    h: int  # Height
383

384
class SDL_FRect:
385
    """Floating point rectangle structure."""
386
    x: float  # X coordinate
387
    y: float  # Y coordinate
388
    w: float  # Width
389
    h: float  # Height
390

391
class SDL_Point:
392
    """Point structure."""
393
    x: int  # X coordinate
394
    y: int  # Y coordinate
395

396
class SDL_FPoint:
397
    """Floating point structure."""
398
    x: float  # X coordinate
399
    y: float  # Y coordinate
400

401
class SDL_Color:
402
    """Color structure."""
403
    r: int  # Red component (0-255)
404
    g: int  # Green component (0-255)
405
    b: int  # Blue component (0-255)
406
    a: int  # Alpha component (0-255)
407
```
408

409
## Usage Examples
410

411
### Basic Rendering with Extensions
412

413
```python
414
import sdl2.ext
415

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

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

424
# Main rendering loop
425
running = True
426
while running:
427
    events = sdl2.ext.get_events()
428
    for event in events:
429
        if event.type == sdl2.SDL_QUIT:
430
            running = False
431
    
432
    # Clear screen with dark blue
433
    renderer.clear((0, 50, 100))
434
    
435
    # Draw some shapes
436
    renderer.fill_rect((100, 100, 200, 150), (255, 100, 100))  # Red rectangle
437
    renderer.draw_rect((350, 100, 200, 150), (100, 255, 100))  # Green outline
438
    renderer.draw_line((400, 300), (600, 450), (100, 100, 255))  # Blue line
439
    
440
    # Present the frame
441
    renderer.present()
442

443
sdl2.ext.quit()
444
```
445

446
### Low-Level Rendering
447

448
```python
449
import sdl2
450
import ctypes
451

452
# Initialize SDL2
453
sdl2.SDL_Init(sdl2.SDL_INIT_VIDEO)
454

455
# Create window
456
window = sdl2.SDL_CreateWindow(
457
    b"Low-level Rendering",
458
    sdl2.SDL_WINDOWPOS_CENTERED, sdl2.SDL_WINDOWPOS_CENTERED,
459
    800, 600,
460
    sdl2.SDL_WINDOW_SHOWN
461
)
462

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

466
# Main loop
467
running = True
468
event = sdl2.SDL_Event()
469

470
while running:
471
    while sdl2.SDL_PollEvent(event):
472
        if event.type == sdl2.SDL_QUIT:
473
            running = False
474
    
475
    # Set draw color to dark blue
476
    sdl2.SDL_SetRenderDrawColor(renderer, 0, 50, 100, 255)
477
    sdl2.SDL_RenderClear(renderer)
478
    
479
    # Draw red rectangle
480
    rect = sdl2.SDL_Rect(100, 100, 200, 150)
481
    sdl2.SDL_SetRenderDrawColor(renderer, 255, 100, 100, 255)
482
    sdl2.SDL_RenderFillRect(renderer, rect)
483
    
484
    # Draw green line
485
    sdl2.SDL_SetRenderDrawColor(renderer, 100, 255, 100, 255)
486
    sdl2.SDL_RenderDrawLine(renderer, 400, 300, 600, 450)
487
    
488
    # Present frame
489
    sdl2.SDL_RenderPresent(renderer)
490

491
# Cleanup
492
sdl2.SDL_DestroyRenderer(renderer)
493
sdl2.SDL_DestroyWindow(window)
494
sdl2.SDL_Quit()
495
```
496

497
### Texture Rendering
498

499
```python
500
import sdl2
501
import sdl2.ext
502

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

509
# Load image as surface then create texture
510
surface = sdl2.SDL_LoadBMP(b"image.bmp")
511
if surface:
512
    texture = sdl2.ext.Texture(renderer, surface)
513
    sdl2.SDL_FreeSurface(surface)
514
    
515
    # Main loop
516
    running = True
517
    while running:
518
        events = sdl2.ext.get_events()
519
        for event in events:
520
            if event.type == sdl2.SDL_QUIT:
521
                running = False
522
        
523
        # Clear and render texture
524
        renderer.clear((0, 0, 0))
525
        renderer.copy(texture, dstrect=sdl2.SDL_Rect(100, 100, 200, 200))
526
        renderer.present()
527

528
sdl2.ext.quit()
529
```