tessl/pypi-pygame

Cross-platform library for developing multimedia applications and video games in Python built on top of SDL

Overview

Eval results

Files

Advanced Drawing

Name: tessl/pypi-pygame
Author: tessl

High-performance primitive drawing operations with antialiasing and advanced features. The pygame.gfxdraw module provides optimized functions for drawing shapes, textures, and geometric primitives with pixel-level precision and enhanced visual quality through antialiasing.

import pygame.gfxdraw

Capabilities

Pixel and Line Operations

Draw individual pixels and optimized horizontal/vertical lines for precise control.

def pixel(surface: pygame.Surface, x: int, y: int, color) -> None:
    """
    Draw a single pixel on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x (int): X coordinate
        y (int): Y coordinate
        color: Color to use (Color, tuple, or color name)
    """

def hline(surface: pygame.Surface, x1: int, x2: int, y: int, color) -> None:
    """
    Draw a horizontal line on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x1 (int): Starting X coordinate
        x2 (int): Ending X coordinate
        y (int): Y coordinate for the line
        color: Color to use
    """

def vline(surface: pygame.Surface, x: int, y1: int, y2: int, color) -> None:
    """
    Draw a vertical line on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x (int): X coordinate for the line
        y1 (int): Starting Y coordinate
        y2 (int): Ending Y coordinate
        color: Color to use
    """

Rectangle Drawing

Draw rectangles with outline and filled variants for efficient rendering.

def rectangle(surface: pygame.Surface, rect: pygame.Rect, color) -> None:
    """
    Draw a rectangle outline on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        rect (pygame.Rect): Rectangle area to draw
        color: Color to use for the outline
    """

def box(surface: pygame.Surface, rect: pygame.Rect, color) -> None:
    """
    Draw a filled rectangle on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        rect (pygame.Rect): Rectangle area to fill
        color: Color to use for filling
    """

Antialiased Shapes

Draw smooth, antialiased shapes for high-quality graphics with reduced aliasing artifacts.

def aacircle(surface: pygame.Surface, x: int, y: int, r: int, color) -> None:
    """
    Draw an antialiased circle outline on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x (int): X coordinate of center
        y (int): Y coordinate of center
        r (int): Radius in pixels
        color: Color to use
    """

def aaellipse(surface: pygame.Surface, x: int, y: int, rx: int, ry: int, color) -> None:
    """
    Draw an antialiased ellipse outline on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x (int): X coordinate of center
        y (int): Y coordinate of center
        rx (int): Horizontal radius
        ry (int): Vertical radius
        color: Color to use
    """

def aatrigon(surface: pygame.Surface, x1: int, y1: int, x2: int, y2: int, x3: int, y3: int, color) -> None:
    """
    Draw an antialiased triangle outline on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x1 (int): X coordinate of first vertex
        y1 (int): Y coordinate of first vertex
        x2 (int): X coordinate of second vertex
        y2 (int): Y coordinate of second vertex
        x3 (int): X coordinate of third vertex
        y3 (int): Y coordinate of third vertex
        color: Color to use
    """

def aapolygon(surface: pygame.Surface, points: list[tuple[int, int]], color) -> None:
    """
    Draw an antialiased polygon outline on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        points (list[tuple[int, int]]): List of (x, y) vertices
        color: Color to use
    """

Filled Shapes

Draw solid filled shapes for efficient area rendering and backgrounds.

def filled_circle(surface: pygame.Surface, x: int, y: int, r: int, color) -> None:
    """
    Draw a filled circle on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x (int): X coordinate of center
        y (int): Y coordinate of center
        r (int): Radius in pixels
        color: Color to use for filling
    """

def filled_ellipse(surface: pygame.Surface, x: int, y: int, rx: int, ry: int, color) -> None:
    """
    Draw a filled ellipse on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x (int): X coordinate of center
        y (int): Y coordinate of center
        rx (int): Horizontal radius
        ry (int): Vertical radius
        color: Color to use for filling
    """

