Using SDL-based packages in Pyodide

This is experimental

SDL support in Pyodide is experimental. Pyodide relies on undocumented behavior of Emscripten and SDL, so it may break or change in the future.

In addition, this feature requires to enable an opt-in flag, pyodide._api._skip_unwind_fatal_error = true; which can lead to stack unwinding issues (see Known issues).

Pyodide provides a way to use SDL-based packages in the browser, This document explains how to use SDL-based packages in Pyodide.

Setting canvas

Before using SDL-based packages, you need to set the canvas to draw on.

The canvas object must be a HTMLCanvasElement object, with the id attribute set to "canvas". For example, you can set a canvas like this:

let sdl2Canvas = document.createElement("canvas");
sdl2Canvas.id = "canvas";
pyodide.canvas.setCanvas2D(sdl2Canvas);

See also: pyodide.canvas

Working with infinite loop

It is common to use an infinite loop to draw animations or game scenes with SDL-based package.

For instance, a common code pattern in pygame (a SDL-based Python game library) is:

clock = pygame.time.Clock()
fps = 60
def run_game():
    while True:
        do_something()
        draw_canvas()
        clock.tick(fps)

However, in Pyodide, this will not work as expected, because the loop will block the main thread and prevent the browser from updating the canvas. To work around this, you need to use async functions and yield control to the browser.

import asyncio

async def run_game():
    while True:
        do_something()
        draw_canvas()
        await asyncio.sleep(1 / fps)

Using asyncio.sleep will yield control to the browser and allow the canvas to be updated.

Known issues

There is a known issue that with,

pyodide._api._skip_unwind_fatal_error = true;

Python call stacks are not being unwound after calling emscripten_set_main_loop().

see: pyodide#3697