1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
.. module:: sdl2
:synopsis: SDL2 library wrapper
sdl2 - SDL2 library wrapper
===========================
The :mod:`sdl2` package is a :mod:`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
<http://wiki.libsdl.org/moin.cgi/CategoryAPI>`_.
Usage
-----
You can use :mod:`sdl2` in nearly exactly the same way as you would do with
the SDL library and C code.
.. highlight:: c
A brief example in C code::
#include <SDL.h>
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;
}
.. highlight:: python
Doing the same in Python: ::
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 :mod:`sdl2.ext` package.
Missing interfaces
------------------
The following functions, classes, constants and macros of SDL2 are *not*
available within :mod:`sdl2`.
* :c:data:`SDL_REVISION` and :c:data:`SDL_REVISION_NUMBER` from ``SDL_revision.h``
* :c:data:`SDL_NAME()` from ``SDL_name.h``
* :c:func:`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 :mod:`sdl2`.
.. data:: ALL_PIXELFORMATS
Tuple containing all SDL2 pixel format constants (SDL_PIXELFORMAT_INDEX1LSB,
..., SDL_PIXELFORMAT_RGB565, ...).
.. data:: AUDIO_FORMATS
Set containing all SDL2 audio format constants (AUDIO_U8, AUDIO_S8,
... AUDIO_F32LSB, ... ).
.. function:: 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:
read(length) -> data
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.
seek(offset, whence) -> int
offset denotes the offset to move the read/write pointer of the
object to. whence indicates the movement behaviour and can be one
of the following values:
* 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
If it could not move read/write pointer to the desired location,
an error must be raised.
tell() -> int
Must return the current offset. This method must only be
provided, if seek() does not return any value.
close() -> None
Closes the object(or its internal data access methods). Must raise
an error on failure.
write(data) -> None
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 :class:`sdl2.SDL_RWops` is a pure Python object and
**must not** be freed via :func:`sdl2.SDL_FreeRW()`.
|