def filled_trigon(surface: pygame.Surface, x1: int, y1: int, x2: int, y2: int, x3: int, y3: int, color) -> None:
    """
    Draw a filled triangle on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x1 (int): X coordinate of first vertex
        y1 (int): Y coordinate of first vertex
        x2 (int): X coordinate of second vertex
        y2 (int): Y coordinate of second vertex
        x3 (int): X coordinate of third vertex
        y3 (int): Y coordinate of third vertex
        color: Color to use for filling
    """

def filled_polygon(surface: pygame.Surface, points: list[tuple[int, int]], color) -> None:
    """
    Draw a filled polygon on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        points (list[tuple[int, int]]): List of (x, y) vertices
        color: Color to use for filling
    """

Advanced Shapes

Draw specialized shapes including arcs, textured polygons, and smooth curves.

def pie(surface: pygame.Surface, x: int, y: int, r: int, start: int, end: int, color) -> None:
    """
    Draw a filled pie slice (sector) on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x (int): X coordinate of center
        y (int): Y coordinate of center
        r (int): Radius in pixels
        start (int): Start angle in degrees
        end (int): End angle in degrees
        color: Color to use for filling
    """

def trigon(surface: pygame.Surface, x1: int, y1: int, x2: int, y2: int, x3: int, y3: int, color) -> None:
    """
    Draw a triangle outline on a surface.

    Args:
        surface (pygame.Surface): Surface to draw on
        x1 (int): X coordinate of first vertex
        y1 (int): Y coordinate of first vertex
        x2 (int): X coordinate of second vertex
        y2 (int): Y coordinate of second vertex
        x3 (int): X coordinate of third vertex
        y3 (int): Y coordinate of third vertex
        color: Color to use
    """

def textured_polygon(surface: pygame.Surface, points: list[tuple[int, int]], texture: pygame.Surface, tx: int, ty: int) -> None:
    """
    Draw a polygon filled with a texture pattern.

    Args:
        surface (pygame.Surface): Surface to draw on
        points (list[tuple[int, int]]): List of (x, y) vertices
        texture (pygame.Surface): Texture surface to use for filling
        tx (int): Texture X offset
        ty (int): Texture Y offset
    """

def bezier(surface: pygame.Surface, points: list[tuple[int, int]], steps: int, color) -> None:
    """
    Draw a smooth Bezier curve through control points.

    Args:
        surface (pygame.Surface): Surface to draw on
        points (list[tuple[int, int]]): Control points for the curve
        steps (int): Number of interpolation steps (higher = smoother)
        color: Color to use for the curve
    """

Usage Examples

Antialiased Graphics

import pygame
import pygame.gfxdraw

pygame.init()
screen = pygame.display.set_mode((800, 600))
screen.fill((0, 0, 0))

# Compare regular vs antialiased circles
pygame.draw.circle(screen, (255, 0, 0), (200, 150), 50, 2)  # Regular circle
pygame.gfxdraw.aacircle(screen, 600, 150, 50, (255, 0, 0))  # Antialiased circle

# Antialiased ellipse with smooth edges
pygame.gfxdraw.aaellipse(screen, 400, 300, 100, 50, (0, 255, 0))
pygame.gfxdraw.filled_ellipse(screen, 400, 300, 98, 48, (0, 100, 0))

# Smooth triangle
triangle_points = [(300, 450), (400, 350), (500, 450)]
pygame.gfxdraw.aatrigon(screen, *triangle_points[0], *triangle_points[1], *triangle_points[2], (0, 0, 255))

pygame.display.flip()

Precise Pixel Operations

import pygame
import pygame.gfxdraw
import random

pygame.init()
screen = pygame.display.set_mode((800, 600))
screen.fill((0, 0, 0))

# Draw starfield with individual pixels
for _ in range(1000):
    x = random.randint(0, 799)
    y = random.randint(0, 599)
    brightness = random.randint(100, 255)
    pygame.gfxdraw.pixel(screen, x, y, (brightness, brightness, brightness))

# Draw grid with horizontal and vertical lines
grid_color = (40, 40, 40)
for x in range(0, 800, 50):
    pygame.gfxdraw.vline(screen, x, 0, 599, grid_color)
for y in range(0, 600, 50):
    pygame.gfxdraw.hline(screen, 0, 799, y, grid_color)

