1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
<html xmlns="http://www.w3.org/1999/xhtml">
6
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8
<title>pygame — Pygame v1.9.2 documentation</title>
9
<link rel="stylesheet" href="../_static/pygame.css" type="text/css" />
10
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
11
<script type="text/javascript">
12
var DOCUMENTATION_OPTIONS = {
15
COLLAPSE_INDEX: false,
20
<script type="text/javascript" src="../_static/jquery.js"></script>
21
<script type="text/javascript" src="../_static/underscore.js"></script>
22
<script type="text/javascript" src="../_static/doctools.js"></script>
23
<link rel="shortcut icon" href="../_static/pygame.ico"/>
24
<link rel="top" title="Pygame v1.9.2 documentation" href="../index.html" />
25
<link rel="next" title="pygame.Rect" href="rect.html" />
26
<link rel="prev" title="pygame.pixelcopy" href="pixelcopy.html" />
30
<div class="document">
36
<a href="http://www.pygame.org/">
37
<img src="../_static/pygame_tiny.png"/>
39
<h5>pygame documentation</h5>
41
<td class="pagelinks">
44
<a href="http://www.pygame.org/">Pygame Home</a> ||
45
<a href="../index.html">Help Contents</a> ||
46
<a href="../genindex.html">Reference Index</a> ||
49
<a href="camera.html">camera</a> ||
50
<a href="cdrom.html">cdrom</a> ||
51
<a href="color.html">Color</a> ||
52
<a href="cursors.html">cursors</a> ||
53
<a href="display.html">display</a> ||
54
<a href="draw.html">draw</a> ||
55
<a href="event.html">event</a> ||
56
<a href="examples.html">examples</a> ||
57
<a href="font.html">font</a> ||
58
<a href="freetype.html">freetype</a> ||
59
<a href="gfxdraw.html">gfxdraw</a> ||
60
<a href="image.html">image</a> ||
61
<a href="joystick.html">joystick</a> ||
62
<a href="key.html">key</a> ||
63
<a href="locals.html">locals</a> ||
64
<a href="mask.html">mask</a> ||
65
<a href="math.html">math</a> ||
66
<a href="midi.html">midi</a> ||
67
<a href="mixer.html">mixer</a> ||
68
<a href="mouse.html">mouse</a> ||
69
<a href="movie.html">movie</a> ||
70
<a href="music.html">music</a> ||
71
<a href="overlay.html">Overlay</a> ||
72
<a href="pixelarray.html">PixelArray</a> ||
73
<a href="pixelcopy.html">pixelcopy</a> ||
74
<a href="pygame.html">pygame</a> ||
75
<a href="rect.html">Rect</a> ||
76
<a href="scrap.html">scrap</a> ||
77
<a href="sndarray.html">sndarray</a> ||
78
<a href="sprite.html">sprite</a> ||
79
<a href="surface.html">Surface</a> ||
80
<a href="surfarray.html">surfarray</a> ||
81
<a href="tests.html">tests</a> ||
82
<a href="time.html">time</a> ||
83
<a href="transform.html">transform</a> ||
84
<a href="pygame.html#module-pygame.version">version</a>
91
<div class="documentwrapper">
94
<div class="sectionwrapper">
95
<div class="section" id="module-pygame">
96
<span id="pygame"></span><dl class="definition module">
97
<dt class="title module">
98
<tt class="docutils literal"><span class="pre">pygame</span></tt></dt>
99
<dd><div class="line-block">
100
<div class="line"><span class="summaryline">the top level pygame package</span></div>
102
<table border="1" class="toc docutils">
109
<tr><td><a class="toc reference external" href="pygame.html#pygame.init">pygame.init</a></td>
111
<td>initialize all imported pygame modules</td>
113
<tr><td><a class="toc reference external" href="pygame.html#pygame.quit">pygame.quit</a></td>
115
<td>uninitialize all pygame modules</td>
117
<tr><td><a class="toc reference external" href="pygame.html#pygame.error">pygame.error</a></td>
119
<td>standard pygame exception</td>
121
<tr><td><a class="toc reference external" href="pygame.html#pygame.get_error">pygame.get_error</a></td>
123
<td>get the current error message</td>
125
<tr><td><a class="toc reference external" href="pygame.html#pygame.set_error">pygame.set_error</a></td>
127
<td>set the current error message</td>
129
<tr><td><a class="toc reference external" href="pygame.html#pygame.get_sdl_version">pygame.get_sdl_version</a></td>
131
<td>get the version number of SDL</td>
133
<tr><td><a class="toc reference external" href="pygame.html#pygame.get_sdl_byteorder">pygame.get_sdl_byteorder</a></td>
135
<td>get the byte order of SDL</td>
137
<tr><td><a class="toc reference external" href="pygame.html#pygame.register_quit">pygame.register_quit</a></td>
139
<td>register a function to be called when pygame quits</td>
141
<tr><td><a class="toc reference external" href="pygame.html#pygame.encode_string">pygame.encode_string</a></td>
143
<td>Encode a unicode or bytes object</td>
145
<tr><td><a class="toc reference external" href="pygame.html#pygame.encode_file_path">pygame.encode_file_path</a></td>
147
<td>Encode a unicode or bytes object as a file system path</td>
151
<p>The pygame package represents the top-level package for others to use. Pygame
152
itself is broken into many submodules, but this does not affect programs that
154
<p>As a convenience, most of the top-level variables in pygame have been placed
155
inside a module named ‘pygame.locals’. This is meant to be used with ‘from
156
<a class="tooltip reference internal" href="locals.html#module-pygame.locals" title=""><tt class="xref py py-mod docutils literal"><span class="pre">pygame.locals</span></tt><span class="tooltip-content">pygame constants</span></a> import *’, in addition to ‘import pygame’.</p>
157
<p>When you ‘import pygame’ all available pygame submodules are automatically
158
imported. Be aware that some of the pygame modules are considered “optional”,
159
and may not be available. In that case, Pygame will provide a placeholder
160
object instead of the module, which can be used to test for availability.</p>
161
<dl class="definition function">
162
<dt class="title" id="pygame.init">
163
<tt class="descclassname">pygame.</tt><tt class="descname">init</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.init" title="Permalink to this definition">¶</a></dt>
164
<dd><div class="line-block">
165
<div class="line"><span class="summaryline">initialize all imported pygame modules</span></div>
166
<div class="line"><span class="signature">init() -> (numpass, numfail)</span></div>
168
<p>Initialize all imported Pygame modules. No exceptions will be raised if a
169
module fails, but the total number if successful and failed inits will be
170
returned as a tuple. You can always initialize individual modules manually,
171
but <a class="tooltip reference internal" href="#pygame.init" title=""><tt class="xref py py-func docutils literal"><span class="pre">pygame.init()</span></tt><span class="tooltip-content">initialize all imported pygame modules</span></a> is a convenient way to get everything started. The
172
<tt class="docutils literal"><span class="pre">init()</span></tt> functions for individual modules will raise exceptions when they
174
<p>You may want to initalise the different modules seperately to speed up your
175
program or to not use things your game does not.</p>
176
<p>It is safe to call this <tt class="docutils literal"><span class="pre">init()</span></tt> more than once: repeated calls will have
177
no effect. This is true even if you have <tt class="docutils literal"><span class="pre">pygame.quit()</span></tt> all the modules.</p>
180
<dl class="definition function">
181
<dt class="title" id="pygame.quit">
182
<tt class="descclassname">pygame.</tt><tt class="descname">quit</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.quit" title="Permalink to this definition">¶</a></dt>
183
<dd><div class="line-block">
184
<div class="line"><span class="summaryline">uninitialize all pygame modules</span></div>
185
<div class="line"><span class="signature">quit() -> None</span></div>
187
<p>Uninitialize all pygame modules that have previously been initialized. When
188
the Python interpreter shuts down, this method is called regardless, so your
189
program should not need it, except when it wants to terminate its pygame
190
resources and continue. It is safe to call this function more than once:
191
repeated calls have no effect.</p>
192
<p>Note, that <a class="tooltip reference internal" href="#pygame.quit" title=""><tt class="xref py py-func docutils literal"><span class="pre">pygame.quit()</span></tt><span class="tooltip-content">uninitialize all pygame modules</span></a> will not exit your program. Consider letting
193
your program end in the same way a normal python program will end.</p>
196
<dl class="definition exception">
197
<dt class="title" id="pygame.error">
198
<em class="property">exception </em><tt class="descclassname">pygame.</tt><tt class="descname">error</tt><a class="headerlink" href="#pygame.error" title="Permalink to this definition">¶</a></dt>
199
<dd><div class="line-block">
200
<div class="line"><span class="summaryline">standard pygame exception</span></div>
201
<div class="line"><span class="signature">raise pygame.error(message)</span></div>
203
<p>This exception is raised whenever a pygame or <tt class="docutils literal"><span class="pre">SDL</span></tt> operation fails. You
204
can catch any anticipated problems and deal with the error. The exception is
205
always raised with a descriptive message about the problem.</p>
206
<p>Derived from the RuntimeError exception, which can also be used to catch
207
these raised errors.</p>
210
<dl class="definition function">
211
<dt class="title" id="pygame.get_error">
212
<tt class="descclassname">pygame.</tt><tt class="descname">get_error</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.get_error" title="Permalink to this definition">¶</a></dt>
213
<dd><div class="line-block">
214
<div class="line"><span class="summaryline">get the current error message</span></div>
215
<div class="line"><span class="signature">get_error() -> errorstr</span></div>
217
<p><tt class="docutils literal"><span class="pre">SDL</span></tt> maintains an internal error message. This message will usually be
218
given to you when <a class="tooltip reference internal" href="#pygame.error" title=""><tt class="xref py py-func docutils literal"><span class="pre">pygame.error()</span></tt><span class="tooltip-content">standard pygame exception</span></a> is raised. You will rarely need to
219
call this function.</p>
222
<dl class="definition function">
223
<dt class="title" id="pygame.set_error">
224
<tt class="descclassname">pygame.</tt><tt class="descname">set_error</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.set_error" title="Permalink to this definition">¶</a></dt>
225
<dd><div class="line-block">
226
<div class="line"><span class="summaryline">set the current error message</span></div>
227
<div class="line"><span class="signature">set_error(error_msg) -> None</span></div>
229
<p><tt class="docutils literal"><span class="pre">SDL</span></tt> maintains an internal error message. This message will usually be
230
given to you when <a class="tooltip reference internal" href="#pygame.error" title=""><tt class="xref py py-func docutils literal"><span class="pre">pygame.error()</span></tt><span class="tooltip-content">standard pygame exception</span></a> is raised. You will rarely need to
231
call this function.</p>
234
<dl class="definition function">
235
<dt class="title" id="pygame.get_sdl_version">
236
<tt class="descclassname">pygame.</tt><tt class="descname">get_sdl_version</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.get_sdl_version" title="Permalink to this definition">¶</a></dt>
237
<dd><div class="line-block">
238
<div class="line"><span class="summaryline">get the version number of SDL</span></div>
239
<div class="line"><span class="signature">get_sdl_version() -> major, minor, patch</span></div>
241
<p>Returns the three version numbers of the <tt class="docutils literal"><span class="pre">SDL</span></tt> library. This version is
242
built at compile time. It can be used to detect which features may not be
243
available through Pygame.</p>
244
<p>get_sdl_version is new in pygame 1.7.0</p>
247
<dl class="definition function">
248
<dt class="title" id="pygame.get_sdl_byteorder">
249
<tt class="descclassname">pygame.</tt><tt class="descname">get_sdl_byteorder</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.get_sdl_byteorder" title="Permalink to this definition">¶</a></dt>
250
<dd><div class="line-block">
251
<div class="line"><span class="summaryline">get the byte order of SDL</span></div>
252
<div class="line"><span class="signature">get_sdl_byteorder() -> int</span></div>
254
<p>Returns the byte order of the <tt class="docutils literal"><span class="pre">SDL</span></tt> library. It returns <tt class="docutils literal"><span class="pre">LIL_ENDIAN</span></tt> for
255
little endian byte order and <tt class="docutils literal"><span class="pre">BIG_ENDIAN</span></tt> for big endian byte order.</p>
256
<p>get_sdl_byteorder is new in pygame 1.8</p>
259
<dl class="definition function">
260
<dt class="title" id="pygame.register_quit">
261
<tt class="descclassname">pygame.</tt><tt class="descname">register_quit</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.register_quit" title="Permalink to this definition">¶</a></dt>
262
<dd><div class="line-block">
263
<div class="line"><span class="summaryline">register a function to be called when pygame quits</span></div>
264
<div class="line"><span class="signature">register_quit(callable) -> None</span></div>
266
<p>When <a class="tooltip reference internal" href="#pygame.quit" title=""><tt class="xref py py-func docutils literal"><span class="pre">pygame.quit()</span></tt><span class="tooltip-content">uninitialize all pygame modules</span></a> is called, all registered quit functions are
267
called. Pygame modules do this automatically when they are initializing.
268
This function is not be needed for regular pygame users.</p>
271
<dl class="definition function">
272
<dt class="title" id="pygame.encode_string">
273
<tt class="descclassname">pygame.</tt><tt class="descname">encode_string</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.encode_string" title="Permalink to this definition">¶</a></dt>
274
<dd><div class="line-block">
275
<div class="line"><span class="summaryline">Encode a unicode or bytes object</span></div>
276
<div class="line"><span class="signature">encode_string([obj [, encoding [, errors [, etype]]]]) -> bytes or None</span></div>
278
<p>obj: If unicode, encode; if bytes, return unaltered; if anything else,
279
return None; if not given, raise SyntaxError.</p>
280
<p>encoding (string): If present, encoding to use. The default is
281
‘unicode_escape’.</p>
282
<p>errors (string): If given, how to handle unencodable characters. The default
283
is ‘backslashreplace’.</p>
284
<p>etype (exception type): If given, the exception type to raise for an
285
encoding error. The default is UnicodeEncodeError, as returned by
286
<tt class="docutils literal"><span class="pre">PyUnicode_AsEncodedString()</span></tt>. For the default encoding and errors values
287
there should be no encoding errors.</p>
288
<p>This function is used in encoding file paths. Keyword arguments are
290
<p>Added in Pygame 1.9.2 (primarily for use in unit tests)</p>
293
<dl class="definition function">
294
<dt class="title" id="pygame.encode_file_path">
295
<tt class="descclassname">pygame.</tt><tt class="descname">encode_file_path</tt><big>(</big><big>)</big><a class="headerlink" href="#pygame.encode_file_path" title="Permalink to this definition">¶</a></dt>
296
<dd><div class="line-block">
297
<div class="line"><span class="summaryline">Encode a unicode or bytes object as a file system path</span></div>
298
<div class="line"><span class="signature">encode_file_path([obj [, etype]]) -> bytes or None</span></div>
300
<p>obj: If unicode, encode; if bytes, return unaltered; if anything else,
301
return None; if not given, raise SyntaxError.</p>
302
<p>etype (exception type): If given, the exception type to raise for an
303
encoding error. The default is UnicodeEncodeError, as returned by
304
<tt class="docutils literal"><span class="pre">PyUnicode_AsEncodedString()</span></tt>.</p>
305
<p>This function is used to encode file paths in Pygame. Encoding is to the
306
codec as returned by <tt class="docutils literal"><span class="pre">sys.getfilesystemencoding()</span></tt>. Keyword arguments are
308
<p>Added in Pygame 1.9.2 (primarily for use in unit tests)</p>
314
<div class="section" id="module-pygame.version">
315
<span id="pygame-version"></span><dl class="definition module">
316
<dt class="title module">
317
<tt class="docutils literal"><span class="pre">pygame.version</span></tt></dt>
318
<dd><div class="line-block">
319
<div class="line"><span class="summaryline">small module containing version information</span></div>
321
<table border="1" class="toc docutils">
328
<tr><td><a class="toc reference external" href="pygame.html#pygame.version.ver">pygame.version.ver</a></td>
330
<td>version number as a string</td>
332
<tr><td><a class="toc reference external" href="pygame.html#pygame.version.vernum">pygame.version.vernum</a></td>
334
<td>tupled integers of the version</td>
338
<p>This module is automatically imported into the pygame package and offers a few
339
variables to check with version of pygame has been imported.</p>
340
<dl class="definition data">
341
<dt class="title" id="pygame.version.ver">
342
<tt class="descclassname">pygame.version.</tt><tt class="descname">ver</tt><a class="headerlink" href="#pygame.version.ver" title="Permalink to this definition">¶</a></dt>
343
<dd><div class="line-block">
344
<div class="line"><span class="summaryline">version number as a string</span></div>
345
<div class="line"><span class="signature">ver = ‘1.2’</span></div>
347
<p>This is the version represented as a string. It can contain a micro release
348
number as well, <tt class="docutils literal"><span class="pre">e.g.</span></tt>, ‘1.5.2’</p>
351
<dl class="definition data">
352
<dt class="title" id="pygame.version.vernum">
353
<tt class="descclassname">pygame.version.</tt><tt class="descname">vernum</tt><a class="headerlink" href="#pygame.version.vernum" title="Permalink to this definition">¶</a></dt>
354
<dd><div class="line-block">
355
<div class="line"><span class="summaryline">tupled integers of the version</span></div>
356
<div class="line"><span class="signature">vernum = (1, 5, 3)</span></div>
358
<p>This variable for the version can easily be compared with other version
359
numbers of the same format. An example of checking Pygame version numbers
360
would look like this:</p>
361
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">pygame</span><span class="o">.</span><span class="n">version</span><span class="o">.</span><span class="n">vernum</span> <span class="o"><</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">):</span>
362
<span class="k">print</span> <span class="s">'Warning, older version of Pygame (</span><span class="si">%s</span><span class="s">)'</span> <span class="o">%</span> <span class="n">pygame</span><span class="o">.</span><span class="n">version</span><span class="o">.</span><span class="n">ver</span>
363
<span class="n">disable_advanced_features</span> <span class="o">=</span> <span class="bp">True</span>
375
<div class="clearer"></div>
377
<div class="related">
380
<li class="right" style="margin-right: 10px">
381
<a href="../genindex.html" title="General Index"
382
accesskey="I">index</a></li>
384
<a href="rect.html" title="pygame.Rect"
385
accesskey="N">next</a> |</li>
387
<a href="pixelcopy.html" title="pygame.pixelcopy"
388
accesskey="P">previous</a> |</li>
389
<li><a href="../index.html">Pygame v1.9.2 documentation</a> »</li>
390
<script type="text/javascript" src="jquery.plugin.docscomments.js"></script>
395
© Copyright 2011, Pygame Developers.
b'\\ No newline at end of file'