sdl2 — SDL2 library wrapper¶
The sdl2 package is a ctypes -based wrapper around the SDL2 library. It wraps nearly all publicly accessible structures and functions of the SDL2 library to be accessible from Python code.
A detailed documentation about the behaviour of the different functions can found within the SDL2 documentation.
Usage¶
You can use sdl2 in nearly exactly the same way as you would do with the SDL library and C code.
A brief example in C code:
#include int main(int argc, char *argv[]) int running; SDL_Window *window; SDL_Surface *windowsurface; SDL_Surface *image; SDL_Event event; SDL_Init(SDL_INIT_VIDEO); window = SDL_CreateWindow("Hello World", SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED, 592, 460, SDL_WINDOW_SHOWN); windowsurface = SDL_GetWindowSurface(window); image = SDL_LoadBMP("exampleimage.bmp"); SDL_BlitSurface(image, NULL, windowsurface, NULL); SDL_UpdateWindowSurface(window); SDL_FreeSurface(image); running = 1; while (running) while (SDL_PollEvent(&event) != 0) if (event.type == SDL_QUIT) running = 0; break; > > > SDL_DestroyWindow(window); SDL_Quit(); return 0; >
import sys import ctypes from sdl2 import * def main(): SDL_Init(SDL_INIT_VIDEO) window = SDL_CreateWindow(b"Hello World", SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED, 592, 460, SDL_WINDOW_SHOWN) windowsurface = SDL_GetWindowSurface(window) image = SDL_LoadBMP(b"exampleimage.bmp") SDL_BlitSurface(image, None, windowsurface, None) SDL_UpdateWindowSurface(window) SDL_FreeSurface(image) running = True event = SDL_Event() while running: while SDL_PollEvent(ctypes.byref(event)) != 0: if event.type == SDL_QUIT: running = False break SDL_DestroyWindow(window) SDL_Quit() return 0 if __name__ == "__main__": sys.exit(main())
You can port code in a straightforward manner from one language to the other, though it is important to know about the limitations and slight differences mentioned below. Also, PySDL2 offers advanced functionality, which also feels more ‘pythonic’, via the sdl2.ext package.
Missing interfaces¶
The following functions, classes, constants and macros of SDL2 are not available within sdl2 .
- SDL_REVISION and SDL_REVISION_NUMBER from SDL_revision.h
- SDL_NAME() from SDL_name.h
- SDL_MostSignificantBitIndex32() and SDL_HasExactlyOneBitSet32 from SDL_bits.h
- Most functions from SDL2_stdinc.h (most are for math and string operations Python already has excellent built-in support for)
- Everything from SDL_main.h
- Everything from SDL_system.h
- Everything from SDL_assert.h
- Everything from SDL_thread.h
- Everything from SDL_atomic.h
- Everything from SDL_opengl.h (see PyOpenGL for a compatible OpenGL API)
- Everything from SDL_mutex.h
Additional interfaces¶
The following functions, classes, constants and macros are not part of SDL2, but were introduced by sdl2 .
Tuple containing all SDL2 pixel format constants (SDL_PIXELFORMAT_INDEX1LSB, …, SDL_PIXELFORMAT_RGB565, …).
Set containing all SDL2 audio format constants (AUDIO_U8, AUDIO_S8, … AUDIO_F32LSB, … ).
sdl2. rw_from_object ( obj : object ) → SDL_RWops¶
Creates a SDL_RWops from any Python object. The Python object must at least support the following methods:
length is the size in bytes to be read. A call to len(data) must return the correct amount of bytes for the data, so that len(data) / [size in bytes for a single element from data] returns the amount of elements. Must raise an error on failure.
- RW_SEEK_SET — move to offset from the start of the file
- RW_SEEK_CUR — move by offset from the relative location
- RW_SEEK_END — move to offset from the end of the file
Must return the current offset. This method must only be provided, if seek() does not return any value.
Writes the passed data(which is a string of bytes) to the object. Must raise an error on failure.
Note
The write() method is optional and only necessary, if the passed object should be able to write data.
The returned sdl2.SDL_RWops is a pure Python object and must not be freed via sdl2.SDL_FreeRW() .
© Copyright 2022, Marcus von Appen. Last updated: 2022-07-26 Revision 512eede7 .
Versions latest stable 0.9.13 0.9.11 0.9.10 rel_0_9_7 Downloads On Read the Docs Project Home Builds Free document hosting provided by Read the Docs.
sdl2 — SDL2 library wrapper¶
The sdl2 package is a ctypes -based wrapper around the SDL2 library. It wraps nearly all publicly accessible structures and functions of the SDL2 library to be accessible from Python code.
A detailed documentation about the behaviour of the different functions can found within the SDL2 documentation.
Usage¶
You can use sdl2 in nearly exactly the same way as you would do with the SDL library and C code.
A brief example in C code:
#include int main(int argc, char *argv[]) int running; SDL_Window *window; SDL_Surface *windowsurface; SDL_Surface *image; SDL_Event event; SDL_Init(SDL_INIT_VIDEO); window = SDL_CreateWindow("Hello World", SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED, 592, 460, SDL_WINDOW_SHOWN); windowsurface = SDL_GetWindowSurface(window); image = SDL_LoadBMP("exampleimage.bmp"); SDL_BlitSurface(image, NULL, windowsurface, NULL); SDL_UpdateWindowSurface(window); SDL_FreeSurface(image); running = 1; while (running) while (SDL_PollEvent(&event) != 0) if (event.type == SDL_QUIT) running = 0; break; > > > SDL_DestroyWindow(window); SDL_Quit(); return 0; >
import sys import ctypes from sdl2 import * def main(): SDL_Init(SDL_INIT_VIDEO) window = SDL_CreateWindow(b"Hello World", SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED, 592, 460, SDL_WINDOW_SHOWN) windowsurface = SDL_GetWindowSurface(window) image = SDL_LoadBMP(b"exampleimage.bmp") SDL_BlitSurface(image, None, windowsurface, None) SDL_UpdateWindowSurface(window) SDL_FreeSurface(image) running = True event = SDL_Event() while running: while SDL_PollEvent(ctypes.byref(event)) != 0: if event.type == SDL_QUIT: running = False break SDL_DestroyWindow(window) SDL_Quit() return 0 if __name__ == "__main__": sys.exit(main())
You can port code in a straightforward manner from one language to the other, though it is important to know about the limitations and slight differences mentioned below. Also, PySDL2 offers advanced functionality, which also feels more ‘pythonic’, via the sdl2.ext package.
Missing interfaces¶
The following functions, classes, constants and macros of SDL2 are not available within sdl2 .
- SDL_REVISION and SDL_REVISION_NUMBER from SDL_revision.h
- SDL_NAME() from SDL_name.h
- SDL_MostSignificantBitIndex32() and SDL_HasExactlyOneBitSet32 from SDL_bits.h
- Most functions from SDL2_stdinc.h (most are for math and string operations Python already has excellent built-in support for)
- Everything from SDL_main.h
- Everything from SDL_system.h
- Everything from SDL_assert.h
- Everything from SDL_thread.h
- Everything from SDL_atomic.h
- Everything from SDL_opengl.h (see PyOpenGL for a compatible OpenGL API)
- Everything from SDL_mutex.h
Additionally, SDL_GetJoystickGUIDInfo only functions properly in Python 3.7 and newer due to a ctypes bug. On older versions of Python, the function can be called but will have no effect.
Additional interfaces¶
The following functions, classes, constants and macros are not part of SDL2, but were introduced by sdl2 .
Tuple containing all SDL2 pixel format constants (SDL_PIXELFORMAT_INDEX1LSB, …, SDL_PIXELFORMAT_RGB565, …).
Set containing all SDL2 audio format constants (AUDIO_U8, AUDIO_S8, … AUDIO_F32LSB, … ).
sdl2. rw_from_object ( obj : object ) → SDL_RWops¶
Creates a SDL_RWops from any Python object. The Python object must at least support the following methods:
length is the size in bytes to be read. A call to len(data) must return the correct amount of bytes for the data, so that len(data) / [size in bytes for a single element from data] returns the amount of elements. Must raise an error on failure.
- RW_SEEK_SET — move to offset from the start of the file
- RW_SEEK_CUR — move by offset from the relative location
- RW_SEEK_END — move to offset from the end of the file
Must return the current offset. This method must only be provided, if seek() does not return any value.
Writes the passed data(which is a string of bytes) to the object. Must raise an error on failure.
Note
The write() method is optional and only necessary, if the passed object should be able to write data.
The returned sdl2.SDL_RWops is a pure Python object and must not be freed via sdl2.SDL_FreeRW() .
© Copyright 2023, Marcus von Appen. Last updated: 2023-06-28 Revision e5e6954c .
Versions latest stable 0.9.16 0.9.15 0.9.14 0.9.13 0.9.11 0.9.10 rel_0_9_7 Downloads On Read the Docs Project Home Builds Free document hosting provided by Read the Docs.
PySDL2
PySDL2 is a pure Python wrapper around the SDL2, SDL2_mixer, SDL2_image, SDL2_ttf, and SDL2_gfx libraries. Instead of relying on C code, it uses the built-in ctypes module to interface with SDL2, and provides simple Python classes and wrappers for common SDL2 functionality.
Installation
PySDL2 is easy to install and integrate within your own projects. To install or update to the latest version, simply run one of the following commands in a terminal:
pip install -U pysdl2 pip install -U git+https://github.com/py-sdl/py-sdl2.git Note: If installing on Python 3 on a computer where both Python 2 and 3 are installed, replace pip with pip3 in the above commands.
Requirements
In order for PySDL2 to work, the binaries for SDL2 (and any SDL2 addon modules you wish to use, e.g. SDL2_mixer) need to be installed on your system. On macOS, Windows, and most x86 and ARM64 distributions of Linux, the recommended way to install the SDL2 binaries is via the pysdl2-dll package using pip:
This will install pre-built binaries for all supported SDL2 libraries as a Python package, which PySDL2 will automatically load if available. On systems not supported by pysdl2-dll , you can install the SDL2 binaries using your system’s package manager (which may be out of date), or alternatively build and install the latest versions yourself from source.
The current minimum supported versions for each library are listed below:
- SDL2 >= 2.0.5
- SDL2_mixer >= 2.0.1 (for the sdl2.sdlmixer module)
- SDL2_ttf >= 2.0.14 (for the sdl2.sdlttf module)
- SDL2_image >= 2.0.1 (for the sdl2.sdlimage module)
- SDL2_gfx >= 1.0.3 (for the sdl2.sdlgfx module)
Documentation
If you just started with SDL and PySDL2, it is strongly recommended that you read through the tutorial of the documentation to learn the basics. You can find the documentation at doc/html or online at http://pysdl2.readthedocs.org.
License
This library is given to the public domain. There are no licensing restrictions. Please see doc/copying.rst for further details.