# Highlight with brighter lines
pygame.gfxdraw.hline(screen, 0, 799, 300, (100, 100, 0))
pygame.gfxdraw.vline(screen, 400, 0, 599, (100, 100, 0))

pygame.display.flip()

Complex Shapes and Curves

import pygame
import pygame.gfxdraw
import math

pygame.init()
screen = pygame.display.set_mode((800, 600))
screen.fill((50, 50, 50))

# Draw pie chart segments
center = (200, 200)
radius = 80
segments = [30, 45, 60, 90, 120, 135]  # Angles
colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 255, 0), (255, 0, 255), (0, 255, 255)]

start_angle = 0
for i, segment in enumerate(segments):
    end_angle = start_angle + segment
    pygame.gfxdraw.pie(screen, center[0], center[1], radius, start_angle, end_angle, colors[i])
    start_angle = end_angle

# Draw smooth Bezier curve
control_points = [(500, 100), (600, 200), (700, 150), (750, 300)]
pygame.gfxdraw.bezier(screen, control_points, 100, (255, 255, 255))

# Mark control points
for point in control_points:
    pygame.gfxdraw.filled_circle(screen, point[0], point[1], 5, (255, 255, 0))

# Draw complex polygon with texture
polygon_points = [(100, 400), (200, 350), (250, 450), (150, 500), (50, 450)]
texture = pygame.Surface((20, 20))
pygame.draw.checkerboard(texture, (100, 100, 100), (150, 150, 150), 10)
pygame.gfxdraw.textured_polygon(screen, polygon_points, texture, 0, 0)

pygame.display.flip()

Performance Optimization with GFXDraw

import pygame
import pygame.gfxdraw
import time

pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()

# Efficient batch drawing operations
def draw_optimized_scene():
    screen.fill((0, 0, 0))

    # Use box() for filled rectangles - faster than pygame.draw.rect
    for x in range(0, 800, 40):
        for y in range(0, 600, 40):
            if (x + y) % 80 == 0:
                rect = pygame.Rect(x, y, 35, 35)
                pygame.gfxdraw.box(screen, rect, (20, 20, 50))

    # Efficient circle drawing
    for i in range(20):
        x = 50 + i * 35
        y = 300
        pygame.gfxdraw.filled_circle(screen, x, y, 15, (100 + i * 5, 0, 255 - i * 10))
        pygame.gfxdraw.aacircle(screen, x, y, 15, (255, 255, 255))

    # Fast line operations
    for i in range(0, 800, 10):
        pygame.gfxdraw.vline(screen, i, 500, 580, (0, i // 3, 100))

running = True
frame_count = 0
start_time = time.time()

while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    draw_optimized_scene()

    frame_count += 1
    if frame_count % 60 == 0:
        elapsed = time.time() - start_time
        fps = frame_count / elapsed
        print(f"FPS: {fps:.1f}")

    pygame.display.flip()
    clock.tick(60)

pygame.quit()

Performance Notes

Optimization Guidelines

# Use gfxdraw for high-performance scenarios
import pygame.gfxdraw

# Faster filled shapes
pygame.gfxdraw.box(surface, rect, color)           # Faster than pygame.draw.rect(surface, color, rect)
pygame.gfxdraw.filled_circle(surface, x, y, r, color)  # Faster than pygame.draw.circle(surface, color, (x, y), r)

# Antialiasing when quality matters
pygame.gfxdraw.aacircle(surface, x, y, r, color)   # Smooth edges, slightly slower
pygame.gfxdraw.aapolygon(surface, points, color)   # Professional quality graphics

# Pixel-level control for effects
pygame.gfxdraw.pixel(surface, x, y, color)         # Direct pixel access
pygame.gfxdraw.hline(surface, x1, x2, y, color)    # Optimized horizontal lines
pygame.gfxdraw.vline(surface, x, y1, y2, color)    # Optimized vertical lines

Memory and Speed Considerations

pygame.gfxdraw functions are generally faster than equivalent pygame.draw functions
Antialiased functions (aa*) provide better visual quality at slight performance cost
Use box() instead of rectangle() for filled shapes when possible
Pixel operations are efficient for effects but avoid for large areas
Bezier curves and textured polygons are computationally expensive
Batch similar operations together for better cache performance