added completly new version for haslach 2025
This commit is contained in:
fotobox
@@ -0,0 +1,274 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.BufferProxy — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.camera" href="camera.html" />
|
||||
<link rel="prev" title="Pygame Front Page" href="../index.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="pygame-bufferproxy">
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.BufferProxy">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">BufferProxy</span></span><a class="headerlink" href="#pygame.BufferProxy" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame object to export a surface buffer through an array protocol</span></div>
|
||||
<div class="line"><span class="signature">BufferProxy(<parent>) -> BufferProxy</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="bufferproxy.html#pygame.BufferProxy.parent">pygame.BufferProxy.parent</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Return wrapped exporting object.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="bufferproxy.html#pygame.BufferProxy.length">pygame.BufferProxy.length</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>The size, in bytes, of the exported buffer.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="bufferproxy.html#pygame.BufferProxy.raw">pygame.BufferProxy.raw</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>A copy of the exported buffer as a single block of bytes.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="bufferproxy.html#pygame.BufferProxy.write">pygame.BufferProxy.write</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Write raw bytes to object buffer.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p><a class="reference internal" href="#pygame.BufferProxy" title="pygame.BufferProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferProxy</span></code></a> is a pygame support type, designed as the return value
|
||||
of the <a class="reference internal" href="surface.html#pygame.Surface.get_buffer" title="pygame.Surface.get_buffer"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Surface.get_buffer()</span></code></a> and <a class="reference internal" href="surface.html#pygame.Surface.get_view" title="pygame.Surface.get_view"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Surface.get_view()</span></code></a> methods.
|
||||
For all Python versions a <a class="reference internal" href="#pygame.BufferProxy" title="pygame.BufferProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferProxy</span></code></a> object exports a C struct
|
||||
and Python level array interface on behalf of its parent object's buffer.
|
||||
A new buffer interface is also exported.
|
||||
In pygame, <a class="reference internal" href="#pygame.BufferProxy" title="pygame.BufferProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferProxy</span></code></a> is key to implementing the
|
||||
<a class="tooltip reference internal" href="surfarray.html#module-pygame.surfarray" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.surfarray</span></code><span class="tooltip-content">pygame module for accessing surface pixel data using array interfaces</span></a> module.</p>
|
||||
<p><a class="reference internal" href="#pygame.BufferProxy" title="pygame.BufferProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferProxy</span></code></a> instances can be created directly from Python code,
|
||||
either for a parent that exports an interface, or from a Python <code class="docutils literal notranslate"><span class="pre">dict</span></code>
|
||||
describing an object's buffer layout. The dict entries are based on the
|
||||
Python level array interface mapping. The following keys are recognized:</p>
|
||||
<blockquote>
|
||||
<div><dl class="simple">
|
||||
<dt><code class="docutils literal notranslate"><span class="pre">"shape"</span></code><span class="classifier">tuple</span></dt><dd><p>The length of each array dimension as a tuple of integers. The
|
||||
length of the tuple is the number of dimensions in the array.</p>
|
||||
</dd>
|
||||
<dt><code class="docutils literal notranslate"><span class="pre">"typestr"</span></code><span class="classifier">string</span></dt><dd><p>The array element type as a length 3 string. The first character
|
||||
gives byteorder, '<' for little-endian, '>' for big-endian, and
|
||||
'|' for not applicable. The second character is the element type,
|
||||
'i' for signed integer, 'u' for unsigned integer, 'f' for floating
|
||||
point, and 'V' for an chunk of bytes. The third character gives the
|
||||
bytesize of the element, from '1' to '9' bytes. So, for example,
|
||||
"<u4" is an unsigned 4 byte little-endian integer, such as a
|
||||
32 bit pixel on a PC, while "|V3" would represent a 24 bit pixel,
|
||||
which has no integer equivalent.</p>
|
||||
</dd>
|
||||
<dt><code class="docutils literal notranslate"><span class="pre">"data"</span></code><span class="classifier">tuple</span></dt><dd><p>The physical buffer start address and a read-only flag as a length
|
||||
2 tuple. The address is an integer value, while the read-only flag
|
||||
is a bool—<code class="docutils literal notranslate"><span class="pre">False</span></code> for writable, <code class="docutils literal notranslate"><span class="pre">True</span></code> for read-only.</p>
|
||||
</dd>
|
||||
<dt><code class="docutils literal notranslate"><span class="pre">"strides"</span></code><span class="classifier">tuple</span><span class="classifier">(optional)</span></dt><dd><p>Array stride information as a tuple of integers. It is required
|
||||
only of non C-contiguous arrays. The tuple length must match
|
||||
that of <code class="docutils literal notranslate"><span class="pre">"shape"</span></code>.</p>
|
||||
</dd>
|
||||
<dt><code class="docutils literal notranslate"><span class="pre">"parent"</span></code><span class="classifier">object</span><span class="classifier">(optional)</span></dt><dd><p>The exporting object. It can be used to keep the parent object
|
||||
alive while its buffer is visible.</p>
|
||||
</dd>
|
||||
<dt><code class="docutils literal notranslate"><span class="pre">"before"</span></code><span class="classifier">callable</span><span class="classifier">(optional)</span></dt><dd><p>Callback invoked when the <a class="reference internal" href="#pygame.BufferProxy" title="pygame.BufferProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferProxy</span></code></a> instance
|
||||
exports the buffer. The callback is given one argument, the
|
||||
<code class="docutils literal notranslate"><span class="pre">"parent"</span></code> object if given, otherwise <code class="docutils literal notranslate"><span class="pre">None</span></code>.
|
||||
The callback is useful for setting a lock on the parent.</p>
|
||||
</dd>
|
||||
<dt><code class="docutils literal notranslate"><span class="pre">"after"</span></code><span class="classifier">callable</span><span class="classifier">(optional)</span></dt><dd><p>Callback invoked when an exported buffer is released.
|
||||
The callback is passed on argument, the <code class="docutils literal notranslate"><span class="pre">"parent"</span></code> object if given,
|
||||
otherwise None. The callback is useful for releasing a lock on the
|
||||
parent.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</div></blockquote>
|
||||
<p>The BufferProxy class supports subclassing, instance variables, and weak
|
||||
references.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.0.</span></p>
|
||||
</div>
|
||||
<div class="versionextended">
|
||||
<p><span class="versionmodified extended">Extended in pygame 1.9.2.</span></p>
|
||||
</div>
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.BufferProxy.parent">
|
||||
<span class="sig-name descname"><span class="pre">parent</span></span><a class="headerlink" href="#pygame.BufferProxy.parent" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Return wrapped exporting object.</span></div>
|
||||
<div class="line"><span class="signature">parent -> Surface</span></div>
|
||||
<div class="line"><span class="signature">parent -> <parent></span></div>
|
||||
</div>
|
||||
<p>The <a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><code class="xref py py-class docutils literal notranslate"><span class="pre">Surface</span></code></a> which returned the <a class="reference internal" href="#pygame.BufferProxy" title="pygame.BufferProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferProxy</span></code></a> object or
|
||||
the object passed to a <a class="reference internal" href="#pygame.BufferProxy" title="pygame.BufferProxy"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferProxy</span></code></a> call.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.BufferProxy.length">
|
||||
<span class="sig-name descname"><span class="pre">length</span></span><a class="headerlink" href="#pygame.BufferProxy.length" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">The size, in bytes, of the exported buffer.</span></div>
|
||||
<div class="line"><span class="signature">length -> int</span></div>
|
||||
</div>
|
||||
<p>The number of valid bytes of data exported. For discontinuous data,
|
||||
that is data which is not a single block of memory, the bytes within
|
||||
the gaps are excluded from the count. This property is equivalent to
|
||||
the <code class="docutils literal notranslate"><span class="pre">Py_buffer</span></code> C struct <code class="docutils literal notranslate"><span class="pre">len</span></code> field.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.BufferProxy.raw">
|
||||
<span class="sig-name descname"><span class="pre">raw</span></span><a class="headerlink" href="#pygame.BufferProxy.raw" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">A copy of the exported buffer as a single block of bytes.</span></div>
|
||||
<div class="line"><span class="signature">raw -> bytes</span></div>
|
||||
</div>
|
||||
<p>The buffer data as a <code class="docutils literal notranslate"><span class="pre">str</span></code>/<code class="docutils literal notranslate"><span class="pre">bytes</span></code> object.
|
||||
Any gaps in the exported data are removed.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.BufferProxy.write">
|
||||
<span class="sig-name descname"><span class="pre">write</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.BufferProxy.write" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Write raw bytes to object buffer.</span></div>
|
||||
<div class="line"><span class="signature">write(buffer, offset=0)</span></div>
|
||||
</div>
|
||||
<p>Overwrite bytes in the parent object's data. The data must be C or F
|
||||
contiguous, otherwise a ValueError is raised. Argument <cite>buffer</cite> is a
|
||||
<code class="docutils literal notranslate"><span class="pre">str</span></code>/<code class="docutils literal notranslate"><span class="pre">bytes</span></code> object. An optional offset gives a
|
||||
start position, in bytes, within the buffer where overwriting begins.
|
||||
If the offset is negative or greater that or equal to the buffer proxy's
|
||||
<a class="reference internal" href="#pygame.BufferProxy.length" title="pygame.BufferProxy.length"><code class="xref py py-attr docutils literal notranslate"><span class="pre">length</span></code></a> value, an <code class="docutils literal notranslate"><span class="pre">IndexException</span></code> is raised.
|
||||
If <code class="docutils literal notranslate"><span class="pre">len(buffer)</span> <span class="pre">></span> <span class="pre">proxy.length</span> <span class="pre">+</span> <span class="pre">offset</span></code>, a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is raised.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/bufferproxy.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="camera.html" title="pygame.camera"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="../index.html" title="Pygame Front Page"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.BufferProxy</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,458 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.camera — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.cdrom" href="cdrom.html" />
|
||||
<link rel="prev" title="pygame.BufferProxy" href="bufferproxy.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.camera">
|
||||
<span id="pygame-camera"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.camera</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for camera use</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.init">pygame.camera.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Module init</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.get_backends">pygame.camera.get_backends</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Get the backends supported on this system</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.colorspace">pygame.camera.colorspace</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Surface colorspace conversion</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.list_cameras">pygame.camera.list_cameras</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns a list of available cameras</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera">pygame.camera.Camera</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>load a camera</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Pygame currently supports Linux (V4L2) and Windows (MSMF) cameras natively,
|
||||
with wider platform support available via an integrated OpenCV backend.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.2: </span>Windows native camera support</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.3: </span>New OpenCV backends</p>
|
||||
</div>
|
||||
<p>EXPERIMENTAL!: This API may change or disappear in later pygame releases. If
|
||||
you use this, your code will very likely break with the next pygame release.</p>
|
||||
<p>The Bayer to <code class="docutils literal notranslate"><span class="pre">RGB</span></code> function is based on:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Sonix SN9C101 based webcam basic I/F routines
|
||||
Copyright (C) 2004 Takafumi Mizuno <taka-qce@ls-a.jp>
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions
|
||||
are met:
|
||||
1. Redistributions of source code must retain the above copyright
|
||||
notice, this list of conditions and the following disclaimer.
|
||||
2. Redistributions in binary form must reproduce the above copyright
|
||||
notice, this list of conditions and the following disclaimer in the
|
||||
documentation and/or other materials provided with the distribution.
|
||||
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
SUCH DAMAGE.
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>New in pygame 1.9.0.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.camera.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Module init</span></div>
|
||||
<div class="line"><span class="signature">init(backend = None) -> None</span></div>
|
||||
</div>
|
||||
<p>This function starts up the camera module, choosing the best webcam backend
|
||||
it can find for your system. This is not guaranteed to succeed, and may even
|
||||
attempt to import third party modules, like <cite>OpenCV</cite>. If you want to
|
||||
override its backend choice, you can call pass the name of the backend you
|
||||
want into this function. More about backends in
|
||||
<a class="reference internal" href="#pygame.camera.get_backends" title="pygame.camera.get_backends"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_backends()</span></code></a>.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.3: </span>Option to explicitly select backend</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.get_backends">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.camera.</span></span><span class="sig-name descname"><span class="pre">get_backends</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.get_backends" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Get the backends supported on this system</span></div>
|
||||
<div class="line"><span class="signature">get_backends() -> [str]</span></div>
|
||||
</div>
|
||||
<p>This function returns every backend it thinks has a possibility of working
|
||||
on your system, in order of priority.</p>
|
||||
<p>pygame.camera Backends:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Backend OS Description
|
||||
---------------------------------------------------------------------------------
|
||||
_camera (MSMF) Windows Builtin, works on Windows 8+ Python3
|
||||
_camera (V4L2) Linux Builtin
|
||||
OpenCV Any Uses `opencv-python` module, can't enumerate cameras
|
||||
OpenCV-Mac Mac Same as OpenCV, but has camera enumeration
|
||||
VideoCapture Windows Uses abandoned `VideoCapture` module, can't enumerate
|
||||
cameras, may be removed in the future
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>There are two main differences among backends.</p>
|
||||
<p>The _camera backends are built in to pygame itself, and require no third
|
||||
party imports. All the other backends do. For the OpenCV and VideoCapture
|
||||
backends, those modules need to be installed on your system.</p>
|
||||
<p>The other big difference is "camera enumeration." Some backends don't have
|
||||
a way to list out camera names, or even the number of cameras on the
|
||||
system. In these cases, <a class="reference internal" href="#pygame.camera.list_cameras" title="pygame.camera.list_cameras"><code class="xref py py-func docutils literal notranslate"><span class="pre">list_cameras()</span></code></a> will return
|
||||
something like <code class="docutils literal notranslate"><span class="pre">[0]</span></code>. If you know you have multiple cameras on the
|
||||
system, these backend ports will pass through a "camera index number"
|
||||
through if you use that as the <code class="docutils literal notranslate"><span class="pre">device</span></code> parameter.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.colorspace">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.camera.</span></span><span class="sig-name descname"><span class="pre">colorspace</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.colorspace" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Surface colorspace conversion</span></div>
|
||||
<div class="line"><span class="signature">colorspace(Surface, format, DestSurface = None) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Allows for conversion from "RGB" to a destination colorspace of "HSV" or
|
||||
"YUV". The source and destination surfaces must be the same size and pixel
|
||||
depth. This is useful for computer vision on devices with limited processing
|
||||
power. Capture as small of an image as possible, <code class="docutils literal notranslate"><span class="pre">transform.scale()</span></code> it
|
||||
even smaller, and then convert the colorspace to <code class="docutils literal notranslate"><span class="pre">YUV</span></code> or <code class="docutils literal notranslate"><span class="pre">HSV</span></code> before
|
||||
doing any processing on it.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.list_cameras">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.camera.</span></span><span class="sig-name descname"><span class="pre">list_cameras</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.list_cameras" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns a list of available cameras</span></div>
|
||||
<div class="line"><span class="signature">list_cameras() -> [cameras]</span></div>
|
||||
</div>
|
||||
<p>Checks the computer for available cameras and returns a list of strings of
|
||||
camera names, ready to be fed into <a class="tooltip reference internal" href="#pygame.camera.Camera" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.camera.Camera</span></code><span class="tooltip-content">load a camera</span></a>.</p>
|
||||
<p>If the camera backend doesn't support webcam enumeration, this will return
|
||||
something like <code class="docutils literal notranslate"><span class="pre">[0]</span></code>. See <a class="reference internal" href="#pygame.camera.get_backends" title="pygame.camera.get_backends"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_backends()</span></code></a> for much more
|
||||
information.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.camera.</span></span><span class="sig-name descname"><span class="pre">Camera</span></span><a class="headerlink" href="#pygame.camera.Camera" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">load a camera</span></div>
|
||||
<div class="line"><span class="signature">Camera(device, (width, height), format) -> Camera</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera.start">pygame.camera.Camera.start</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>opens, initializes, and starts capturing</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera.stop">pygame.camera.Camera.stop</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stops, uninitializes, and closes the camera</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera.get_controls">pygame.camera.Camera.get_controls</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>gets current values of user controls</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera.set_controls">pygame.camera.Camera.set_controls</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>changes camera settings if supported by the camera</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera.get_size">pygame.camera.Camera.get_size</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns the dimensions of the images being recorded</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera.query_image">pygame.camera.Camera.query_image</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>checks if a frame is ready</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera.get_image">pygame.camera.Camera.get_image</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>captures an image as a Surface</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="camera.html#pygame.camera.Camera.get_raw">pygame.camera.Camera.get_raw</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns an unmodified image as bytes</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Loads a camera. On Linux, the device is typically something like
|
||||
"/dev/video0". Default width and height are 640 by 480.
|
||||
Format is the desired colorspace of the output.
|
||||
This is useful for computer vision purposes. The default is
|
||||
<code class="docutils literal notranslate"><span class="pre">RGB</span></code>. The following are supported:</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGB</span></code> - Red, Green, Blue</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">YUV</span></code> - Luma, Blue Chrominance, Red Chrominance</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">HSV</span></code> - Hue, Saturation, Value</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera.start">
|
||||
<span class="sig-name descname"><span class="pre">start</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.Camera.start" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">opens, initializes, and starts capturing</span></div>
|
||||
<div class="line"><span class="signature">start() -> None</span></div>
|
||||
</div>
|
||||
<p>Opens the camera device, attempts to initialize it, and begins recording
|
||||
images to a buffer. The camera must be started before any of the below
|
||||
functions can be used.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera.stop">
|
||||
<span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.Camera.stop" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stops, uninitializes, and closes the camera</span></div>
|
||||
<div class="line"><span class="signature">stop() -> None</span></div>
|
||||
</div>
|
||||
<p>Stops recording, uninitializes the camera, and closes it. Once a camera
|
||||
is stopped, the below functions cannot be used until it is started again.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera.get_controls">
|
||||
<span class="sig-name descname"><span class="pre">get_controls</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.Camera.get_controls" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">gets current values of user controls</span></div>
|
||||
<div class="line"><span class="signature">get_controls() -> (hflip = bool, vflip = bool, brightness)</span></div>
|
||||
</div>
|
||||
<p>If the camera supports it, get_controls will return the current settings
|
||||
for horizontal and vertical image flip as bools and brightness as an int.
|
||||
If unsupported, it will return the default values of (0, 0, 0). Note that
|
||||
the return values here may be different than those returned by
|
||||
set_controls, though these are more likely to be correct.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera.set_controls">
|
||||
<span class="sig-name descname"><span class="pre">set_controls</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.Camera.set_controls" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">changes camera settings if supported by the camera</span></div>
|
||||
<div class="line"><span class="signature">set_controls(hflip = bool, vflip = bool, brightness) -> (hflip = bool, vflip = bool, brightness)</span></div>
|
||||
</div>
|
||||
<p>Allows you to change camera settings if the camera supports it. The
|
||||
return values will be the input values if the camera claims it succeeded
|
||||
or the values previously in use if not. Each argument is optional, and
|
||||
the desired one can be chosen by supplying the keyword, like hflip. Note
|
||||
that the actual settings being used by the camera may not be the same as
|
||||
those returned by set_controls. On Windows, <code class="code docutils literal notranslate"><span class="pre">hflip</span></code> and <code class="code docutils literal notranslate"><span class="pre">vflip</span></code> are
|
||||
implemented by pygame, not by the Camera, so they should always work, but
|
||||
<code class="code docutils literal notranslate"><span class="pre">brightness</span></code> is unsupported.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera.get_size">
|
||||
<span class="sig-name descname"><span class="pre">get_size</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.Camera.get_size" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns the dimensions of the images being recorded</span></div>
|
||||
<div class="line"><span class="signature">get_size() -> (width, height)</span></div>
|
||||
</div>
|
||||
<p>Returns the current dimensions of the images being captured by the
|
||||
camera. This will return the actual size, which may be different than the
|
||||
one specified during initialization if the camera did not support that
|
||||
size.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera.query_image">
|
||||
<span class="sig-name descname"><span class="pre">query_image</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.Camera.query_image" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">checks if a frame is ready</span></div>
|
||||
<div class="line"><span class="signature">query_image() -> bool</span></div>
|
||||
</div>
|
||||
<p>If an image is ready to get, it returns true. Otherwise it returns false.
|
||||
Note that some webcams will always return False and will only queue a
|
||||
frame when called with a blocking function like <a class="reference internal" href="#pygame.camera.Camera.get_image" title="pygame.camera.Camera.get_image"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_image()</span></code></a>.
|
||||
On Windows (MSMF), and the OpenCV backends, <a class="reference internal" href="#pygame.camera.Camera.query_image" title="pygame.camera.Camera.query_image"><code class="xref py py-func docutils literal notranslate"><span class="pre">query_image()</span></code></a>
|
||||
should be reliable, though. This is useful to separate the framerate of
|
||||
the game from that of the camera without having to use threading.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera.get_image">
|
||||
<span class="sig-name descname"><span class="pre">get_image</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.Camera.get_image" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">captures an image as a Surface</span></div>
|
||||
<div class="line"><span class="signature">get_image(Surface = None) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Pulls an image off of the buffer as an <code class="docutils literal notranslate"><span class="pre">RGB</span></code> Surface. It can optionally
|
||||
reuse an existing Surface to save time. The bit-depth of the surface is
|
||||
24 bits on Linux, 32 bits on Windows, or the same as the optionally
|
||||
supplied Surface.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.camera.Camera.get_raw">
|
||||
<span class="sig-name descname"><span class="pre">get_raw</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.camera.Camera.get_raw" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns an unmodified image as bytes</span></div>
|
||||
<div class="line"><span class="signature">get_raw() -> bytes</span></div>
|
||||
</div>
|
||||
<p>Gets an image from a camera as a string in the native pixelformat of the
|
||||
camera. Useful for integration with other libraries. This returns a
|
||||
bytes object</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/camera.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="cdrom.html" title="pygame.cdrom"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="bufferproxy.html" title="pygame.BufferProxy"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.camera</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,578 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.cdrom — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.Color" href="color.html" />
|
||||
<link rel="prev" title="pygame.camera" href="camera.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.cdrom">
|
||||
<span id="pygame-cdrom"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.cdrom</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for audio cdrom control</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.init">pygame.cdrom.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>initialize the cdrom module</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.quit">pygame.cdrom.quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>uninitialize the cdrom module</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.get_init">pygame.cdrom.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>true if the cdrom module is initialized</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.get_count">pygame.cdrom.get_count</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>number of cd drives on the system</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD">pygame.cdrom.CD</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>class to manage a cdrom drive</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>This module is non functional in pygame 2.0 and above, unless you have manually compiled pygame with SDL1.
|
||||
This module will not be supported in the future.
|
||||
One alternative for python cdrom functionality is <a class="reference external" href="https://pypi.org/project/pycdio/">pycdio</a>.</p>
|
||||
</div>
|
||||
<p>The cdrom module manages the <code class="docutils literal notranslate"><span class="pre">CD</span></code> and <code class="docutils literal notranslate"><span class="pre">DVD</span></code> drives on a computer. It can
|
||||
also control the playback of audio CDs. This module needs to be initialized
|
||||
before it can do anything. Each <code class="docutils literal notranslate"><span class="pre">CD</span></code> object you create represents a cdrom
|
||||
drive and must also be initialized individually before it can do most things.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.cdrom.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">initialize the cdrom module</span></div>
|
||||
<div class="line"><span class="signature">init() -> None</span></div>
|
||||
</div>
|
||||
<p>Initialize the cdrom module. This will scan the system for all <code class="docutils literal notranslate"><span class="pre">CD</span></code>
|
||||
devices. The module must be initialized before any other functions will
|
||||
work. This automatically happens when you call <code class="docutils literal notranslate"><span class="pre">pygame.init()</span></code>.</p>
|
||||
<p>It is safe to call this function more than once.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.quit">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.cdrom.</span></span><span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">uninitialize the cdrom module</span></div>
|
||||
<div class="line"><span class="signature">quit() -> None</span></div>
|
||||
</div>
|
||||
<p>Uninitialize the cdrom module. After you call this any existing <code class="docutils literal notranslate"><span class="pre">CD</span></code>
|
||||
objects will no longer work.</p>
|
||||
<p>It is safe to call this function more than once.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.get_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.cdrom.</span></span><span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">true if the cdrom module is initialized</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Test if the cdrom module is initialized or not. This is different than the
|
||||
<code class="docutils literal notranslate"><span class="pre">CD.init()</span></code> since each drive must also be initialized individually.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.get_count">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.cdrom.</span></span><span class="sig-name descname"><span class="pre">get_count</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.get_count" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">number of cd drives on the system</span></div>
|
||||
<div class="line"><span class="signature">get_count() -> count</span></div>
|
||||
</div>
|
||||
<p>Return the number of cd drives on the system. When you create <code class="docutils literal notranslate"><span class="pre">CD</span></code> objects
|
||||
you need to pass an integer id that must be lower than this count. The count
|
||||
will be 0 if there are no drives on the system.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.cdrom.</span></span><span class="sig-name descname"><span class="pre">CD</span></span><a class="headerlink" href="#pygame.cdrom.CD" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">class to manage a cdrom drive</span></div>
|
||||
<div class="line"><span class="signature">CD(id) -> CD</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.init">pygame.cdrom.CD.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>initialize a cdrom drive for use</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.quit">pygame.cdrom.CD.quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>uninitialize a cdrom drive for use</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_init">pygame.cdrom.CD.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>true if this cd device initialized</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.play">pygame.cdrom.CD.play</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>start playing audio</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.stop">pygame.cdrom.CD.stop</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop audio playback</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.pause">pygame.cdrom.CD.pause</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>temporarily stop audio playback</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.resume">pygame.cdrom.CD.resume</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>unpause audio playback</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.eject">pygame.cdrom.CD.eject</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>eject or open the cdrom drive</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_id">pygame.cdrom.CD.get_id</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>the index of the cdrom drive</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_name">pygame.cdrom.CD.get_name</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>the system name of the cdrom drive</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_busy">pygame.cdrom.CD.get_busy</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>true if the drive is playing audio</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_paused">pygame.cdrom.CD.get_paused</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>true if the drive is paused</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_current">pygame.cdrom.CD.get_current</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>the current audio playback position</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_empty">pygame.cdrom.CD.get_empty</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>False if a cdrom is in the drive</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_numtracks">pygame.cdrom.CD.get_numtracks</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>the number of tracks on the cdrom</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_track_audio">pygame.cdrom.CD.get_track_audio</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>true if the cdrom track has audio data</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_all">pygame.cdrom.CD.get_all</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get all track information</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_track_start">pygame.cdrom.CD.get_track_start</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>start time of a cdrom track</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cdrom.html#pygame.cdrom.CD.get_track_length">pygame.cdrom.CD.get_track_length</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>length of a cdrom track</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>You can create a <code class="docutils literal notranslate"><span class="pre">CD</span></code> object for each cdrom on the system. Use
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.cdrom.get_count()</span></code> to determine how many drives actually exist.
|
||||
The id argument is an integer of the drive, starting at zero.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">CD</span></code> object is not initialized, you can only call <code class="docutils literal notranslate"><span class="pre">CD.get_id()</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">CD.get_name()</span></code> on an uninitialized drive.</p>
|
||||
<p>It is safe to create multiple <code class="docutils literal notranslate"><span class="pre">CD</span></code> objects for the same drive, they will
|
||||
all cooperate normally.</p>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.init">
|
||||
<span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">initialize a cdrom drive for use</span></div>
|
||||
<div class="line"><span class="signature">init() -> None</span></div>
|
||||
</div>
|
||||
<p>Initialize the cdrom drive for use. The drive must be initialized for
|
||||
most <code class="docutils literal notranslate"><span class="pre">CD</span></code> methods to work. Even if the rest of pygame has been
|
||||
initialized.</p>
|
||||
<p>There may be a brief pause while the drive is initialized. Avoid
|
||||
<code class="docutils literal notranslate"><span class="pre">CD.init()</span></code> if the program should not stop for a second or two.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.quit">
|
||||
<span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">uninitialize a cdrom drive for use</span></div>
|
||||
<div class="line"><span class="signature">quit() -> None</span></div>
|
||||
</div>
|
||||
<p>Uninitialize a drive for use. Call this when your program will not be
|
||||
accessing the drive for awhile.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_init">
|
||||
<span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">true if this cd device initialized</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Test if this <code class="docutils literal notranslate"><span class="pre">CDROM</span></code> device is initialized. This is different than the
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.cdrom.init()</span></code> since each drive must also be initialized
|
||||
individually.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.play">
|
||||
<span class="sig-name descname"><span class="pre">play</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.play" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">start playing audio</span></div>
|
||||
<div class="line"><span class="signature">play(track, start=None, end=None) -> None</span></div>
|
||||
</div>
|
||||
<p>Playback audio from an audio cdrom in the drive. Besides the track number
|
||||
argument, you can also pass a starting and ending time for playback. The
|
||||
start and end time are in seconds, and can limit the section of an audio
|
||||
track played.</p>
|
||||
<p>If you pass a start time but no end, the audio will play to the end of
|
||||
the track. If you pass a start time and 'None' for the end time, the
|
||||
audio will play to the end of the entire disc.</p>
|
||||
<p>See the <code class="docutils literal notranslate"><span class="pre">CD.get_numtracks()</span></code> and <code class="docutils literal notranslate"><span class="pre">CD.get_track_audio()</span></code> to find
|
||||
tracks to playback.</p>
|
||||
<p>Note, track 0 is the first track on the <code class="docutils literal notranslate"><span class="pre">CD</span></code>. Track numbers start at
|
||||
zero.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.stop">
|
||||
<span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.stop" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop audio playback</span></div>
|
||||
<div class="line"><span class="signature">stop() -> None</span></div>
|
||||
</div>
|
||||
<p>Stops playback of audio from the cdrom. This will also lose the current
|
||||
playback position. This method does nothing if the drive isn't already
|
||||
playing audio.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.pause">
|
||||
<span class="sig-name descname"><span class="pre">pause</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.pause" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">temporarily stop audio playback</span></div>
|
||||
<div class="line"><span class="signature">pause() -> None</span></div>
|
||||
</div>
|
||||
<p>Temporarily stop audio playback on the <code class="docutils literal notranslate"><span class="pre">CD</span></code>. The playback can be
|
||||
resumed at the same point with the <code class="docutils literal notranslate"><span class="pre">CD.resume()</span></code> method. If the <code class="docutils literal notranslate"><span class="pre">CD</span></code>
|
||||
is not playing this method does nothing.</p>
|
||||
<p>Note, track 0 is the first track on the <code class="docutils literal notranslate"><span class="pre">CD</span></code>. Track numbers start at
|
||||
zero.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.resume">
|
||||
<span class="sig-name descname"><span class="pre">resume</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.resume" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">unpause audio playback</span></div>
|
||||
<div class="line"><span class="signature">resume() -> None</span></div>
|
||||
</div>
|
||||
<p>Unpause a paused <code class="docutils literal notranslate"><span class="pre">CD</span></code>. If the <code class="docutils literal notranslate"><span class="pre">CD</span></code> is not paused or already playing,
|
||||
this method does nothing.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.eject">
|
||||
<span class="sig-name descname"><span class="pre">eject</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.eject" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">eject or open the cdrom drive</span></div>
|
||||
<div class="line"><span class="signature">eject() -> None</span></div>
|
||||
</div>
|
||||
<p>This will open the cdrom drive and eject the cdrom. If the drive is
|
||||
playing or paused it will be stopped.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_id">
|
||||
<span class="sig-name descname"><span class="pre">get_id</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_id" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">the index of the cdrom drive</span></div>
|
||||
<div class="line"><span class="signature">get_id() -> id</span></div>
|
||||
</div>
|
||||
<p>Returns the integer id that was used to create the <code class="docutils literal notranslate"><span class="pre">CD</span></code> instance. This
|
||||
method can work on an uninitialized <code class="docutils literal notranslate"><span class="pre">CD</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_name">
|
||||
<span class="sig-name descname"><span class="pre">get_name</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_name" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">the system name of the cdrom drive</span></div>
|
||||
<div class="line"><span class="signature">get_name() -> name</span></div>
|
||||
</div>
|
||||
<p>Return the string name of the drive. This is the system name used to
|
||||
represent the drive. It is often the drive letter or device name. This
|
||||
method can work on an uninitialized <code class="docutils literal notranslate"><span class="pre">CD</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_busy">
|
||||
<span class="sig-name descname"><span class="pre">get_busy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_busy" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">true if the drive is playing audio</span></div>
|
||||
<div class="line"><span class="signature">get_busy() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns True if the drive busy playing back audio.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_paused">
|
||||
<span class="sig-name descname"><span class="pre">get_paused</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_paused" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">true if the drive is paused</span></div>
|
||||
<div class="line"><span class="signature">get_paused() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns True if the drive is currently paused.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_current">
|
||||
<span class="sig-name descname"><span class="pre">get_current</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_current" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">the current audio playback position</span></div>
|
||||
<div class="line"><span class="signature">get_current() -> track, seconds</span></div>
|
||||
</div>
|
||||
<p>Returns both the current track and time of that track. This method works
|
||||
when the drive is either playing or paused.</p>
|
||||
<p>Note, track 0 is the first track on the <code class="docutils literal notranslate"><span class="pre">CD</span></code>. Track numbers start at
|
||||
zero.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_empty">
|
||||
<span class="sig-name descname"><span class="pre">get_empty</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_empty" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">False if a cdrom is in the drive</span></div>
|
||||
<div class="line"><span class="signature">get_empty() -> bool</span></div>
|
||||
</div>
|
||||
<p>Return False if there is a cdrom currently in the drive. If the drive is
|
||||
empty this will return True.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_numtracks">
|
||||
<span class="sig-name descname"><span class="pre">get_numtracks</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_numtracks" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">the number of tracks on the cdrom</span></div>
|
||||
<div class="line"><span class="signature">get_numtracks() -> count</span></div>
|
||||
</div>
|
||||
<p>Return the number of tracks on the cdrom in the drive. This will return
|
||||
zero of the drive is empty or has no tracks.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_track_audio">
|
||||
<span class="sig-name descname"><span class="pre">get_track_audio</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_track_audio" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">true if the cdrom track has audio data</span></div>
|
||||
<div class="line"><span class="signature">get_track_audio(track) -> bool</span></div>
|
||||
</div>
|
||||
<p>Determine if a track on a cdrom contains audio data. You can also call
|
||||
<code class="docutils literal notranslate"><span class="pre">CD.num_tracks()</span></code> and <code class="docutils literal notranslate"><span class="pre">CD.get_all()</span></code> to determine more information
|
||||
about the cdrom.</p>
|
||||
<p>Note, track 0 is the first track on the <code class="docutils literal notranslate"><span class="pre">CD</span></code>. Track numbers start at
|
||||
zero.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_all">
|
||||
<span class="sig-name descname"><span class="pre">get_all</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_all" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get all track information</span></div>
|
||||
<div class="line"><span class="signature">get_all() -> [(audio, start, end, length), ...]</span></div>
|
||||
</div>
|
||||
<p>Return a list with information for every track on the cdrom. The
|
||||
information consists of a tuple with four values. The audio value is True
|
||||
if the track contains audio data. The start, end, and length values are
|
||||
floating point numbers in seconds. Start and end represent absolute times
|
||||
on the entire disc.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_track_start">
|
||||
<span class="sig-name descname"><span class="pre">get_track_start</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_track_start" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">start time of a cdrom track</span></div>
|
||||
<div class="line"><span class="signature">get_track_start(track) -> seconds</span></div>
|
||||
</div>
|
||||
<p>Return the absolute time in seconds where at start of the cdrom track.</p>
|
||||
<p>Note, track 0 is the first track on the <code class="docutils literal notranslate"><span class="pre">CD</span></code>. Track numbers start at
|
||||
zero.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cdrom.CD.get_track_length">
|
||||
<span class="sig-name descname"><span class="pre">get_track_length</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cdrom.CD.get_track_length" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">length of a cdrom track</span></div>
|
||||
<div class="line"><span class="signature">get_track_length(track) -> seconds</span></div>
|
||||
</div>
|
||||
<p>Return a floating point value in seconds of the length of the cdrom
|
||||
track.</p>
|
||||
<p>Note, track 0 is the first track on the <code class="docutils literal notranslate"><span class="pre">CD</span></code>. Track numbers start at
|
||||
zero.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/cdrom.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="color.html" title="pygame.Color"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="camera.html" title="pygame.camera"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.cdrom</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,523 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.Color — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="Named Colors" href="color_list.html" />
|
||||
<link rel="prev" title="pygame.cdrom" href="cdrom.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="pygame-color">
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">Color</span></span><a class="headerlink" href="#pygame.Color" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame object for color representations</span></div>
|
||||
<div class="line"><span class="signature">Color(r, g, b) -> Color</span></div>
|
||||
<div class="line"><span class="signature">Color(r, g, b, a=255) -> Color</span></div>
|
||||
<div class="line"><span class="signature">Color(color_value) -> Color</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.r">pygame.Color.r</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets the red value of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.g">pygame.Color.g</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets the green value of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.b">pygame.Color.b</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets the blue value of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.a">pygame.Color.a</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets the alpha value of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.cmy">pygame.Color.cmy</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets the CMY representation of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.hsva">pygame.Color.hsva</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets the HSVA representation of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.hsla">pygame.Color.hsla</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets the HSLA representation of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.i1i2i3">pygame.Color.i1i2i3</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets the I1I2I3 representation of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.normalize">pygame.Color.normalize</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns the normalized RGBA values of the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.correct_gamma">pygame.Color.correct_gamma</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Applies a certain gamma value to the Color.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.set_length">pygame.Color.set_length</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Set the number of elements in the Color to 1,2,3, or 4.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.grayscale">pygame.Color.grayscale</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns the grayscale of a Color</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.lerp">pygame.Color.lerp</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns a linear interpolation to the given Color.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.premul_alpha">pygame.Color.premul_alpha</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns a Color where the r,g,b components have been multiplied by the alpha.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="color.html#pygame.Color.update">pygame.Color.update</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Sets the elements of the color</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">Color</span></code> class represents <code class="docutils literal notranslate"><span class="pre">RGBA</span></code> color values using a value range of
|
||||
0 to 255 inclusive. It allows basic arithmetic operations — binary
|
||||
operations <code class="docutils literal notranslate"><span class="pre">+</span></code>, <code class="docutils literal notranslate"><span class="pre">-</span></code>, <code class="docutils literal notranslate"><span class="pre">*</span></code>, <code class="docutils literal notranslate"><span class="pre">//</span></code>, <code class="docutils literal notranslate"><span class="pre">%</span></code>, and unary operation <code class="docutils literal notranslate"><span class="pre">~</span></code> — to
|
||||
create new colors, supports conversions to other color spaces such as <code class="docutils literal notranslate"><span class="pre">HSV</span></code>
|
||||
or <code class="docutils literal notranslate"><span class="pre">HSL</span></code> and lets you adjust single color channels.
|
||||
Alpha defaults to 255 (fully opaque) when not given.
|
||||
The arithmetic operations and <code class="docutils literal notranslate"><span class="pre">correct_gamma()</span></code> method preserve subclasses.
|
||||
For the binary operators, the class of the returned color is that of the
|
||||
left hand color object of the operator.</p>
|
||||
<p>Color objects support equality comparison with other color objects and 3 or
|
||||
4 element tuples of integers. There was a bug in pygame 1.8.1
|
||||
where the default alpha was 0, not 255 like previously.</p>
|
||||
<p>Color objects export the C level array interface. The interface exports a
|
||||
read-only one dimensional unsigned byte array of the same assigned length
|
||||
as the color. The new buffer interface is also exported, with the same
|
||||
characteristics as the array interface.</p>
|
||||
<p>The floor division, <code class="docutils literal notranslate"><span class="pre">//</span></code>, and modulus, <code class="docutils literal notranslate"><span class="pre">%</span></code>, operators do not raise
|
||||
an exception for division by zero. Instead, if a color, or alpha, channel
|
||||
in the right hand color is 0, then the result is 0. For example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># These expressions are True</span>
|
||||
<span class="n">Color</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">255</span><span class="p">,</span> <span class="mi">255</span><span class="p">,</span> <span class="mi">255</span><span class="p">)</span> <span class="o">//</span> <span class="n">Color</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">64</span><span class="p">,</span> <span class="mi">64</span><span class="p">,</span> <span class="mi">64</span><span class="p">)</span> <span class="o">==</span> <span class="n">Color</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
|
||||
<span class="n">Color</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">255</span><span class="p">,</span> <span class="mi">255</span><span class="p">,</span> <span class="mi">255</span><span class="p">)</span> <span class="o">%</span> <span class="n">Color</span><span class="p">(</span><span class="mi">64</span><span class="p">,</span> <span class="mi">64</span><span class="p">,</span> <span class="mi">64</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">Color</span><span class="p">(</span><span class="mi">63</span><span class="p">,</span> <span class="mi">63</span><span class="p">,</span> <span class="mi">63</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Use <code class="docutils literal notranslate"><span class="pre">int(color)</span></code> to return the immutable integer value of the color,
|
||||
usable as a <code class="docutils literal notranslate"><span class="pre">dict</span></code> key. This integer value differs from the mapped
|
||||
pixel values of <a class="tooltip reference internal" href="surface.html#pygame.Surface.get_at_mapped" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.get_at_mapped()</span></code><span class="tooltip-content">get the mapped color value at a single pixel</span></a>,
|
||||
<a class="tooltip reference internal" href="surface.html#pygame.Surface.map_rgb" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.map_rgb()</span></code><span class="tooltip-content">convert a color into a mapped color value</span></a> and <a class="tooltip reference internal" href="surface.html#pygame.Surface.unmap_rgb" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.unmap_rgb()</span></code><span class="tooltip-content">convert a mapped integer color value into a Color</span></a>.
|
||||
It can be passed as a <code class="docutils literal notranslate"><span class="pre">color_value</span></code> argument to <a class="reference internal" href="#pygame.Color" title="pygame.Color"><code class="xref py py-class docutils literal notranslate"><span class="pre">Color</span></code></a>
|
||||
(useful with sets).</p>
|
||||
<p>See <a class="reference internal" href="color_list.html"><span class="doc">Named Colors</span></a> for samples of the available named colors.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>r</strong> (<em>int</em>) -- red value in the range of 0 to 255 inclusive</p></li>
|
||||
<li><p><strong>g</strong> (<em>int</em>) -- green value in the range of 0 to 255 inclusive</p></li>
|
||||
<li><p><strong>b</strong> (<em>int</em>) -- blue value in the range of 0 to 255 inclusive</p></li>
|
||||
<li><p><strong>a</strong> (<em>int</em>) -- (optional) alpha value in the range of 0 to 255 inclusive,
|
||||
default is 255</p></li>
|
||||
<li><p><strong>color_value</strong> (<a class="reference internal" href="#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>str</em><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>) or
|
||||
</em><em>list</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- <p>color value (see note below for the supported formats)</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<dl>
|
||||
<dt>Supported <code class="docutils literal notranslate"><span class="pre">color_value</span></code> formats:</dt><dd><div class="line-block">
|
||||
<div class="line">- <strong>Color object:</strong> clones the given <a class="reference internal" href="#pygame.Color" title="pygame.Color"><code class="xref py py-class docutils literal notranslate"><span class="pre">Color</span></code></a> object</div>
|
||||
<div class="line">- <strong>Color name: str:</strong> name of the color to use, e.g. <code class="docutils literal notranslate"><span class="pre">'red'</span></code>
|
||||
(all the supported name strings can be found in the
|
||||
<a class="reference internal" href="color_list.html"><span class="doc">Named Colors</span></a>, with sample swatches)</div>
|
||||
<div class="line">- <strong>HTML color format str:</strong> <code class="docutils literal notranslate"><span class="pre">'#rrggbbaa'</span></code> or <code class="docutils literal notranslate"><span class="pre">'#rrggbb'</span></code>,
|
||||
where rr, gg, bb, and aa are 2-digit hex numbers in the range
|
||||
of 0 to 0xFF inclusive, the aa (alpha) value defaults to 0xFF
|
||||
if not provided</div>
|
||||
<div class="line">- <strong>hex number str:</strong> <code class="docutils literal notranslate"><span class="pre">'0xrrggbbaa'</span></code> or <code class="docutils literal notranslate"><span class="pre">'0xrrggbb'</span></code>, where
|
||||
rr, gg, bb, and aa are 2-digit hex numbers in the range of 0x00
|
||||
to 0xFF inclusive, the aa (alpha) value defaults to 0xFF if not
|
||||
provided</div>
|
||||
<div class="line">- <strong>int:</strong> int value of the color to use, using hex numbers can
|
||||
make this parameter more readable, e.g. <code class="docutils literal notranslate"><span class="pre">0xrrggbbaa</span></code>, where rr,
|
||||
gg, bb, and aa are 2-digit hex numbers in the range of 0x00 to
|
||||
0xFF inclusive, note that the aa (alpha) value is not optional for
|
||||
the int format and must be provided</div>
|
||||
<div class="line">- <strong>tuple/list of int color values:</strong> <code class="docutils literal notranslate"><span class="pre">(R,</span> <span class="pre">G,</span> <span class="pre">B,</span> <span class="pre">A)</span></code> or
|
||||
<code class="docutils literal notranslate"><span class="pre">(R,</span> <span class="pre">G,</span> <span class="pre">B)</span></code>, where R, G, B, and A are int values in the range of
|
||||
0 to 255 inclusive, the A (alpha) value defaults to 255 if not
|
||||
provided</div>
|
||||
</div>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a newly created <a class="reference internal" href="#pygame.Color" title="pygame.Color"><code class="xref py py-class docutils literal notranslate"><span class="pre">Color</span></code></a> object</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="#pygame.Color" title="pygame.Color">Color</a></p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Support for tuples, lists, and <a class="reference internal" href="#pygame.Color" title="pygame.Color"><code class="xref py py-class docutils literal notranslate"><span class="pre">Color</span></code></a> objects when creating
|
||||
<a class="reference internal" href="#pygame.Color" title="pygame.Color"><code class="xref py py-class docutils literal notranslate"><span class="pre">Color</span></code></a> objects.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.2: </span>Color objects export the C level array interface.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.0: </span>Color objects support 4-element tuples of integers.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.8.1: </span>New implementation of the class.</p>
|
||||
</div>
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.r">
|
||||
<span class="sig-name descname"><span class="pre">r</span></span><a class="headerlink" href="#pygame.Color.r" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets the red value of the Color.</span></div>
|
||||
<div class="line"><span class="signature">r -> int</span></div>
|
||||
</div>
|
||||
<p>The red value of the Color.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.g">
|
||||
<span class="sig-name descname"><span class="pre">g</span></span><a class="headerlink" href="#pygame.Color.g" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets the green value of the Color.</span></div>
|
||||
<div class="line"><span class="signature">g -> int</span></div>
|
||||
</div>
|
||||
<p>The green value of the Color.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.b">
|
||||
<span class="sig-name descname"><span class="pre">b</span></span><a class="headerlink" href="#pygame.Color.b" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets the blue value of the Color.</span></div>
|
||||
<div class="line"><span class="signature">b -> int</span></div>
|
||||
</div>
|
||||
<p>The blue value of the Color.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.a">
|
||||
<span class="sig-name descname"><span class="pre">a</span></span><a class="headerlink" href="#pygame.Color.a" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets the alpha value of the Color.</span></div>
|
||||
<div class="line"><span class="signature">a -> int</span></div>
|
||||
</div>
|
||||
<p>The alpha value of the Color.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.cmy">
|
||||
<span class="sig-name descname"><span class="pre">cmy</span></span><a class="headerlink" href="#pygame.Color.cmy" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets the CMY representation of the Color.</span></div>
|
||||
<div class="line"><span class="signature">cmy -> tuple</span></div>
|
||||
</div>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">CMY</span></code> representation of the Color. The <code class="docutils literal notranslate"><span class="pre">CMY</span></code> components are in
|
||||
the ranges <code class="docutils literal notranslate"><span class="pre">C</span></code> = [0, 1], <code class="docutils literal notranslate"><span class="pre">M</span></code> = [0, 1], <code class="docutils literal notranslate"><span class="pre">Y</span></code> = [0, 1]. Note that this
|
||||
will not return the absolutely exact <code class="docutils literal notranslate"><span class="pre">CMY</span></code> values for the set <code class="docutils literal notranslate"><span class="pre">RGB</span></code>
|
||||
values in all cases. Due to the <code class="docutils literal notranslate"><span class="pre">RGB</span></code> mapping from 0-255 and the
|
||||
<code class="docutils literal notranslate"><span class="pre">CMY</span></code> mapping from 0-1 rounding errors may cause the <code class="docutils literal notranslate"><span class="pre">CMY</span></code> values to
|
||||
differ slightly from what you might expect.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.hsva">
|
||||
<span class="sig-name descname"><span class="pre">hsva</span></span><a class="headerlink" href="#pygame.Color.hsva" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets the HSVA representation of the Color.</span></div>
|
||||
<div class="line"><span class="signature">hsva -> tuple</span></div>
|
||||
</div>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">HSVA</span></code> representation of the Color. The <code class="docutils literal notranslate"><span class="pre">HSVA</span></code> components are in
|
||||
the ranges <code class="docutils literal notranslate"><span class="pre">H</span></code> = [0, 360], <code class="docutils literal notranslate"><span class="pre">S</span></code> = [0, 100], <code class="docutils literal notranslate"><span class="pre">V</span></code> = [0, 100], A = [0,
|
||||
100]. Note that this will not return the absolutely exact <code class="docutils literal notranslate"><span class="pre">HSV</span></code> values
|
||||
for the set <code class="docutils literal notranslate"><span class="pre">RGB</span></code> values in all cases. Due to the <code class="docutils literal notranslate"><span class="pre">RGB</span></code> mapping from
|
||||
0-255 and the <code class="docutils literal notranslate"><span class="pre">HSV</span></code> mapping from 0-100 and 0-360 rounding errors may
|
||||
cause the <code class="docutils literal notranslate"><span class="pre">HSV</span></code> values to differ slightly from what you might expect.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.hsla">
|
||||
<span class="sig-name descname"><span class="pre">hsla</span></span><a class="headerlink" href="#pygame.Color.hsla" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets the HSLA representation of the Color.</span></div>
|
||||
<div class="line"><span class="signature">hsla -> tuple</span></div>
|
||||
</div>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">HSLA</span></code> representation of the Color. The <code class="docutils literal notranslate"><span class="pre">HSLA</span></code> components are in
|
||||
the ranges <code class="docutils literal notranslate"><span class="pre">H</span></code> = [0, 360], <code class="docutils literal notranslate"><span class="pre">S</span></code> = [0, 100], <code class="docutils literal notranslate"><span class="pre">L</span></code> = [0, 100], A = [0,
|
||||
100]. Note that this will not return the absolutely exact <code class="docutils literal notranslate"><span class="pre">HSL</span></code> values
|
||||
for the set <code class="docutils literal notranslate"><span class="pre">RGB</span></code> values in all cases. Due to the <code class="docutils literal notranslate"><span class="pre">RGB</span></code> mapping from
|
||||
0-255 and the <code class="docutils literal notranslate"><span class="pre">HSL</span></code> mapping from 0-100 and 0-360 rounding errors may
|
||||
cause the <code class="docutils literal notranslate"><span class="pre">HSL</span></code> values to differ slightly from what you might expect.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.i1i2i3">
|
||||
<span class="sig-name descname"><span class="pre">i1i2i3</span></span><a class="headerlink" href="#pygame.Color.i1i2i3" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets the I1I2I3 representation of the Color.</span></div>
|
||||
<div class="line"><span class="signature">i1i2i3 -> tuple</span></div>
|
||||
</div>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">I1I2I3</span></code> representation of the Color. The <code class="docutils literal notranslate"><span class="pre">I1I2I3</span></code> components are
|
||||
in the ranges <code class="docutils literal notranslate"><span class="pre">I1</span></code> = [0, 1], <code class="docutils literal notranslate"><span class="pre">I2</span></code> = [-0.5, 0.5], <code class="docutils literal notranslate"><span class="pre">I3</span></code> = [-0.5,
|
||||
0.5]. Note that this will not return the absolutely exact <code class="docutils literal notranslate"><span class="pre">I1I2I3</span></code>
|
||||
values for the set <code class="docutils literal notranslate"><span class="pre">RGB</span></code> values in all cases. Due to the <code class="docutils literal notranslate"><span class="pre">RGB</span></code>
|
||||
mapping from 0-255 and the <code class="docutils literal notranslate"><span class="pre">I1I2I3</span></code> mapping from 0-1 rounding errors
|
||||
may cause the <code class="docutils literal notranslate"><span class="pre">I1I2I3</span></code> values to differ slightly from what you might
|
||||
expect.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.normalize">
|
||||
<span class="sig-name descname"><span class="pre">normalize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Color.normalize" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns the normalized RGBA values of the Color.</span></div>
|
||||
<div class="line"><span class="signature">normalize() -> tuple</span></div>
|
||||
</div>
|
||||
<p>Returns the normalized <code class="docutils literal notranslate"><span class="pre">RGBA</span></code> values of the Color as floating point
|
||||
values.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.correct_gamma">
|
||||
<span class="sig-name descname"><span class="pre">correct_gamma</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Color.correct_gamma" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Applies a certain gamma value to the Color.</span></div>
|
||||
<div class="line"><span class="signature">correct_gamma (gamma) -> Color</span></div>
|
||||
</div>
|
||||
<p>Applies a certain gamma value to the Color and returns a new Color with
|
||||
the adjusted <code class="docutils literal notranslate"><span class="pre">RGBA</span></code> values.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.set_length">
|
||||
<span class="sig-name descname"><span class="pre">set_length</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Color.set_length" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Set the number of elements in the Color to 1,2,3, or 4.</span></div>
|
||||
<div class="line"><span class="signature">set_length(len) -> None</span></div>
|
||||
</div>
|
||||
<p>DEPRECATED: You may unpack the values you need like so,
|
||||
<code class="docutils literal notranslate"><span class="pre">r,</span> <span class="pre">g,</span> <span class="pre">b,</span> <span class="pre">_</span> <span class="pre">=</span> <span class="pre">pygame.Color(100,</span> <span class="pre">100,</span> <span class="pre">100)</span></code>
|
||||
If you only want r, g and b
|
||||
Or
|
||||
<code class="docutils literal notranslate"><span class="pre">r,</span> <span class="pre">g,</span> <span class="pre">*_</span> <span class="pre">=</span> <span class="pre">pygame.Color(100,</span> <span class="pre">100,</span> <span class="pre">100)</span></code>
|
||||
if you only want r and g</p>
|
||||
<p>The default Color length is 4. Colors can have lengths 1,2,3 or 4. This
|
||||
is useful if you want to unpack to r,g,b and not r,g,b,a. If you want to
|
||||
get the length of a Color do <code class="docutils literal notranslate"><span class="pre">len(acolor)</span></code>.</p>
|
||||
<div class="deprecated">
|
||||
<p><span class="versionmodified deprecated">Deprecated since pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.grayscale">
|
||||
<span class="sig-name descname"><span class="pre">grayscale</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Color.grayscale" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns the grayscale of a Color</span></div>
|
||||
<div class="line"><span class="signature">grayscale() -> Color</span></div>
|
||||
</div>
|
||||
<p>Returns a Color which represents the grayscaled version of self using the luminosity formula which weights red, green and blue according to their wavelengths..</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.lerp">
|
||||
<span class="sig-name descname"><span class="pre">lerp</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Color.lerp" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns a linear interpolation to the given Color.</span></div>
|
||||
<div class="line"><span class="signature">lerp(Color, float) -> Color</span></div>
|
||||
</div>
|
||||
<p>Returns a Color which is a linear interpolation between self and the
|
||||
given Color in RGBA space. The second parameter determines how far
|
||||
between self and other the result is going to be.
|
||||
It must be a value between 0 and 1 where 0 means self and 1 means
|
||||
other will be returned.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.premul_alpha">
|
||||
<span class="sig-name descname"><span class="pre">premul_alpha</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Color.premul_alpha" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns a Color where the r,g,b components have been multiplied by the alpha.</span></div>
|
||||
<div class="line"><span class="signature">premul_alpha() -> Color</span></div>
|
||||
</div>
|
||||
<p>Returns a new Color where each of the red, green and blue colour
|
||||
channels have been multiplied by the alpha channel of the original
|
||||
color. The alpha channel remains unchanged.</p>
|
||||
<p>This is useful when working with the <code class="docutils literal notranslate"><span class="pre">BLEND_PREMULTIPLIED</span></code> blending mode
|
||||
flag for <a class="tooltip reference internal" href="surface.html#pygame.Surface.blit" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.blit()</span></code><span class="tooltip-content">draw one image onto another</span></a>, which assumes that all surfaces using
|
||||
it are using pre-multiplied alpha colors.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Color.update">
|
||||
<span class="sig-name descname"><span class="pre">update</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Color.update" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Sets the elements of the color</span></div>
|
||||
<div class="line"><span class="signature">update(r, g, b) -> None</span></div>
|
||||
<div class="line"><span class="signature">update(r, g, b, a=255) -> None</span></div>
|
||||
<div class="line"><span class="signature">update(color_value) -> None</span></div>
|
||||
</div>
|
||||
<p>Sets the elements of the color. See parameters for <a class="tooltip reference internal" href="#pygame.Color" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Color()</span></code><span class="tooltip-content">pygame object for color representations</span></a> for the
|
||||
parameters of this function. If the alpha value was not set it will not change.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/color.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="color_list.html" title="Named Colors"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="cdrom.html" title="pygame.cdrom"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.Color</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,438 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.cursors — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.display" href="display.html" />
|
||||
<link rel="prev" title="Named Colors" href="color_list.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.cursors">
|
||||
<span id="pygame-cursors"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.cursors</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for cursor resources</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cursors.html#pygame.cursors.compile">pygame.cursors.compile</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>create binary cursor data from simple strings</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cursors.html#pygame.cursors.load_xbm">pygame.cursors.load_xbm</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>load cursor data from an XBM file</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cursors.html#pygame.cursors.Cursor">pygame.cursors.Cursor</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>pygame object representing a cursor</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Pygame offers control over the system hardware cursor. Pygame supports
|
||||
black and white cursors (bitmap cursors), as well as system variant cursors and color cursors.
|
||||
You control the cursor with functions inside <a class="tooltip reference internal" href="mouse.html#module-pygame.mouse" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mouse</span></code><span class="tooltip-content">pygame module to work with the mouse</span></a>.</p>
|
||||
<p>This cursors module contains functions for loading and decoding various
|
||||
cursor formats. These allow you to easily store your cursors in external files
|
||||
or directly as encoded python strings.</p>
|
||||
<p>The module includes several standard cursors. The <a class="tooltip reference internal" href="mouse.html#pygame.mouse.set_cursor" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.mouse.set_cursor()</span></code><span class="tooltip-content">set the mouse cursor to a new cursor</span></a>
|
||||
function takes several arguments. All those arguments have been stored in a
|
||||
single tuple you can call like this:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">mouse</span><span class="o">.</span><span class="n">set_cursor</span><span class="p">(</span><span class="o">*</span><span class="n">pygame</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">arrow</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The following variables can be passed to <code class="docutils literal notranslate"><span class="pre">pygame.mouse.set_cursor</span></code> function:</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.arrow</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.diamond</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.broken_x</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.tri_left</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.tri_right</span></code></p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<p>This module also contains a few cursors as formatted strings. You'll need to
|
||||
pass these to <code class="docutils literal notranslate"><span class="pre">pygame.cursors.compile()</span></code> function before you can use them.
|
||||
The example call would look like this:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cursor</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">pygame</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">textmarker_strings</span><span class="p">)</span>
|
||||
<span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">mouse</span><span class="o">.</span><span class="n">set_cursor</span><span class="p">((</span><span class="mi">8</span><span class="p">,</span> <span class="mi">16</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="o">*</span><span class="n">cursor</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The following strings can be converted into cursor bitmaps with
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.cursors.compile()</span></code> :</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.thickarrow_strings</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.sizer_x_strings</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.sizer_y_strings</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursors.sizer_xy_strings</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">pygame.cursor.textmarker_strings</span></code></p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cursors.compile">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.cursors.</span></span><span class="sig-name descname"><span class="pre">compile</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cursors.compile" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">create binary cursor data from simple strings</span></div>
|
||||
<div class="line"><span class="signature">compile(strings, black='X', white='.', xor='o') -> data, mask</span></div>
|
||||
</div>
|
||||
<p>A sequence of strings can be used to create binary cursor data for the
|
||||
system cursor. This returns the binary data in the form of two tuples.
|
||||
Those can be passed as the third and fourth arguments respectively of the
|
||||
<a class="tooltip reference internal" href="mouse.html#pygame.mouse.set_cursor" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.mouse.set_cursor()</span></code><span class="tooltip-content">set the mouse cursor to a new cursor</span></a> function.</p>
|
||||
<p>If you are creating your own cursor strings, you can use any value represent
|
||||
the black and white pixels. Some system allow you to set a special toggle
|
||||
color for the system color, this is also called the xor color. If the system
|
||||
does not support xor cursors, that color will simply be black.</p>
|
||||
<p>The height must be divisible by 8. The width of the strings must all be equal
|
||||
and be divisible by 8. If these two conditions are not met, <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is
|
||||
raised.
|
||||
An example set of cursor strings looks like this</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">thickarrow_strings</span> <span class="o">=</span> <span class="p">(</span> <span class="c1">#sized 24x24</span>
|
||||
<span class="s2">"XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XXX "</span><span class="p">,</span>
|
||||
<span class="s2">"XXXX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX.XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX..XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX...XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX....XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX.....XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX......XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX.......XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX........XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX........XXX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX......XXXXX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX.XXX..XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XXXX XX..XX "</span><span class="p">,</span>
|
||||
<span class="s2">"XX XX..XX "</span><span class="p">,</span>
|
||||
<span class="s2">" XX..XX "</span><span class="p">,</span>
|
||||
<span class="s2">" XX..XX "</span><span class="p">,</span>
|
||||
<span class="s2">" XX..XX "</span><span class="p">,</span>
|
||||
<span class="s2">" XXXX "</span><span class="p">,</span>
|
||||
<span class="s2">" XX "</span><span class="p">,</span>
|
||||
<span class="s2">" "</span><span class="p">,</span>
|
||||
<span class="s2">" "</span><span class="p">,</span>
|
||||
<span class="s2">" "</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cursors.load_xbm">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.cursors.</span></span><span class="sig-name descname"><span class="pre">load_xbm</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cursors.load_xbm" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">load cursor data from an XBM file</span></div>
|
||||
<div class="line"><span class="signature">load_xbm(cursorfile) -> cursor_args</span></div>
|
||||
<div class="line"><span class="signature">load_xbm(cursorfile, maskfile) -> cursor_args</span></div>
|
||||
</div>
|
||||
<p>This loads cursors for a simple subset of <code class="docutils literal notranslate"><span class="pre">XBM</span></code> files. <code class="docutils literal notranslate"><span class="pre">XBM</span></code> files are
|
||||
traditionally used to store cursors on UNIX systems, they are an ASCII
|
||||
format used to represent simple images.</p>
|
||||
<p>Sometimes the black and white color values will be split into two separate
|
||||
<code class="docutils literal notranslate"><span class="pre">XBM</span></code> files. You can pass a second maskfile argument to load the two
|
||||
images into a single cursor.</p>
|
||||
<p>The cursorfile and maskfile arguments can either be filenames or file-like
|
||||
object with the readlines method.</p>
|
||||
<p>The return value cursor_args can be passed directly to the
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mouse.set_cursor()</span></code> function.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cursors.Cursor">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.cursors.</span></span><span class="sig-name descname"><span class="pre">Cursor</span></span><a class="headerlink" href="#pygame.cursors.Cursor" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame object representing a cursor</span></div>
|
||||
<div class="line"><span class="signature">Cursor(size, hotspot, xormasks, andmasks) -> Cursor</span></div>
|
||||
<div class="line"><span class="signature">Cursor(hotspot, surface) -> Cursor</span></div>
|
||||
<div class="line"><span class="signature">Cursor(constant) -> Cursor</span></div>
|
||||
<div class="line"><span class="signature">Cursor(Cursor) -> Cursor</span></div>
|
||||
<div class="line"><span class="signature">Cursor() -> Cursor</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cursors.html#pygame.cursors.Cursor.copy">pygame.cursors.Cursor.copy</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>copy the current cursor</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="cursors.html#pygame.cursors.Cursor.type">pygame.cursors.Cursor.type</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the cursor type</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="cursors.html#pygame.cursors.Cursor.data">pygame.cursors.Cursor.data</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the cursor data</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>In pygame 2, there are 3 types of cursors you can create to give your
|
||||
game that little bit of extra polish. There's <strong>bitmap</strong> type cursors,
|
||||
which existed in pygame 1.x, and are compiled from a string or load from an xbm file.
|
||||
Then there are <strong>system</strong> type cursors, where you choose a preset that will
|
||||
convey the same meaning but look native across different operating systems.
|
||||
Finally you can create a <strong>color</strong> cursor, which displays a pygame surface as the cursor.</p>
|
||||
<p><strong>Creating a system cursor</strong></p>
|
||||
<p>Choose a constant from this list, pass it into <code class="docutils literal notranslate"><span class="pre">pygame.cursors.Cursor(constant)</span></code>,
|
||||
and you're good to go. Be advised that not all systems support every system
|
||||
cursor, and you may get a substitution instead. For example, on MacOS,
|
||||
WAIT/WAITARROW should show up as an arrow, and SIZENWSE/SIZENESW/SIZEALL
|
||||
should show up as a closed hand. And on Wayland, every SIZE cursor should
|
||||
show up as a hand.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Pygame</span> <span class="n">Cursor</span> <span class="n">Constant</span> <span class="n">Description</span>
|
||||
<span class="o">--------------------------------------------</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_ARROW</span> <span class="n">arrow</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_IBEAM</span> <span class="n">i</span><span class="o">-</span><span class="n">beam</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_WAIT</span> <span class="n">wait</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_CROSSHAIR</span> <span class="n">crosshair</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_WAITARROW</span> <span class="n">small</span> <span class="n">wait</span> <span class="n">cursor</span>
|
||||
<span class="p">(</span><span class="ow">or</span> <span class="n">wait</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">available</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_SIZENWSE</span> <span class="n">double</span> <span class="n">arrow</span> <span class="n">pointing</span>
|
||||
<span class="n">northwest</span> <span class="ow">and</span> <span class="n">southeast</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_SIZENESW</span> <span class="n">double</span> <span class="n">arrow</span> <span class="n">pointing</span>
|
||||
<span class="n">northeast</span> <span class="ow">and</span> <span class="n">southwest</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_SIZEWE</span> <span class="n">double</span> <span class="n">arrow</span> <span class="n">pointing</span>
|
||||
<span class="n">west</span> <span class="ow">and</span> <span class="n">east</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_SIZENS</span> <span class="n">double</span> <span class="n">arrow</span> <span class="n">pointing</span>
|
||||
<span class="n">north</span> <span class="ow">and</span> <span class="n">south</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_SIZEALL</span> <span class="n">four</span> <span class="n">pointed</span> <span class="n">arrow</span> <span class="n">pointing</span>
|
||||
<span class="n">north</span><span class="p">,</span> <span class="n">south</span><span class="p">,</span> <span class="n">east</span><span class="p">,</span> <span class="ow">and</span> <span class="n">west</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_NO</span> <span class="n">slashed</span> <span class="n">circle</span> <span class="ow">or</span> <span class="n">crossbones</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_HAND</span> <span class="n">hand</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p><strong>Creating a cursor without passing arguments</strong></p>
|
||||
<p>In addition to the cursor constants available and described above,
|
||||
you can also call <code class="docutils literal notranslate"><span class="pre">pygame.cursors.Cursor()</span></code>, and your cursor is ready (doing that is the same as
|
||||
calling <code class="docutils literal notranslate"><span class="pre">pygame.cursors.Cursor(pygame.SYSTEM_CURSOR_ARROW)</span></code>.
|
||||
Doing one of those calls actually creates a system cursor using the default native image.</p>
|
||||
<p><strong>Creating a color cursor</strong></p>
|
||||
<p>To create a color cursor, create a <code class="docutils literal notranslate"><span class="pre">Cursor</span></code> from a <code class="docutils literal notranslate"><span class="pre">hotspot</span></code> and a <code class="docutils literal notranslate"><span class="pre">surface</span></code>.
|
||||
<code class="docutils literal notranslate"><span class="pre">hotspot</span></code> is an (x,y) coordinate that determines where in the cursor the exact point is.
|
||||
The hotspot position must be within the bounds of the <code class="docutils literal notranslate"><span class="pre">surface</span></code>.</p>
|
||||
<p><strong>Creating a bitmap cursor</strong></p>
|
||||
<p>When the mouse cursor is visible, it will be displayed as a black and white
|
||||
bitmap using the given bitmask arrays. The <code class="docutils literal notranslate"><span class="pre">size</span></code> is a sequence containing
|
||||
the cursor width and height. <code class="docutils literal notranslate"><span class="pre">hotspot</span></code> is a sequence containing the cursor
|
||||
hotspot position.</p>
|
||||
<p>A cursor has a width and height, but a mouse position is represented by a
|
||||
set of point coordinates. So the value passed into the cursor <code class="docutils literal notranslate"><span class="pre">hotspot</span></code>
|
||||
variable helps pygame to actually determine at what exact point the cursor
|
||||
is at.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">xormasks</span></code> is a sequence of bytes containing the cursor xor data masks.
|
||||
Lastly <code class="docutils literal notranslate"><span class="pre">andmasks</span></code>, a sequence of bytes containing the cursor bitmask data.
|
||||
To create these variables, we can make use of the
|
||||
<a class="tooltip reference internal" href="#pygame.cursors.compile" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.cursors.compile()</span></code><span class="tooltip-content">create binary cursor data from simple strings</span></a> function.</p>
|
||||
<p>Width and height must be a multiple of 8, and the mask arrays must be the
|
||||
correct size for the given width and height. Otherwise an exception is raised.</p>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cursors.Cursor.copy">
|
||||
<span class="sig-name descname"><span class="pre">copy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.cursors.Cursor.copy" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">copy the current cursor</span></div>
|
||||
<div class="line"><span class="signature">copy() -> Cursor</span></div>
|
||||
</div>
|
||||
<p>Returns a new Cursor object with the same data and hotspot as the original.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cursors.Cursor.type">
|
||||
<span class="sig-name descname"><span class="pre">type</span></span><a class="headerlink" href="#pygame.cursors.Cursor.type" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the cursor type</span></div>
|
||||
<div class="line"><span class="signature">type -> string</span></div>
|
||||
</div>
|
||||
<p>The type will be <code class="docutils literal notranslate"><span class="pre">"system"</span></code>, <code class="docutils literal notranslate"><span class="pre">"bitmap"</span></code>, or <code class="docutils literal notranslate"><span class="pre">"color"</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.cursors.Cursor.data">
|
||||
<span class="sig-name descname"><span class="pre">data</span></span><a class="headerlink" href="#pygame.cursors.Cursor.data" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the cursor data</span></div>
|
||||
<div class="line"><span class="signature">data -> tuple</span></div>
|
||||
</div>
|
||||
<p>Returns the data that was used to create this cursor object, wrapped up in a tuple.</p>
|
||||
</dd></dl>
|
||||
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<p>Example code for creating and settings cursors. (Click the mouse to switch cursor)</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># pygame setup</span>
|
||||
<span class="kn">import</span> <span class="nn">pygame</span> <span class="k">as</span> <span class="nn">pg</span>
|
||||
|
||||
<span class="n">pg</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
|
||||
<span class="n">screen</span> <span class="o">=</span> <span class="n">pg</span><span class="o">.</span><span class="n">display</span><span class="o">.</span><span class="n">set_mode</span><span class="p">([</span><span class="mi">600</span><span class="p">,</span> <span class="mi">400</span><span class="p">])</span>
|
||||
<span class="n">pg</span><span class="o">.</span><span class="n">display</span><span class="o">.</span><span class="n">set_caption</span><span class="p">(</span><span class="s2">"Example code for the cursors module"</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># create a system cursor</span>
|
||||
<span class="n">system</span> <span class="o">=</span> <span class="n">pg</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">Cursor</span><span class="p">(</span><span class="n">pg</span><span class="o">.</span><span class="n">SYSTEM_CURSOR_NO</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># create bitmap cursors</span>
|
||||
<span class="n">bitmap_1</span> <span class="o">=</span> <span class="n">pg</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">Cursor</span><span class="p">(</span><span class="o">*</span><span class="n">pg</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">arrow</span><span class="p">)</span>
|
||||
<span class="n">bitmap_2</span> <span class="o">=</span> <span class="n">pg</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">Cursor</span><span class="p">(</span>
|
||||
<span class="p">(</span><span class="mi">24</span><span class="p">,</span> <span class="mi">24</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="o">*</span><span class="n">pg</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">pg</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">thickarrow_strings</span><span class="p">)</span>
|
||||
<span class="p">)</span>
|
||||
|
||||
<span class="c1"># create a color cursor</span>
|
||||
<span class="n">surf</span> <span class="o">=</span> <span class="n">pg</span><span class="o">.</span><span class="n">Surface</span><span class="p">((</span><span class="mi">40</span><span class="p">,</span> <span class="mi">40</span><span class="p">))</span> <span class="c1"># you could also load an image </span>
|
||||
<span class="n">surf</span><span class="o">.</span><span class="n">fill</span><span class="p">((</span><span class="mi">120</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">))</span> <span class="c1"># and use that as your surface</span>
|
||||
<span class="n">color</span> <span class="o">=</span> <span class="n">pg</span><span class="o">.</span><span class="n">cursors</span><span class="o">.</span><span class="n">Cursor</span><span class="p">((</span><span class="mi">20</span><span class="p">,</span> <span class="mi">20</span><span class="p">),</span> <span class="n">surf</span><span class="p">)</span>
|
||||
|
||||
<span class="n">cursors</span> <span class="o">=</span> <span class="p">[</span><span class="n">system</span><span class="p">,</span> <span class="n">bitmap_1</span><span class="p">,</span> <span class="n">bitmap_2</span><span class="p">,</span> <span class="n">color</span><span class="p">]</span>
|
||||
<span class="n">cursor_index</span> <span class="o">=</span> <span class="mi">0</span>
|
||||
|
||||
<span class="n">pg</span><span class="o">.</span><span class="n">mouse</span><span class="o">.</span><span class="n">set_cursor</span><span class="p">(</span><span class="n">cursors</span><span class="p">[</span><span class="n">cursor_index</span><span class="p">])</span>
|
||||
|
||||
<span class="n">clock</span> <span class="o">=</span> <span class="n">pg</span><span class="o">.</span><span class="n">time</span><span class="o">.</span><span class="n">Clock</span><span class="p">()</span>
|
||||
<span class="n">going</span> <span class="o">=</span> <span class="kc">True</span>
|
||||
<span class="k">while</span> <span class="n">going</span><span class="p">:</span>
|
||||
<span class="n">clock</span><span class="o">.</span><span class="n">tick</span><span class="p">(</span><span class="mi">60</span><span class="p">)</span>
|
||||
<span class="n">screen</span><span class="o">.</span><span class="n">fill</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">75</span><span class="p">,</span> <span class="mi">30</span><span class="p">))</span>
|
||||
<span class="n">pg</span><span class="o">.</span><span class="n">display</span><span class="o">.</span><span class="n">flip</span><span class="p">()</span>
|
||||
|
||||
<span class="k">for</span> <span class="n">event</span> <span class="ow">in</span> <span class="n">pg</span><span class="o">.</span><span class="n">event</span><span class="o">.</span><span class="n">get</span><span class="p">():</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">pg</span><span class="o">.</span><span class="n">QUIT</span> <span class="ow">or</span> <span class="p">(</span><span class="n">event</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">pg</span><span class="o">.</span><span class="n">KEYDOWN</span> <span class="ow">and</span> <span class="n">event</span><span class="o">.</span><span class="n">key</span> <span class="o">==</span> <span class="n">pg</span><span class="o">.</span><span class="n">K_ESCAPE</span><span class="p">):</span>
|
||||
<span class="n">going</span> <span class="o">=</span> <span class="kc">False</span>
|
||||
|
||||
<span class="c1"># if the mouse is clicked it will switch to a new cursor</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">pg</span><span class="o">.</span><span class="n">MOUSEBUTTONDOWN</span><span class="p">:</span>
|
||||
<span class="n">cursor_index</span> <span class="o">+=</span> <span class="mi">1</span>
|
||||
<span class="n">cursor_index</span> <span class="o">%=</span> <span class="nb">len</span><span class="p">(</span><span class="n">cursors</span><span class="p">)</span>
|
||||
<span class="n">pg</span><span class="o">.</span><span class="n">mouse</span><span class="o">.</span><span class="n">set_cursor</span><span class="p">(</span><span class="n">cursors</span><span class="p">[</span><span class="n">cursor_index</span><span class="p">])</span>
|
||||
|
||||
<span class="n">pg</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/cursors.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="display.html" title="pygame.display"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="color_list.html" title="Named Colors"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.cursors</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,956 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.draw — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.event" href="event.html" />
|
||||
<link rel="prev" title="pygame.display" href="display.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.draw">
|
||||
<span id="pygame-draw"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.draw</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for drawing shapes</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.rect">pygame.draw.rect</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw a rectangle</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.polygon">pygame.draw.polygon</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw a polygon</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.circle">pygame.draw.circle</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw a circle</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.ellipse">pygame.draw.ellipse</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw an ellipse</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.arc">pygame.draw.arc</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw an elliptical arc</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.line">pygame.draw.line</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw a straight line</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.lines">pygame.draw.lines</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw multiple contiguous straight line segments</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.aaline">pygame.draw.aaline</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw a straight antialiased line</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="draw.html#pygame.draw.aalines">pygame.draw.aalines</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw multiple contiguous straight antialiased line segments</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Draw several simple shapes to a surface. These functions will work for
|
||||
rendering to any format of surface.</p>
|
||||
<p>Most of the functions take a width argument to represent the size of stroke
|
||||
(thickness) around the edge of the shape. If a width of 0 is passed the shape
|
||||
will be filled (solid).</p>
|
||||
<p>All the drawing functions respect the clip area for the surface and will be
|
||||
constrained to that area. The functions return a rectangle representing the
|
||||
bounding area of changed pixels. This bounding rectangle is the 'minimum'
|
||||
bounding box that encloses the affected area.</p>
|
||||
<p>All the drawing functions accept a color argument that can be one of the
|
||||
following formats:</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p>a <a class="tooltip reference internal" href="color.html#pygame.Color" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.Color</span></code><span class="tooltip-content">pygame object for color representations</span></a> object</p></li>
|
||||
<li><p>an <code class="docutils literal notranslate"><span class="pre">(RGB)</span></code> triplet (tuple/list)</p></li>
|
||||
<li><p>an <code class="docutils literal notranslate"><span class="pre">(RGBA)</span></code> quadruplet (tuple/list)</p></li>
|
||||
<li><p>an integer value that has been mapped to the surface's pixel format
|
||||
(see <a class="tooltip reference internal" href="surface.html#pygame.Surface.map_rgb" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.Surface.map_rgb()</span></code><span class="tooltip-content">convert a color into a mapped color value</span></a> and <a class="tooltip reference internal" href="surface.html#pygame.Surface.unmap_rgb" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.Surface.unmap_rgb()</span></code><span class="tooltip-content">convert a mapped integer color value into a Color</span></a>)</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<p>A color's alpha value will be written directly into the surface (if the
|
||||
surface contains pixel alphas), but the draw function will not draw
|
||||
transparently.</p>
|
||||
<p>These functions temporarily lock the surface they are operating on. Many
|
||||
sequential drawing calls can be sped up by locking and unlocking the surface
|
||||
object around the draw calls (see <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> and
|
||||
<a class="tooltip reference internal" href="surface.html#pygame.Surface.unlock" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.Surface.unlock()</span></code><span class="tooltip-content">unlock the Surface memory from pixel access</span></a>).</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>See the <a class="tooltip reference internal" href="gfxdraw.html#module-pygame.gfxdraw" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.gfxdraw</span></code><span class="tooltip-content">pygame module for drawing shapes</span></a> module for alternative draw methods.</p>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.rect">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">rect</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.rect" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw a rectangle</span></div>
|
||||
<div class="line"><span class="signature">rect(surface, color, rect) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">rect(surface, color, rect, width=0, border_radius=0, border_top_left_radius=-1, border_top_right_radius=-1, border_bottom_left_radius=-1, border_bottom_right_radius=-1) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws a rectangle on the given surface.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>rect</strong> (<a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect"><em>Rect</em></a>) -- rectangle to draw, position and dimensions</p></li>
|
||||
<li><p><strong>width</strong> (<em>int</em>) -- <p>(optional) used for line thickness or to indicate that
|
||||
the rectangle is to be filled (not to be confused with the width value
|
||||
of the <code class="docutils literal notranslate"><span class="pre">rect</span></code> parameter)</p>
|
||||
<blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">==</span> <span class="pre">0</span></code>, (default) fill the rectangle</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">></span> <span class="pre">0</span></code>, used for line thickness</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre"><</span> <span class="pre">0</span></code>, nothing will be drawn</div>
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.1.1: </span>Drawing rects with width now draws the width correctly inside the
|
||||
rect's area, rather than using an internal call to draw.lines(),
|
||||
which had half the width spill outside the rect area.</p>
|
||||
</div>
|
||||
</p></li>
|
||||
<li><p><strong>border_radius</strong> (<em>int</em>) -- (optional) used for drawing rectangle with rounded corners.
|
||||
The supported range is [0, min(height, width) / 2], with 0 representing a rectangle
|
||||
without rounded corners.</p></li>
|
||||
<li><p><strong>border_top_left_radius</strong> (<em>int</em>) -- (optional) used for setting the value of top left
|
||||
border. If you don't set this value, it will use the border_radius value.</p></li>
|
||||
<li><p><strong>border_top_right_radius</strong> (<em>int</em>) -- (optional) used for setting the value of top right
|
||||
border. If you don't set this value, it will use the border_radius value.</p></li>
|
||||
<li><p><strong>border_bottom_left_radius</strong> (<em>int</em>) -- (optional) used for setting the value of bottom left
|
||||
border. If you don't set this value, it will use the border_radius value.</p></li>
|
||||
<li><p><strong>border_bottom_right_radius</strong> (<em>int</em>) -- <p>(optional) used for setting the value of bottom right
|
||||
border. If you don't set this value, it will use the border_radius value.</p>
|
||||
<blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">border_radius</span> <span class="pre"><</span> <span class="pre">1</span></code> it will draw rectangle without rounded corners</div>
|
||||
<div class="line">if any of border radii has the value <code class="docutils literal notranslate"><span class="pre"><</span> <span class="pre">0</span></code> it will use value of the border_radius</div>
|
||||
<div class="line">If sum of radii on the same side of the rectangle is greater than the rect size the radii</div>
|
||||
<div class="line">will get scaled</div>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the position of the given <code class="docutils literal notranslate"><span class="pre">rect</span></code>
|
||||
parameter and its width and height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The <a class="tooltip reference internal" href="surface.html#pygame.Surface.fill" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.Surface.fill()</span></code><span class="tooltip-content">fill Surface with a solid color</span></a> method works just as well for drawing
|
||||
filled rectangles and can be hardware accelerated on some platforms.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0.dev8: </span>Added support for border radius.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.polygon">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">polygon</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.polygon" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw a polygon</span></div>
|
||||
<div class="line"><span class="signature">polygon(surface, color, points) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">polygon(surface, color, points, width=0) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws a polygon on the given surface.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>points</strong> (<em>tuple</em><em>(</em><em>coordinate</em><em>) or </em><em>list</em><em>(</em><em>coordinate</em><em>)</em>) -- a sequence of 3 or more (x, y) coordinates that make up the
|
||||
vertices of the polygon, each <em>coordinate</em> in the sequence must be a
|
||||
tuple/list/<a class="tooltip reference internal" href="math.html#pygame.math.Vector2" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.math.Vector2</span></code><span class="tooltip-content">a 2-Dimensional Vector</span></a> of 2 ints/floats,
|
||||
e.g. <code class="docutils literal notranslate"><span class="pre">[(x1,</span> <span class="pre">y1),</span> <span class="pre">(x2,</span> <span class="pre">y2),</span> <span class="pre">(x3,</span> <span class="pre">y3)]</span></code></p></li>
|
||||
<li><p><strong>width</strong> (<em>int</em>) -- <p>(optional) used for line thickness or to indicate that
|
||||
the polygon is to be filled</p>
|
||||
<blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line">if width == 0, (default) fill the polygon</div>
|
||||
<div class="line">if width > 0, used for line thickness</div>
|
||||
<div class="line">if width < 0, nothing will be drawn</div>
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>When using <code class="docutils literal notranslate"><span class="pre">width</span></code> values <code class="docutils literal notranslate"><span class="pre">></span> <span class="pre">1</span></code>, the edge lines will grow
|
||||
outside the original boundary of the polygon. For more details on
|
||||
how the thickness for edge lines grow, refer to the <code class="docutils literal notranslate"><span class="pre">width</span></code> notes
|
||||
of the <a class="tooltip reference internal" href="#pygame.draw.line" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.draw.line()</span></code><span class="tooltip-content">draw a straight line</span></a> function.</p>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the position of the first point in the
|
||||
<code class="docutils literal notranslate"><span class="pre">points</span></code> parameter (float values will be truncated) and its width and
|
||||
height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><ul class="simple">
|
||||
<li><p><strong>ValueError</strong> -- if <code class="docutils literal notranslate"><span class="pre">len(points)</span> <span class="pre"><</span> <span class="pre">3</span></code> (must have at least 3 points)</p></li>
|
||||
<li><p><strong>TypeError</strong> -- if <code class="docutils literal notranslate"><span class="pre">points</span></code> is not a sequence or <code class="docutils literal notranslate"><span class="pre">points</span></code> does not
|
||||
contain number pairs</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>For an aapolygon, use <a class="reference internal" href="#pygame.draw.aalines" title="pygame.draw.aalines"><code class="xref py py-func docutils literal notranslate"><span class="pre">aalines()</span></code></a> with <code class="docutils literal notranslate"><span class="pre">closed=True</span></code>.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.circle">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">circle</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.circle" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw a circle</span></div>
|
||||
<div class="line"><span class="signature">circle(surface, color, center, radius) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">circle(surface, color, center, radius, width=0, draw_top_right=None, draw_top_left=None, draw_bottom_left=None, draw_bottom_right=None) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws a circle on the given surface.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>center</strong> (<em>tuple</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or
|
||||
</em><em>list</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or </em><a class="reference internal" href="math.html#pygame.math.Vector2" title="pygame.math.Vector2"><em>Vector2</em></a><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>)</em>) -- center point of the circle as a sequence of 2 ints/floats,
|
||||
e.g. <code class="docutils literal notranslate"><span class="pre">(x,</span> <span class="pre">y)</span></code></p></li>
|
||||
<li><p><strong>radius</strong> (<em>int</em><em> or </em><em>float</em>) -- radius of the circle, measured from the <code class="docutils literal notranslate"><span class="pre">center</span></code> parameter,
|
||||
nothing will be drawn if the <code class="docutils literal notranslate"><span class="pre">radius</span></code> is less than 1</p></li>
|
||||
<li><p><strong>width</strong> (<em>int</em>) -- <p>(optional) used for line thickness or to indicate that
|
||||
the circle is to be filled</p>
|
||||
<blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">==</span> <span class="pre">0</span></code>, (default) fill the circle</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">></span> <span class="pre">0</span></code>, used for line thickness</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre"><</span> <span class="pre">0</span></code>, nothing will be drawn</div>
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>When using <code class="docutils literal notranslate"><span class="pre">width</span></code> values <code class="docutils literal notranslate"><span class="pre">></span> <span class="pre">1</span></code>, the edge lines will only grow
|
||||
inward.</p>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</p></li>
|
||||
<li><p><strong>draw_top_right</strong> (<em>bool</em>) -- (optional) if this is set to True then the top right corner
|
||||
of the circle will be drawn</p></li>
|
||||
<li><p><strong>draw_top_left</strong> (<em>bool</em>) -- (optional) if this is set to True then the top left corner
|
||||
of the circle will be drawn</p></li>
|
||||
<li><p><strong>draw_bottom_left</strong> (<em>bool</em>) -- (optional) if this is set to True then the bottom left corner
|
||||
of the circle will be drawn</p></li>
|
||||
<li><p><strong>draw_bottom_right</strong> (<em>bool</em>) -- <p>(optional) if this is set to True then the bottom right corner
|
||||
of the circle will be drawn</p>
|
||||
<blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line">if any of the draw_circle_part is True then it will draw all circle parts that have the True</div>
|
||||
<div class="line">value, otherwise it will draw the entire circle.</div>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the <code class="docutils literal notranslate"><span class="pre">center</span></code> parameter value (float
|
||||
values will be truncated) and its width and height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><ul class="simple">
|
||||
<li><p><strong>TypeError</strong> -- if <code class="docutils literal notranslate"><span class="pre">center</span></code> is not a sequence of two numbers</p></li>
|
||||
<li><p><strong>TypeError</strong> -- if <code class="docutils literal notranslate"><span class="pre">radius</span></code> is not a number</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.
|
||||
Nothing is drawn when the radius is 0 (a pixel at the <code class="docutils literal notranslate"><span class="pre">center</span></code> coordinates
|
||||
used to be drawn when the radius equaled 0).
|
||||
Floats, and Vector2 are accepted for the <code class="docutils literal notranslate"><span class="pre">center</span></code> param.
|
||||
The drawing algorithm was improved to look more like a circle.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0.dev8: </span>Added support for drawing circle quadrants.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.ellipse">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">ellipse</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.ellipse" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw an ellipse</span></div>
|
||||
<div class="line"><span class="signature">ellipse(surface, color, rect) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">ellipse(surface, color, rect, width=0) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws an ellipse on the given surface.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>rect</strong> (<a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect"><em>Rect</em></a>) -- rectangle to indicate the position and dimensions of the
|
||||
ellipse, the ellipse will be centered inside the rectangle and bounded
|
||||
by it</p></li>
|
||||
<li><p><strong>width</strong> (<em>int</em>) -- <p>(optional) used for line thickness or to indicate that
|
||||
the ellipse is to be filled (not to be confused with the width value
|
||||
of the <code class="docutils literal notranslate"><span class="pre">rect</span></code> parameter)</p>
|
||||
<blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">==</span> <span class="pre">0</span></code>, (default) fill the ellipse</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">></span> <span class="pre">0</span></code>, used for line thickness</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre"><</span> <span class="pre">0</span></code>, nothing will be drawn</div>
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>When using <code class="docutils literal notranslate"><span class="pre">width</span></code> values <code class="docutils literal notranslate"><span class="pre">></span> <span class="pre">1</span></code>, the edge lines will only grow
|
||||
inward from the original boundary of the <code class="docutils literal notranslate"><span class="pre">rect</span></code> parameter.</p>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the position of the given <code class="docutils literal notranslate"><span class="pre">rect</span></code>
|
||||
parameter and its width and height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.arc">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">arc</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.arc" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw an elliptical arc</span></div>
|
||||
<div class="line"><span class="signature">arc(surface, color, rect, start_angle, stop_angle) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">arc(surface, color, rect, start_angle, stop_angle, width=1) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws an elliptical arc on the given surface.</p>
|
||||
<p>The two angle arguments are given in radians and indicate the start and stop
|
||||
positions of the arc. The arc is drawn in a counterclockwise direction from
|
||||
the <code class="docutils literal notranslate"><span class="pre">start_angle</span></code> to the <code class="docutils literal notranslate"><span class="pre">stop_angle</span></code>.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>rect</strong> (<a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect"><em>Rect</em></a>) -- rectangle to indicate the position and dimensions of the
|
||||
ellipse which the arc will be based on, the ellipse will be centered
|
||||
inside the rectangle</p></li>
|
||||
<li><p><strong>start_angle</strong> (<em>float</em>) -- start angle of the arc in radians</p></li>
|
||||
<li><p><strong>stop_angle</strong> (<em>float</em>) -- <p>stop angle of the arc in
|
||||
radians</p>
|
||||
<blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">start_angle</span> <span class="pre"><</span> <span class="pre">stop_angle</span></code>, the arc is drawn in a
|
||||
counterclockwise direction from the <code class="docutils literal notranslate"><span class="pre">start_angle</span></code> to the
|
||||
<code class="docutils literal notranslate"><span class="pre">stop_angle</span></code></div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">start_angle</span> <span class="pre">></span> <span class="pre">stop_angle</span></code>, tau (tau == 2 * pi) will be added
|
||||
to the <code class="docutils literal notranslate"><span class="pre">stop_angle</span></code>, if the resulting stop angle value is greater
|
||||
than the <code class="docutils literal notranslate"><span class="pre">start_angle</span></code> the above <code class="docutils literal notranslate"><span class="pre">start_angle</span> <span class="pre"><</span> <span class="pre">stop_angle</span></code> case
|
||||
applies, otherwise nothing will be drawn</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">start_angle</span> <span class="pre">==</span> <span class="pre">stop_angle</span></code>, nothing will be drawn</div>
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</p></li>
|
||||
<li><p><strong>width</strong> (<em>int</em>) -- <p>(optional) used for line thickness (not to be confused
|
||||
with the width value of the <code class="docutils literal notranslate"><span class="pre">rect</span></code> parameter)</p>
|
||||
<blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">==</span> <span class="pre">0</span></code>, nothing will be drawn</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">></span> <span class="pre">0</span></code>, (default is 1) used for line thickness</div>
|
||||
<div class="line">if <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre"><</span> <span class="pre">0</span></code>, same as <code class="docutils literal notranslate"><span class="pre">width</span> <span class="pre">==</span> <span class="pre">0</span></code></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>When using <code class="docutils literal notranslate"><span class="pre">width</span></code> values <code class="docutils literal notranslate"><span class="pre">></span> <span class="pre">1</span></code>, the edge lines will only grow
|
||||
inward from the original boundary of the <code class="docutils literal notranslate"><span class="pre">rect</span></code> parameter.</p>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the position of the given <code class="docutils literal notranslate"><span class="pre">rect</span></code>
|
||||
parameter and its width and height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.line">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">line</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.line" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw a straight line</span></div>
|
||||
<div class="line"><span class="signature">line(surface, color, start_pos, end_pos) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">line(surface, color, start_pos, end_pos, width=1) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws a straight line on the given surface. There are no endcaps. For thick
|
||||
lines the ends are squared off.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>start_pos</strong> (<em>tuple</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or
|
||||
</em><em>list</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or </em><a class="reference internal" href="math.html#pygame.math.Vector2" title="pygame.math.Vector2"><em>Vector2</em></a><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>)</em>) -- start position of the line, (x, y)</p></li>
|
||||
<li><p><strong>end_pos</strong> (<em>tuple</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or
|
||||
</em><em>list</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or </em><a class="reference internal" href="math.html#pygame.math.Vector2" title="pygame.math.Vector2"><em>Vector2</em></a><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>)</em>) -- end position of the line, (x, y)</p></li>
|
||||
<li><p><strong>width</strong> (<em>int</em>) -- <p>(optional) used for line thickness</p>
|
||||
<div class="line-block">
|
||||
<div class="line">if width >= 1, used for line thickness (default is 1)</div>
|
||||
<div class="line">if width < 1, nothing will be drawn</div>
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>When using <code class="docutils literal notranslate"><span class="pre">width</span></code> values <code class="docutils literal notranslate"><span class="pre">></span> <span class="pre">1</span></code>, lines will grow as follows.</p>
|
||||
<p>For odd <code class="docutils literal notranslate"><span class="pre">width</span></code> values, the thickness of each line grows with the
|
||||
original line being in the center.</p>
|
||||
<p>For even <code class="docutils literal notranslate"><span class="pre">width</span></code> values, the thickness of each line grows with the
|
||||
original line being offset from the center (as there is no exact
|
||||
center line drawn). As a result, lines with a slope < 1
|
||||
(horizontal-ish) will have 1 more pixel of thickness below the
|
||||
original line (in the y direction). Lines with a slope >= 1
|
||||
(vertical-ish) will have 1 more pixel of thickness to the right of
|
||||
the original line (in the x direction).</p>
|
||||
</div>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the <code class="docutils literal notranslate"><span class="pre">start_pos</span></code> parameter value (float
|
||||
values will be truncated) and its width and height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p><strong>TypeError</strong> -- if <code class="docutils literal notranslate"><span class="pre">start_pos</span></code> or <code class="docutils literal notranslate"><span class="pre">end_pos</span></code> is not a sequence of
|
||||
two numbers</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.lines">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">lines</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.lines" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw multiple contiguous straight line segments</span></div>
|
||||
<div class="line"><span class="signature">lines(surface, color, closed, points) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">lines(surface, color, closed, points, width=1) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws a sequence of contiguous straight lines on the given surface. There are
|
||||
no endcaps or miter joints. For thick lines the ends are squared off.
|
||||
Drawing thick lines with sharp corners can have undesired looking results.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>closed</strong> (<em>bool</em>) -- if <code class="docutils literal notranslate"><span class="pre">True</span></code> an additional line segment is drawn between
|
||||
the first and last points in the <code class="docutils literal notranslate"><span class="pre">points</span></code> sequence</p></li>
|
||||
<li><p><strong>points</strong> (<em>tuple</em><em>(</em><em>coordinate</em><em>) or </em><em>list</em><em>(</em><em>coordinate</em><em>)</em>) -- a sequence of 2 or more (x, y) coordinates, where each
|
||||
<em>coordinate</em> in the sequence must be a
|
||||
tuple/list/<a class="tooltip reference internal" href="math.html#pygame.math.Vector2" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.math.Vector2</span></code><span class="tooltip-content">a 2-Dimensional Vector</span></a> of 2 ints/floats and adjacent
|
||||
coordinates will be connected by a line segment, e.g. for the
|
||||
points <code class="docutils literal notranslate"><span class="pre">[(x1,</span> <span class="pre">y1),</span> <span class="pre">(x2,</span> <span class="pre">y2),</span> <span class="pre">(x3,</span> <span class="pre">y3)]</span></code> a line segment will be drawn
|
||||
from <code class="docutils literal notranslate"><span class="pre">(x1,</span> <span class="pre">y1)</span></code> to <code class="docutils literal notranslate"><span class="pre">(x2,</span> <span class="pre">y2)</span></code> and from <code class="docutils literal notranslate"><span class="pre">(x2,</span> <span class="pre">y2)</span></code> to <code class="docutils literal notranslate"><span class="pre">(x3,</span> <span class="pre">y3)</span></code>,
|
||||
additionally if the <code class="docutils literal notranslate"><span class="pre">closed</span></code> parameter is <code class="docutils literal notranslate"><span class="pre">True</span></code> another line segment
|
||||
will be drawn from <code class="docutils literal notranslate"><span class="pre">(x3,</span> <span class="pre">y3)</span></code> to <code class="docutils literal notranslate"><span class="pre">(x1,</span> <span class="pre">y1)</span></code></p></li>
|
||||
<li><p><strong>width</strong> (<em>int</em>) -- <p>(optional) used for line thickness</p>
|
||||
<div class="line-block">
|
||||
<div class="line">if width >= 1, used for line thickness (default is 1)</div>
|
||||
<div class="line">if width < 1, nothing will be drawn</div>
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>When using <code class="docutils literal notranslate"><span class="pre">width</span></code> values <code class="docutils literal notranslate"><span class="pre">></span> <span class="pre">1</span></code> refer to the <code class="docutils literal notranslate"><span class="pre">width</span></code> notes
|
||||
of <a class="reference internal" href="#pygame.draw.line" title="pygame.draw.line"><code class="xref py py-func docutils literal notranslate"><span class="pre">line()</span></code></a> for details on how thick lines grow.</p>
|
||||
</div>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the position of the first point in the
|
||||
<code class="docutils literal notranslate"><span class="pre">points</span></code> parameter (float values will be truncated) and its width and
|
||||
height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><ul class="simple">
|
||||
<li><p><strong>ValueError</strong> -- if <code class="docutils literal notranslate"><span class="pre">len(points)</span> <span class="pre"><</span> <span class="pre">2</span></code> (must have at least 2 points)</p></li>
|
||||
<li><p><strong>TypeError</strong> -- if <code class="docutils literal notranslate"><span class="pre">points</span></code> is not a sequence or <code class="docutils literal notranslate"><span class="pre">points</span></code> does not
|
||||
contain number pairs</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.aaline">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">aaline</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.aaline" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw a straight antialiased line</span></div>
|
||||
<div class="line"><span class="signature">aaline(surface, color, start_pos, end_pos) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">aaline(surface, color, start_pos, end_pos, blend=1) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws a straight antialiased line on the given surface.</p>
|
||||
<p>The line has a thickness of one pixel and the endpoints have a height and
|
||||
width of one pixel each.</p>
|
||||
<dl>
|
||||
<dt>The way a line and its endpoints are drawn:</dt><dd><p>If both endpoints are equal, only a single pixel is drawn (after
|
||||
rounding floats to nearest integer).</p>
|
||||
<p>Otherwise if the line is not steep (i.e. if the length along the x-axis
|
||||
is greater than the height along the y-axis):</p>
|
||||
<blockquote>
|
||||
<div><p>For each endpoint:</p>
|
||||
<blockquote>
|
||||
<div><p>If <code class="docutils literal notranslate"><span class="pre">x</span></code>, the endpoint's x-coordinate, is a whole number find
|
||||
which pixels would be covered by it and draw them.</p>
|
||||
<p>Otherwise:</p>
|
||||
<blockquote>
|
||||
<div><p>Calculate the position of the nearest point with a whole number
|
||||
for its x-coordinate, when extending the line past the
|
||||
endpoint.</p>
|
||||
<p>Find which pixels would be covered and how much by that point.</p>
|
||||
<p>If the endpoint is the left one, multiply the coverage by (1 -
|
||||
the decimal part of <code class="docutils literal notranslate"><span class="pre">x</span></code>).</p>
|
||||
<p>Otherwise multiply the coverage by the decimal part of <code class="docutils literal notranslate"><span class="pre">x</span></code>.</p>
|
||||
<p>Then draw those pixels.</p>
|
||||
<dl>
|
||||
<dt><em>e.g.:</em></dt><dd><div class="line-block">
|
||||
<div class="line">The left endpoint of the line <code class="docutils literal notranslate"><span class="pre">((1,</span> <span class="pre">1.3),</span> <span class="pre">(5,</span> <span class="pre">3))</span></code> would
|
||||
cover 70% of the pixel <code class="docutils literal notranslate"><span class="pre">(1,</span> <span class="pre">1)</span></code> and 30% of the pixel
|
||||
<code class="docutils literal notranslate"><span class="pre">(1,</span> <span class="pre">2)</span></code> while the right one would cover 100% of the
|
||||
pixel <code class="docutils literal notranslate"><span class="pre">(5,</span> <span class="pre">3)</span></code>.</div>
|
||||
<div class="line">The left endpoint of the line <code class="docutils literal notranslate"><span class="pre">((1.2,</span> <span class="pre">1.4),</span> <span class="pre">(4.6,</span> <span class="pre">3.1))</span></code>
|
||||
would cover 56% <em>(i.e. 0.8 * 70%)</em> of the pixel <code class="docutils literal notranslate"><span class="pre">(1,</span> <span class="pre">1)</span></code>
|
||||
and 24% <em>(i.e. 0.8 * 30%)</em> of the pixel <code class="docutils literal notranslate"><span class="pre">(1,</span> <span class="pre">2)</span></code> while
|
||||
the right one would cover 42% <em>(i.e. 0.6 * 70%)</em> of the
|
||||
pixel <code class="docutils literal notranslate"><span class="pre">(5,</span> <span class="pre">3)</span></code> and 18% <em>(i.e. 0.6 * 30%)</em> of the pixel
|
||||
<code class="docutils literal notranslate"><span class="pre">(5,</span> <span class="pre">4)</span></code> while the right</div>
|
||||
</div>
|
||||
</dd>
|
||||
</dl>
|
||||
</div></blockquote>
|
||||
</div></blockquote>
|
||||
<p>Then for each point between the endpoints, along the line, whose
|
||||
x-coordinate is a whole number:</p>
|
||||
<blockquote>
|
||||
<div><p>Find which pixels would be covered and how much by that point and
|
||||
draw them.</p>
|
||||
<dl>
|
||||
<dt><em>e.g.:</em></dt><dd><div class="line-block">
|
||||
<div class="line">The points along the line <code class="docutils literal notranslate"><span class="pre">((1,</span> <span class="pre">1),</span> <span class="pre">(4,</span> <span class="pre">2.5))</span></code> would be
|
||||
<code class="docutils literal notranslate"><span class="pre">(2,</span> <span class="pre">1.5)</span></code> and <code class="docutils literal notranslate"><span class="pre">(3,</span> <span class="pre">2)</span></code> and would cover 50% of the pixel
|
||||
<code class="docutils literal notranslate"><span class="pre">(2,</span> <span class="pre">1)</span></code>, 50% of the pixel <code class="docutils literal notranslate"><span class="pre">(2,</span> <span class="pre">2)</span></code> and 100% of the pixel
|
||||
<code class="docutils literal notranslate"><span class="pre">(3,</span> <span class="pre">2)</span></code>.</div>
|
||||
<div class="line">The points along the line <code class="docutils literal notranslate"><span class="pre">((1.2,</span> <span class="pre">1.4),</span> <span class="pre">(4.6,</span> <span class="pre">3.1))</span></code> would
|
||||
be <code class="docutils literal notranslate"><span class="pre">(2,</span> <span class="pre">1.8)</span></code> (covering 20% of the pixel <code class="docutils literal notranslate"><span class="pre">(2,</span> <span class="pre">1)</span></code> and 80%
|
||||
of the pixel <code class="docutils literal notranslate"><span class="pre">(2,</span> <span class="pre">2)</span></code>), <code class="docutils literal notranslate"><span class="pre">(3,</span> <span class="pre">2.3)</span></code> (covering 70% of the
|
||||
pixel <code class="docutils literal notranslate"><span class="pre">(3,</span> <span class="pre">2)</span></code> and 30% of the pixel <code class="docutils literal notranslate"><span class="pre">(3,</span> <span class="pre">3)</span></code>) and <code class="docutils literal notranslate"><span class="pre">(4,</span>
|
||||
<span class="pre">2.8)</span></code> (covering 20% of the pixel <code class="docutils literal notranslate"><span class="pre">(2,</span> <span class="pre">1)</span></code> and 80% of the
|
||||
pixel <code class="docutils literal notranslate"><span class="pre">(2,</span> <span class="pre">2)</span></code>)</div>
|
||||
</div>
|
||||
</dd>
|
||||
</dl>
|
||||
</div></blockquote>
|
||||
</div></blockquote>
|
||||
<p>Otherwise do the same for steep lines as for non-steep lines except
|
||||
along the y-axis instead of the x-axis (using <code class="docutils literal notranslate"><span class="pre">y</span></code> instead of <code class="docutils literal notranslate"><span class="pre">x</span></code>,
|
||||
top instead of left and bottom instead of right).</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Regarding float values for coordinates, a point with coordinate
|
||||
consisting of two whole numbers is considered being right in the center
|
||||
of said pixel (and having a height and width of 1 pixel would therefore
|
||||
completely cover it), while a point with coordinate where one (or both)
|
||||
of the numbers have non-zero decimal parts would be partially covering
|
||||
two (or four if both numbers have decimal parts) adjacent pixels, <em>e.g.</em>
|
||||
the point <code class="docutils literal notranslate"><span class="pre">(1.4,</span> <span class="pre">2)</span></code> covers 60% of the pixel <code class="docutils literal notranslate"><span class="pre">(1,</span> <span class="pre">2)</span></code> and 40% of the
|
||||
pixel <code class="docutils literal notranslate"><span class="pre">(2,2)</span></code>.</p>
|
||||
</div>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>start_pos</strong> (<em>tuple</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or
|
||||
</em><em>list</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or </em><a class="reference internal" href="math.html#pygame.math.Vector2" title="pygame.math.Vector2"><em>Vector2</em></a><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>)</em>) -- start position of the line, (x, y)</p></li>
|
||||
<li><p><strong>end_pos</strong> (<em>tuple</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or
|
||||
</em><em>list</em><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>) or </em><a class="reference internal" href="math.html#pygame.math.Vector2" title="pygame.math.Vector2"><em>Vector2</em></a><em>(</em><em>int</em><em> or </em><em>float</em><em>, </em><em>int</em><em> or </em><em>float</em><em>)</em>) -- end position of the line, (x, y)</p></li>
|
||||
<li><p><strong>blend</strong> (<em>int</em>) -- (optional) (deprecated) if non-zero (default) the line will be blended
|
||||
with the surface's existing pixel shades, otherwise it will overwrite them</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the <code class="docutils literal notranslate"><span class="pre">start_pos</span></code> parameter value (float
|
||||
values will be truncated) and its width and height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p><strong>TypeError</strong> -- if <code class="docutils literal notranslate"><span class="pre">start_pos</span></code> or <code class="docutils literal notranslate"><span class="pre">end_pos</span></code> is not a sequence of
|
||||
two numbers</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.draw.aalines">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.draw.</span></span><span class="sig-name descname"><span class="pre">aalines</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.draw.aalines" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw multiple contiguous straight antialiased line segments</span></div>
|
||||
<div class="line"><span class="signature">aalines(surface, color, closed, points) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">aalines(surface, color, closed, points, blend=1) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Draws a sequence of contiguous straight antialiased lines on the given
|
||||
surface.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>surface</strong> (<a class="reference internal" href="surface.html#pygame.Surface" title="pygame.Surface"><em>Surface</em></a>) -- surface to draw on</p></li>
|
||||
<li><p><strong>color</strong> (<a class="reference internal" href="color.html#pygame.Color" title="pygame.Color"><em>Color</em></a><em> or </em><em>int</em><em> or </em><em>tuple</em><em>(</em><em>int</em><em>, </em><em>int</em><em>, </em><em>int</em><em>, </em><em>[</em><em>int</em><em>]</em><em>)</em>) -- color to draw with, the alpha value is optional if using a
|
||||
tuple <code class="docutils literal notranslate"><span class="pre">(RGB[A])</span></code></p></li>
|
||||
<li><p><strong>closed</strong> (<em>bool</em>) -- if <code class="docutils literal notranslate"><span class="pre">True</span></code> an additional line segment is drawn between
|
||||
the first and last points in the <code class="docutils literal notranslate"><span class="pre">points</span></code> sequence</p></li>
|
||||
<li><p><strong>points</strong> (<em>tuple</em><em>(</em><em>coordinate</em><em>) or </em><em>list</em><em>(</em><em>coordinate</em><em>)</em>) -- a sequence of 2 or more (x, y) coordinates, where each
|
||||
<em>coordinate</em> in the sequence must be a
|
||||
tuple/list/<a class="tooltip reference internal" href="math.html#pygame.math.Vector2" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.math.Vector2</span></code><span class="tooltip-content">a 2-Dimensional Vector</span></a> of 2 ints/floats and adjacent
|
||||
coordinates will be connected by a line segment, e.g. for the
|
||||
points <code class="docutils literal notranslate"><span class="pre">[(x1,</span> <span class="pre">y1),</span> <span class="pre">(x2,</span> <span class="pre">y2),</span> <span class="pre">(x3,</span> <span class="pre">y3)]</span></code> a line segment will be drawn
|
||||
from <code class="docutils literal notranslate"><span class="pre">(x1,</span> <span class="pre">y1)</span></code> to <code class="docutils literal notranslate"><span class="pre">(x2,</span> <span class="pre">y2)</span></code> and from <code class="docutils literal notranslate"><span class="pre">(x2,</span> <span class="pre">y2)</span></code> to <code class="docutils literal notranslate"><span class="pre">(x3,</span> <span class="pre">y3)</span></code>,
|
||||
additionally if the <code class="docutils literal notranslate"><span class="pre">closed</span></code> parameter is <code class="docutils literal notranslate"><span class="pre">True</span></code> another line segment
|
||||
will be drawn from <code class="docutils literal notranslate"><span class="pre">(x3,</span> <span class="pre">y3)</span></code> to <code class="docutils literal notranslate"><span class="pre">(x1,</span> <span class="pre">y1)</span></code></p></li>
|
||||
<li><p><strong>blend</strong> (<em>int</em>) -- (optional) (deprecated) if non-zero (default) each line will be blended
|
||||
with the surface's existing pixel shades, otherwise the pixels will be
|
||||
overwritten</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>a rect bounding the changed pixels, if nothing is drawn the
|
||||
bounding rect's position will be the position of the first point in the
|
||||
<code class="docutils literal notranslate"><span class="pre">points</span></code> parameter (float values will be truncated) and its width and
|
||||
height will be 0</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="rect.html#pygame.Rect" title="pygame.Rect">Rect</a></p>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><ul class="simple">
|
||||
<li><p><strong>ValueError</strong> -- if <code class="docutils literal notranslate"><span class="pre">len(points)</span> <span class="pre"><</span> <span class="pre">2</span></code> (must have at least 2 points)</p></li>
|
||||
<li><p><strong>TypeError</strong> -- if <code class="docutils literal notranslate"><span class="pre">points</span></code> is not a sequence or <code class="docutils literal notranslate"><span class="pre">points</span></code> does not
|
||||
contain number pairs</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<figure class="align-default" id="id1">
|
||||
<img alt="draw module example" src="../_images/draw_module_example.png" />
|
||||
<figcaption>
|
||||
<p><span class="caption-text">Example code for draw module.</span><a class="headerlink" href="#id1" title="Permalink to this image">¶</a></p>
|
||||
</figcaption>
|
||||
</figure>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">pygame</span>
|
||||
<span class="kn">from</span> <span class="nn">math</span> <span class="kn">import</span> <span class="n">pi</span>
|
||||
|
||||
<span class="c1"># Initialize pygame</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
|
||||
|
||||
<span class="c1"># Set the height and width of the screen</span>
|
||||
<span class="n">size</span> <span class="o">=</span> <span class="p">[</span><span class="mi">400</span><span class="p">,</span> <span class="mi">300</span><span class="p">]</span>
|
||||
<span class="n">screen</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">display</span><span class="o">.</span><span class="n">set_mode</span><span class="p">(</span><span class="n">size</span><span class="p">)</span>
|
||||
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">display</span><span class="o">.</span><span class="n">set_caption</span><span class="p">(</span><span class="s2">"Example code for the draw module"</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Loop until the user clicks the close button.</span>
|
||||
<span class="n">done</span> <span class="o">=</span> <span class="kc">False</span>
|
||||
<span class="n">clock</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">time</span><span class="o">.</span><span class="n">Clock</span><span class="p">()</span>
|
||||
|
||||
<span class="k">while</span> <span class="ow">not</span> <span class="n">done</span><span class="p">:</span>
|
||||
<span class="c1"># This limits the while loop to a max of 60 times per second.</span>
|
||||
<span class="c1"># Leave this out and we will use all CPU we can.</span>
|
||||
<span class="n">clock</span><span class="o">.</span><span class="n">tick</span><span class="p">(</span><span class="mi">60</span><span class="p">)</span>
|
||||
|
||||
<span class="k">for</span> <span class="n">event</span> <span class="ow">in</span> <span class="n">pygame</span><span class="o">.</span><span class="n">event</span><span class="o">.</span><span class="n">get</span><span class="p">():</span> <span class="c1"># User did something</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">pygame</span><span class="o">.</span><span class="n">QUIT</span><span class="p">:</span> <span class="c1"># If user clicked close</span>
|
||||
<span class="n">done</span> <span class="o">=</span> <span class="kc">True</span> <span class="c1"># Flag that we are done so we exit this loop</span>
|
||||
|
||||
<span class="c1"># Clear the screen and set the screen background</span>
|
||||
<span class="n">screen</span><span class="o">.</span><span class="n">fill</span><span class="p">(</span><span class="s2">"white"</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw on the screen a green line from (0, 0) to (50, 30)</span>
|
||||
<span class="c1"># 5 pixels wide. Uses (r, g, b) color - medium sea green.</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">line</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="p">(</span><span class="mi">60</span><span class="p">,</span> <span class="mi">179</span><span class="p">,</span> <span class="mi">113</span><span class="p">),</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">50</span><span class="p">,</span> <span class="mi">30</span><span class="p">],</span> <span class="mi">5</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw on the screen a green line from (0, 50) to (50, 80)</span>
|
||||
<span class="c1"># Because it is an antialiased line, it is 1 pixel wide.</span>
|
||||
<span class="c1"># Uses (r, g, b) color - medium sea green.</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">aaline</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="p">(</span><span class="mi">60</span><span class="p">,</span> <span class="mi">179</span><span class="p">,</span> <span class="mi">113</span><span class="p">),</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">50</span><span class="p">],</span> <span class="p">[</span><span class="mi">50</span><span class="p">,</span> <span class="mi">80</span><span class="p">],</span> <span class="kc">True</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw on the screen 3 black lines, each 5 pixels wide.</span>
|
||||
<span class="c1"># The 'False' means the first and last points are not connected.</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">lines</span><span class="p">(</span>
|
||||
<span class="n">screen</span><span class="p">,</span> <span class="s2">"black"</span><span class="p">,</span> <span class="kc">False</span><span class="p">,</span> <span class="p">[[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">80</span><span class="p">],</span> <span class="p">[</span><span class="mi">50</span><span class="p">,</span> <span class="mi">90</span><span class="p">],</span> <span class="p">[</span><span class="mi">200</span><span class="p">,</span> <span class="mi">80</span><span class="p">],</span> <span class="p">[</span><span class="mi">220</span><span class="p">,</span> <span class="mi">30</span><span class="p">]],</span> <span class="mi">5</span>
|
||||
<span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw a rectangle outline</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">rect</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"black"</span><span class="p">,</span> <span class="p">[</span><span class="mi">75</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">20</span><span class="p">],</span> <span class="mi">2</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw a solid rectangle. Same color as "black" above, specified in a new way</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">rect</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="p">[</span><span class="mi">150</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">20</span><span class="p">])</span>
|
||||
|
||||
<span class="c1"># Draw a rectangle with rounded corners</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">rect</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"green"</span><span class="p">,</span> <span class="p">[</span><span class="mi">115</span><span class="p">,</span> <span class="mi">210</span><span class="p">,</span> <span class="mi">70</span><span class="p">,</span> <span class="mi">40</span><span class="p">],</span> <span class="mi">10</span><span class="p">,</span> <span class="n">border_radius</span><span class="o">=</span><span class="mi">15</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">rect</span><span class="p">(</span>
|
||||
<span class="n">screen</span><span class="p">,</span>
|
||||
<span class="s2">"red"</span><span class="p">,</span>
|
||||
<span class="p">[</span><span class="mi">135</span><span class="p">,</span> <span class="mi">260</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">30</span><span class="p">],</span>
|
||||
<span class="mi">0</span><span class="p">,</span>
|
||||
<span class="n">border_radius</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span>
|
||||
<span class="n">border_top_left_radius</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
|
||||
<span class="n">border_bottom_right_radius</span><span class="o">=</span><span class="mi">15</span><span class="p">,</span>
|
||||
<span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw an ellipse outline, using a rectangle as the outside boundaries</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">ellipse</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"red"</span><span class="p">,</span> <span class="p">[</span><span class="mi">225</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">20</span><span class="p">],</span> <span class="mi">2</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw an solid ellipse, using a rectangle as the outside boundaries</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">ellipse</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"red"</span><span class="p">,</span> <span class="p">[</span><span class="mi">300</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">20</span><span class="p">])</span>
|
||||
|
||||
<span class="c1"># This draws a triangle using the polygon command</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">polygon</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"black"</span><span class="p">,</span> <span class="p">[[</span><span class="mi">100</span><span class="p">,</span> <span class="mi">100</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">200</span><span class="p">],</span> <span class="p">[</span><span class="mi">200</span><span class="p">,</span> <span class="mi">200</span><span class="p">]],</span> <span class="mi">5</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw an arc as part of an ellipse.</span>
|
||||
<span class="c1"># Use radians to determine what angle to draw.</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">arc</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"black"</span><span class="p">,</span> <span class="p">[</span><span class="mi">210</span><span class="p">,</span> <span class="mi">75</span><span class="p">,</span> <span class="mi">150</span><span class="p">,</span> <span class="mi">125</span><span class="p">],</span> <span class="mi">0</span><span class="p">,</span> <span class="n">pi</span> <span class="o">/</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">arc</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"green"</span><span class="p">,</span> <span class="p">[</span><span class="mi">210</span><span class="p">,</span> <span class="mi">75</span><span class="p">,</span> <span class="mi">150</span><span class="p">,</span> <span class="mi">125</span><span class="p">],</span> <span class="n">pi</span> <span class="o">/</span> <span class="mi">2</span><span class="p">,</span> <span class="n">pi</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">arc</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"blue"</span><span class="p">,</span> <span class="p">[</span><span class="mi">210</span><span class="p">,</span> <span class="mi">75</span><span class="p">,</span> <span class="mi">150</span><span class="p">,</span> <span class="mi">125</span><span class="p">],</span> <span class="n">pi</span><span class="p">,</span> <span class="mi">3</span> <span class="o">*</span> <span class="n">pi</span> <span class="o">/</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">arc</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"red"</span><span class="p">,</span> <span class="p">[</span><span class="mi">210</span><span class="p">,</span> <span class="mi">75</span><span class="p">,</span> <span class="mi">150</span><span class="p">,</span> <span class="mi">125</span><span class="p">],</span> <span class="mi">3</span> <span class="o">*</span> <span class="n">pi</span> <span class="o">/</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span> <span class="o">*</span> <span class="n">pi</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw a circle</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">circle</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"blue"</span><span class="p">,</span> <span class="p">[</span><span class="mi">60</span><span class="p">,</span> <span class="mi">250</span><span class="p">],</span> <span class="mi">40</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Draw only one circle quadrant</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">circle</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"blue"</span><span class="p">,</span> <span class="p">[</span><span class="mi">250</span><span class="p">,</span> <span class="mi">250</span><span class="p">],</span> <span class="mi">40</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">draw_top_right</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">circle</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"red"</span><span class="p">,</span> <span class="p">[</span><span class="mi">250</span><span class="p">,</span> <span class="mi">250</span><span class="p">],</span> <span class="mi">40</span><span class="p">,</span> <span class="mi">30</span><span class="p">,</span> <span class="n">draw_top_left</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">circle</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"green"</span><span class="p">,</span> <span class="p">[</span><span class="mi">250</span><span class="p">,</span> <span class="mi">250</span><span class="p">],</span> <span class="mi">40</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="n">draw_bottom_left</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">draw</span><span class="o">.</span><span class="n">circle</span><span class="p">(</span><span class="n">screen</span><span class="p">,</span> <span class="s2">"black"</span><span class="p">,</span> <span class="p">[</span><span class="mi">250</span><span class="p">,</span> <span class="mi">250</span><span class="p">],</span> <span class="mi">40</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="n">draw_bottom_right</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Go ahead and update the screen with what we've drawn.</span>
|
||||
<span class="c1"># This MUST happen after all the other drawing commands.</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">display</span><span class="o">.</span><span class="n">flip</span><span class="p">()</span>
|
||||
|
||||
<span class="c1"># Be IDLE friendly</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/draw.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="event.html" title="pygame.event"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="display.html" title="pygame.display"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.draw</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,796 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.event — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.examples" href="examples.html" />
|
||||
<link rel="prev" title="pygame.draw" href="draw.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.event">
|
||||
<span id="pygame-event"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.event</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for interacting with events and queues</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.pump">pygame.event.pump</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>internally process pygame event handlers</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.get">pygame.event.get</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get events from the queue</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.poll">pygame.event.poll</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get a single event from the queue</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.wait">pygame.event.wait</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>wait for a single event from the queue</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.peek">pygame.event.peek</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if event types are waiting on the queue</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.clear">pygame.event.clear</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>remove all events from the queue</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.event_name">pygame.event.event_name</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the string name from an event id</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.set_blocked">pygame.event.set_blocked</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>control which events are allowed on the queue</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.set_allowed">pygame.event.set_allowed</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>control which events are allowed on the queue</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.get_blocked">pygame.event.get_blocked</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if a type of event is blocked from the queue</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.set_grab">pygame.event.set_grab</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>control the sharing of input devices with other applications</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.get_grab">pygame.event.get_grab</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if the program is sharing input devices</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.set_keyboard_grab">pygame.event.set_keyboard_grab</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>grab enables capture of system keyboard shortcuts like Alt+Tab or the Meta/Super key.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.get_keyboard_grab">pygame.event.get_keyboard_grab</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the current keyboard grab state</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.post">pygame.event.post</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>place a new event on the queue</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.custom_type">pygame.event.custom_type</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>make custom user event type</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.Event">pygame.event.Event</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>pygame object for representing events</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Pygame handles all its event messaging through an event queue. The routines in
|
||||
this module help you manage that event queue. The input queue is heavily
|
||||
dependent on the <a class="tooltip reference internal" href="display.html#module-pygame.display" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.display</span></code><span class="tooltip-content">pygame module to control the display window and screen</span></a> module. If the display has not been
|
||||
initialized and a video mode not set, the event queue may not work properly.</p>
|
||||
<p>The event queue has an upper limit on the number of events it can hold. When
|
||||
the queue becomes full new events are quietly dropped. To prevent lost events,
|
||||
especially input events which signal a quit command, your program must handle
|
||||
events every frame (with <code class="docutils literal notranslate"><span class="pre">pygame.event.get()</span></code>, <code class="docutils literal notranslate"><span class="pre">pygame.event.pump()</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.event.wait()</span></code>, <code class="docutils literal notranslate"><span class="pre">pygame.event.peek()</span></code> or <code class="docutils literal notranslate"><span class="pre">pygame.event.clear()</span></code>)
|
||||
and process them. Not handling events may cause your system to decide your
|
||||
program has locked up. To speed up queue processing use
|
||||
<a class="tooltip reference internal" href="#pygame.event.set_blocked" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.set_blocked()</span></code><span class="tooltip-content">control which events are allowed on the queue</span></a> to limit which events get queued.</p>
|
||||
<p>To get the state of various input devices, you can forego the event queue and
|
||||
access the input devices directly with their appropriate modules:
|
||||
<a class="tooltip reference internal" href="mouse.html#module-pygame.mouse" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mouse</span></code><span class="tooltip-content">pygame module to work with the mouse</span></a>, <a class="tooltip reference internal" href="key.html#module-pygame.key" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.key</span></code><span class="tooltip-content">pygame module to work with the keyboard</span></a>, and <a class="tooltip reference internal" href="joystick.html#module-pygame.joystick" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.joystick</span></code><span class="tooltip-content">Pygame module for interacting with joysticks, gamepads, and trackballs.</span></a>. If you use
|
||||
this method, remember that pygame requires some form of communication with the
|
||||
system window manager and other parts of the platform. To keep pygame in sync
|
||||
with the system, you will need to call <a class="tooltip reference internal" href="#pygame.event.pump" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.pump()</span></code><span class="tooltip-content">internally process pygame event handlers</span></a> to keep
|
||||
everything current. Usually, this should be called once per game loop.
|
||||
Note: Joysticks will not send any events until the device has been initialized.</p>
|
||||
<p>The event queue contains <a class="tooltip reference internal" href="#pygame.event.Event" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.event.Event</span></code><span class="tooltip-content">pygame object for representing events</span></a> event objects.
|
||||
There are a variety of ways to access the queued events, from simply
|
||||
checking for the existence of events, to grabbing them directly off the stack.
|
||||
The event queue also offers some simple filtering which can slightly help
|
||||
performance by blocking certain event types from the queue. Use
|
||||
<a class="tooltip reference internal" href="#pygame.event.set_allowed" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.set_allowed()</span></code><span class="tooltip-content">control which events are allowed on the queue</span></a> and <a class="tooltip reference internal" href="#pygame.event.set_blocked" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.set_blocked()</span></code><span class="tooltip-content">control which events are allowed on the queue</span></a> to
|
||||
change this filtering. By default, all event types can be placed on the queue.</p>
|
||||
<p>All <a class="tooltip reference internal" href="#pygame.event.Event" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.event.Event</span></code><span class="tooltip-content">pygame object for representing events</span></a> instances contain an event type identifier
|
||||
and attributes specific to that event type. The event type identifier is
|
||||
accessible as the <a class="tooltip reference internal" href="#pygame.event.Event.type" title=""><code class="xref py py-attr docutils literal notranslate"><span class="pre">pygame.event.Event.type</span></code><span class="tooltip-content">event type identifier.</span></a> property. Any of the
|
||||
event specific attributes can be accessed through the
|
||||
<a class="tooltip reference internal" href="#pygame.event.Event.__dict__" title=""><code class="xref py py-attr docutils literal notranslate"><span class="pre">pygame.event.Event.__dict__</span></code><span class="tooltip-content">event attribute dictionary</span></a> attribute or directly as an attribute
|
||||
of the event object (as member lookups are passed through to the object's
|
||||
dictionary values). The event object has no method functions. Users can create
|
||||
their own new events with the <a class="tooltip reference internal" href="#pygame.event.Event" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.Event()</span></code><span class="tooltip-content">pygame object for representing events</span></a> function.</p>
|
||||
<p>The event type identifier is in between the values of <code class="docutils literal notranslate"><span class="pre">NOEVENT</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">NUMEVENTS</span></code>. User defined events should have a value in the inclusive range
|
||||
of <code class="docutils literal notranslate"><span class="pre">USEREVENT</span></code> to <code class="docutils literal notranslate"><span class="pre">NUMEVENTS</span> <span class="pre">-</span> <span class="pre">1</span></code>. User defined events can get a custom
|
||||
event number with <a class="tooltip reference internal" href="#pygame.event.custom_type" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.custom_type()</span></code><span class="tooltip-content">make custom user event type</span></a>.
|
||||
It is recommended all user events follow this system.</p>
|
||||
<p>Events support equality and inequality comparisons. Two events are equal if
|
||||
they are the same type and have identical attribute values.</p>
|
||||
<p>While debugging and experimenting, you can print an event object for a quick
|
||||
display of its type and members. The function <a class="tooltip reference internal" href="#pygame.event.event_name" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.event_name()</span></code><span class="tooltip-content">get the string name from an event id</span></a>
|
||||
can be used to get a string representing the name of the event type.</p>
|
||||
<p>Events that come from the system will have a guaranteed set of member
|
||||
attributes based on the type. The following is a list event types with their
|
||||
specific attributes.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">QUIT</span> <span class="n">none</span>
|
||||
<span class="n">ACTIVEEVENT</span> <span class="n">gain</span><span class="p">,</span> <span class="n">state</span>
|
||||
<span class="n">KEYDOWN</span> <span class="n">key</span><span class="p">,</span> <span class="n">mod</span><span class="p">,</span> <span class="n">unicode</span><span class="p">,</span> <span class="n">scancode</span>
|
||||
<span class="n">KEYUP</span> <span class="n">key</span><span class="p">,</span> <span class="n">mod</span><span class="p">,</span> <span class="n">unicode</span><span class="p">,</span> <span class="n">scancode</span>
|
||||
<span class="n">MOUSEMOTION</span> <span class="n">pos</span><span class="p">,</span> <span class="n">rel</span><span class="p">,</span> <span class="n">buttons</span><span class="p">,</span> <span class="n">touch</span>
|
||||
<span class="n">MOUSEBUTTONUP</span> <span class="n">pos</span><span class="p">,</span> <span class="n">button</span><span class="p">,</span> <span class="n">touch</span>
|
||||
<span class="n">MOUSEBUTTONDOWN</span> <span class="n">pos</span><span class="p">,</span> <span class="n">button</span><span class="p">,</span> <span class="n">touch</span>
|
||||
<span class="n">JOYAXISMOTION</span> <span class="n">joy</span> <span class="p">(</span><span class="n">deprecated</span><span class="p">),</span> <span class="n">instance_id</span><span class="p">,</span> <span class="n">axis</span><span class="p">,</span> <span class="n">value</span>
|
||||
<span class="n">JOYBALLMOTION</span> <span class="n">joy</span> <span class="p">(</span><span class="n">deprecated</span><span class="p">),</span> <span class="n">instance_id</span><span class="p">,</span> <span class="n">ball</span><span class="p">,</span> <span class="n">rel</span>
|
||||
<span class="n">JOYHATMOTION</span> <span class="n">joy</span> <span class="p">(</span><span class="n">deprecated</span><span class="p">),</span> <span class="n">instance_id</span><span class="p">,</span> <span class="n">hat</span><span class="p">,</span> <span class="n">value</span>
|
||||
<span class="n">JOYBUTTONUP</span> <span class="n">joy</span> <span class="p">(</span><span class="n">deprecated</span><span class="p">),</span> <span class="n">instance_id</span><span class="p">,</span> <span class="n">button</span>
|
||||
<span class="n">JOYBUTTONDOWN</span> <span class="n">joy</span> <span class="p">(</span><span class="n">deprecated</span><span class="p">),</span> <span class="n">instance_id</span><span class="p">,</span> <span class="n">button</span>
|
||||
<span class="n">VIDEORESIZE</span> <span class="n">size</span><span class="p">,</span> <span class="n">w</span><span class="p">,</span> <span class="n">h</span>
|
||||
<span class="n">VIDEOEXPOSE</span> <span class="n">none</span>
|
||||
<span class="n">USEREVENT</span> <span class="n">code</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>The <code class="docutils literal notranslate"><span class="pre">joy</span></code> attribute was deprecated, <code class="docutils literal notranslate"><span class="pre">instance_id</span></code> was added.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.1: </span>The <code class="docutils literal notranslate"><span class="pre">unicode</span></code> attribute was added to <code class="docutils literal notranslate"><span class="pre">KEYUP</span></code> event.</p>
|
||||
</div>
|
||||
<p>Note that <code class="docutils literal notranslate"><span class="pre">ACTIVEEVENT</span></code>, <code class="docutils literal notranslate"><span class="pre">VIDEORESIZE</span></code> and <code class="docutils literal notranslate"><span class="pre">VIDEOEXPOSE</span></code> are considered
|
||||
as "legacy" events, the use of pygame2 <code class="docutils literal notranslate"><span class="pre">WINDOWEVENT</span></code> API is recommended over
|
||||
the use of this older API.</p>
|
||||
<p>You can also find a list of constants for keyboard keys
|
||||
<a class="reference internal" href="key.html#key-constants-label"><span class="std std-ref">here</span></a>.</p>
|
||||
<p>A keyboard event occurs when a key is pressed (<code class="docutils literal notranslate"><span class="pre">KEYDOWN</span></code>) and when a key is released (<code class="docutils literal notranslate"><span class="pre">KEYUP</span></code>)
|
||||
The <code class="docutils literal notranslate"><span class="pre">key</span></code> attribute of keyboard events contains the value of what key was pressed or released.
|
||||
The <code class="docutils literal notranslate"><span class="pre">mod</span></code> attribute contains information about the state of keyboard modifiers (SHIFT, CTRL, ALT, etc.).
|
||||
The <code class="docutils literal notranslate"><span class="pre">unicode</span></code> attribute stores the 16-bit unicode value of the key that was pressed or released.
|
||||
The <code class="docutils literal notranslate"><span class="pre">scancode</span></code> attribute represents the physical location of a key on the keyboard.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">ACTIVEEVENT</span></code> contains information about the application gaining or losing focus. The <code class="docutils literal notranslate"><span class="pre">gain</span></code> attribute
|
||||
will be 1 if the mouse enters the window, otherwise <code class="docutils literal notranslate"><span class="pre">gain</span></code> will be 0. The <code class="docutils literal notranslate"><span class="pre">state</span></code> attribute will have a
|
||||
value of <code class="docutils literal notranslate"><span class="pre">SDL_APPMOUSEFOCUS</span></code> if mouse focus was gained/lost, <code class="docutils literal notranslate"><span class="pre">SDL_APPINPUTFOCUS</span></code> if the application loses
|
||||
or gains keyboard focus, or <code class="docutils literal notranslate"><span class="pre">SDL_APPACTIVE</span></code> if the application is minimized (<code class="docutils literal notranslate"><span class="pre">gain</span></code> will be 0) or restored.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<p>When compiled with SDL2, pygame has these additional events and their
|
||||
attributes.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">AUDIODEVICEADDED</span> <span class="n">which</span><span class="p">,</span> <span class="n">iscapture</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.4</span><span class="p">)</span>
|
||||
<span class="n">AUDIODEVICEREMOVED</span> <span class="n">which</span><span class="p">,</span> <span class="n">iscapture</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.4</span><span class="p">)</span>
|
||||
<span class="n">FINGERMOTION</span> <span class="n">touch_id</span><span class="p">,</span> <span class="n">finger_id</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">dx</span><span class="p">,</span> <span class="n">dy</span>
|
||||
<span class="n">FINGERDOWN</span> <span class="n">touch_id</span><span class="p">,</span> <span class="n">finger_id</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">dx</span><span class="p">,</span> <span class="n">dy</span>
|
||||
<span class="n">FINGERUP</span> <span class="n">touch_id</span><span class="p">,</span> <span class="n">finger_id</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">dx</span><span class="p">,</span> <span class="n">dy</span>
|
||||
<span class="n">MOUSEWHEEL</span> <span class="n">which</span><span class="p">,</span> <span class="n">flipped</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">touch</span><span class="p">,</span> <span class="n">precise_x</span><span class="p">,</span> <span class="n">precise_y</span>
|
||||
<span class="n">MULTIGESTURE</span> <span class="n">touch_id</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">pinched</span><span class="p">,</span> <span class="n">rotated</span><span class="p">,</span> <span class="n">num_fingers</span>
|
||||
<span class="n">TEXTEDITING</span> <span class="n">text</span><span class="p">,</span> <span class="n">start</span><span class="p">,</span> <span class="n">length</span>
|
||||
<span class="n">TEXTINPUT</span> <span class="n">text</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.5.</span></p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2: </span>Fixed amount horizontal scroll (x, positive to the right and negative to the left).</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2: </span>The <code class="docutils literal notranslate"><span class="pre">touch</span></code> attribute was added to all the <code class="docutils literal notranslate"><span class="pre">MOUSE</span></code> events.</p>
|
||||
</div>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">touch</span></code> attribute of <code class="docutils literal notranslate"><span class="pre">MOUSE</span></code> events indicates whether or not the events were generated
|
||||
by a touch input device, and not a real mouse. You might want to ignore such events, if your application
|
||||
already handles <code class="docutils literal notranslate"><span class="pre">FINGERMOTION</span></code>, <code class="docutils literal notranslate"><span class="pre">FINGERDOWN</span></code> and <code class="docutils literal notranslate"><span class="pre">FINGERUP</span></code> events.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3: </span>Added <code class="docutils literal notranslate"><span class="pre">precise_x</span></code> and <code class="docutils literal notranslate"><span class="pre">precise_y</span></code> to <code class="docutils literal notranslate"><span class="pre">MOUSEWHEEL</span></code> events</p>
|
||||
</div>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">MOUSEWHEEL</span></code> event occurs whenever the mouse wheel is moved.
|
||||
The <code class="docutils literal notranslate"><span class="pre">which</span></code> attribute determines if the event was generated from a touch input device vs an actual
|
||||
mousewheel.
|
||||
The <code class="docutils literal notranslate"><span class="pre">preciseX</span></code> attribute contains a float with the amount scrolled horizontally (positive to the right,
|
||||
negative to the left).
|
||||
The <code class="docutils literal notranslate"><span class="pre">preciseY</span></code> attribute contains a float with the amount scrolled vertically (positive away from user,
|
||||
negative towards user).
|
||||
The <code class="docutils literal notranslate"><span class="pre">flipped</span></code> attribute determines if the values in x and y will be opposite or not. If <code class="docutils literal notranslate"><span class="pre">SDL_MOUSEWHEEL_FLIPPED</span></code>
|
||||
is defined, the direction of x and y will be opposite.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">TEXTEDITING</span></code> event is triggered when a user activates an input method via hotkey or selecting an
|
||||
input method in a GUI and starts typing</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">which</span></code> attribute for <code class="docutils literal notranslate"><span class="pre">AUDIODEVICE*</span></code> events is an integer representing the index for new audio
|
||||
devices that are added. <code class="docutils literal notranslate"><span class="pre">AUDIODEVICE*</span></code> events are used to update audio settings or device list.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<p>Many new events were introduced in pygame 2.</p>
|
||||
<p>pygame can recognize text or files dropped in its window. If a file
|
||||
is dropped, <code class="docutils literal notranslate"><span class="pre">DROPFILE</span></code> event will be sent, <code class="docutils literal notranslate"><span class="pre">file</span></code> will be its path.
|
||||
The <code class="docutils literal notranslate"><span class="pre">DROPTEXT</span></code> event is only supported on X11.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">MIDIIN</span></code> and <code class="docutils literal notranslate"><span class="pre">MIDIOUT</span></code> are events reserved for <a class="tooltip reference internal" href="midi.html#module-pygame.midi" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code><span class="tooltip-content">pygame module for interacting with midi input and output.</span></a> use.
|
||||
<code class="docutils literal notranslate"><span class="pre">MIDI*</span></code> events differ from <code class="docutils literal notranslate"><span class="pre">AUDIODEVICE*</span></code> events in that AUDIODEVICE
|
||||
events are triggered when there is a state change related to an audio
|
||||
input/output device.</p>
|
||||
<p>pygame 2 also supports controller hot-plugging</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Event</span> <span class="n">name</span> <span class="n">Attributes</span> <span class="ow">and</span> <span class="n">notes</span>
|
||||
|
||||
<span class="n">DROPFILE</span> <span class="n">file</span>
|
||||
<span class="n">DROPBEGIN</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.5</span><span class="p">)</span>
|
||||
<span class="n">DROPCOMPLETE</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.5</span><span class="p">)</span>
|
||||
<span class="n">DROPTEXT</span> <span class="n">text</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.5</span><span class="p">)</span>
|
||||
<span class="n">MIDIIN</span>
|
||||
<span class="n">MIDIOUT</span>
|
||||
<span class="n">CONTROLLERDEVICEADDED</span> <span class="n">device_index</span>
|
||||
<span class="n">JOYDEVICEADDED</span> <span class="n">device_index</span>
|
||||
<span class="n">CONTROLLERDEVICEREMOVED</span> <span class="n">instance_id</span>
|
||||
<span class="n">JOYDEVICEREMOVED</span> <span class="n">instance_id</span>
|
||||
<span class="n">CONTROLLERDEVICEREMAPPED</span> <span class="n">instance_id</span>
|
||||
<span class="n">KEYMAPCHANGED</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.4</span><span class="p">)</span>
|
||||
<span class="n">CLIPBOARDUPDATE</span>
|
||||
<span class="n">RENDER_TARGETS_RESET</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.2</span><span class="p">)</span>
|
||||
<span class="n">RENDER_DEVICE_RESET</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.4</span><span class="p">)</span>
|
||||
<span class="n">LOCALECHANGED</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.14</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Also in this version, <code class="docutils literal notranslate"><span class="pre">instance_id</span></code> attributes were added to joystick events,
|
||||
and the <code class="docutils literal notranslate"><span class="pre">joy</span></code> attribute was deprecated.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">KEYMAPCHANGED</span></code> is a type of an event sent when keymap changes due to a
|
||||
system event such as an input language or keyboard layout change.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">CLIPBOARDUPDATE</span></code> is an event sent when clipboard changes. This can still
|
||||
be considered as an experimental feature, some kinds of clipboard changes might
|
||||
not trigger this event.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">LOCALECHANGED</span></code> is an event sent when user locale changes</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3: </span><code class="docutils literal notranslate"><span class="pre">KEYMAPCHANGED</span></code>, <code class="docutils literal notranslate"><span class="pre">CLIPBOARDUPDATE</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">RENDER_TARGETS_RESET</span></code>, <code class="docutils literal notranslate"><span class="pre">RENDER_DEVICE_RESET</span></code> and <code class="docutils literal notranslate"><span class="pre">LOCALECHANGED</span></code></p>
|
||||
</div>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<p>Since pygame 2.0.1, there are a new set of events, called window events.
|
||||
Here is a list of all window events, along with a short description</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Event</span> <span class="nb">type</span> <span class="n">Short</span> <span class="n">description</span>
|
||||
|
||||
<span class="n">WINDOWSHOWN</span> <span class="n">Window</span> <span class="n">became</span> <span class="n">shown</span>
|
||||
<span class="n">WINDOWHIDDEN</span> <span class="n">Window</span> <span class="n">became</span> <span class="n">hidden</span>
|
||||
<span class="n">WINDOWEXPOSED</span> <span class="n">Window</span> <span class="n">got</span> <span class="n">updated</span> <span class="n">by</span> <span class="n">some</span> <span class="n">external</span> <span class="n">event</span>
|
||||
<span class="n">WINDOWMOVED</span> <span class="n">Window</span> <span class="n">got</span> <span class="n">moved</span>
|
||||
<span class="n">WINDOWRESIZED</span> <span class="n">Window</span> <span class="n">got</span> <span class="n">resized</span>
|
||||
<span class="n">WINDOWSIZECHANGED</span> <span class="n">Window</span> <span class="n">changed</span> <span class="n">its</span> <span class="n">size</span>
|
||||
<span class="n">WINDOWMINIMIZED</span> <span class="n">Window</span> <span class="n">was</span> <span class="n">minimized</span>
|
||||
<span class="n">WINDOWMAXIMIZED</span> <span class="n">Window</span> <span class="n">was</span> <span class="n">maximized</span>
|
||||
<span class="n">WINDOWRESTORED</span> <span class="n">Window</span> <span class="n">was</span> <span class="n">restored</span>
|
||||
<span class="n">WINDOWENTER</span> <span class="n">Mouse</span> <span class="n">entered</span> <span class="n">the</span> <span class="n">window</span>
|
||||
<span class="n">WINDOWLEAVE</span> <span class="n">Mouse</span> <span class="n">left</span> <span class="n">the</span> <span class="n">window</span>
|
||||
<span class="n">WINDOWFOCUSGAINED</span> <span class="n">Window</span> <span class="n">gained</span> <span class="n">focus</span>
|
||||
<span class="n">WINDOWFOCUSLOST</span> <span class="n">Window</span> <span class="n">lost</span> <span class="n">focus</span>
|
||||
<span class="n">WINDOWCLOSE</span> <span class="n">Window</span> <span class="n">was</span> <span class="n">closed</span>
|
||||
<span class="n">WINDOWTAKEFOCUS</span> <span class="n">Window</span> <span class="n">was</span> <span class="n">offered</span> <span class="n">focus</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.5</span><span class="p">)</span>
|
||||
<span class="n">WINDOWHITTEST</span> <span class="n">Window</span> <span class="n">has</span> <span class="n">a</span> <span class="n">special</span> <span class="n">hit</span> <span class="n">test</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.5</span><span class="p">)</span>
|
||||
<span class="n">WINDOWICCPROFCHANGED</span> <span class="n">Window</span> <span class="n">ICC</span> <span class="n">profile</span> <span class="n">changed</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.18</span><span class="p">)</span>
|
||||
<span class="n">WINDOWDISPLAYCHANGED</span> <span class="n">Window</span> <span class="n">moved</span> <span class="n">on</span> <span class="n">a</span> <span class="n">new</span> <span class="n">display</span> <span class="p">(</span><span class="n">SDL</span> <span class="n">backend</span> <span class="o">>=</span> <span class="mf">2.0.18</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">WINDOWMOVED</span></code>, <code class="docutils literal notranslate"><span class="pre">WINDOWRESIZED</span></code> and <code class="docutils literal notranslate"><span class="pre">WINDOWSIZECHANGED</span></code> have <code class="docutils literal notranslate"><span class="pre">x</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">y</span></code> attributes, <code class="docutils literal notranslate"><span class="pre">WINDOWDISPLAYCHANGED</span></code> has a <code class="docutils literal notranslate"><span class="pre">display_index</span></code> attribute.
|
||||
All windowevents have a <code class="docutils literal notranslate"><span class="pre">window</span></code> attribute.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1.</span></p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3: </span><code class="docutils literal notranslate"><span class="pre">WINDOWICCPROFCHANGED</span></code> and <code class="docutils literal notranslate"><span class="pre">WINDOWDISPLAYCHANGED</span></code></p>
|
||||
</div>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<p>On Android, the following events can be generated</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Event</span> <span class="nb">type</span> <span class="n">Short</span> <span class="n">description</span>
|
||||
|
||||
<span class="n">APP_TERMINATING</span> <span class="n">OS</span> <span class="ow">is</span> <span class="n">terminating</span> <span class="n">the</span> <span class="n">application</span>
|
||||
<span class="n">APP_LOWMEMORY</span> <span class="n">OS</span> <span class="ow">is</span> <span class="n">low</span> <span class="n">on</span> <span class="n">memory</span><span class="p">,</span> <span class="k">try</span> <span class="n">to</span> <span class="n">free</span> <span class="n">memory</span> <span class="k">if</span> <span class="n">possible</span>
|
||||
<span class="n">APP_WILLENTERBACKGROUND</span> <span class="n">Application</span> <span class="ow">is</span> <span class="n">entering</span> <span class="n">background</span>
|
||||
<span class="n">APP_DIDENTERBACKGROUND</span> <span class="n">Application</span> <span class="n">entered</span> <span class="n">background</span>
|
||||
<span class="n">APP_WILLENTERFOREGROUND</span> <span class="n">Application</span> <span class="ow">is</span> <span class="n">entering</span> <span class="n">foreground</span>
|
||||
<span class="n">APP_DIDENTERFOREGROUND</span> <span class="n">Application</span> <span class="n">entered</span> <span class="n">foreground</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.pump">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">pump</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.pump" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">internally process pygame event handlers</span></div>
|
||||
<div class="line"><span class="signature">pump() -> None</span></div>
|
||||
</div>
|
||||
<p>For each frame of your game, you will need to make some sort of call to the
|
||||
event queue. This ensures your program can internally interact with the rest
|
||||
of the operating system. If you are not using other event functions in your
|
||||
game, you should call <code class="docutils literal notranslate"><span class="pre">pygame.event.pump()</span></code> to allow pygame to handle
|
||||
internal actions.</p>
|
||||
<p>This function is not necessary if your program is consistently processing
|
||||
events on the queue through the other <a class="tooltip reference internal" href="#module-pygame.event" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.event</span></code><span class="tooltip-content">pygame module for interacting with events and queues</span></a> functions.</p>
|
||||
<p>There are important things that must be dealt with internally in the event
|
||||
queue. The main window may need to be repainted or respond to the system. If
|
||||
you fail to make a call to the event queue for too long, the system may
|
||||
decide your program has locked up.</p>
|
||||
<div class="admonition caution">
|
||||
<p class="admonition-title">Caution</p>
|
||||
<p>This function should only be called in the thread that initialized <a class="tooltip reference internal" href="display.html#module-pygame.display" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.display</span></code><span class="tooltip-content">pygame module to control the display window and screen</span></a>.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.get">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.get" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get events from the queue</span></div>
|
||||
<div class="line"><span class="signature">get(eventtype=None) -> Eventlist</span></div>
|
||||
<div class="line"><span class="signature">get(eventtype=None, pump=True) -> Eventlist</span></div>
|
||||
<div class="line"><span class="signature">get(eventtype=None, pump=True, exclude=None) -> Eventlist</span></div>
|
||||
</div>
|
||||
<p>This will get all the messages and remove them from the queue. If a type or
|
||||
sequence of types is given only those messages will be removed from the
|
||||
queue and returned.</p>
|
||||
<p>If a type or sequence of types is passed in the <code class="docutils literal notranslate"><span class="pre">exclude</span></code> argument
|
||||
instead, then all only <em>other</em> messages will be removed from the queue. If
|
||||
an <code class="docutils literal notranslate"><span class="pre">exclude</span></code> parameter is passed, the <code class="docutils literal notranslate"><span class="pre">eventtype</span></code> parameter <em>must</em> be
|
||||
None.</p>
|
||||
<p>If you are only taking specific events from the queue, be aware that the
|
||||
queue could eventually fill up with the events you are not interested.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">pump</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), then <a class="tooltip reference internal" href="#pygame.event.pump" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.pump()</span></code><span class="tooltip-content">internally process pygame event handlers</span></a> will be called.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.5: </span>Added <code class="docutils literal notranslate"><span class="pre">pump</span></code> argument</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2: </span>Added <code class="docutils literal notranslate"><span class="pre">exclude</span></code> argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.poll">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">poll</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.poll" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get a single event from the queue</span></div>
|
||||
<div class="line"><span class="signature">poll() -> Event instance</span></div>
|
||||
</div>
|
||||
<p>Returns a single event from the queue. If the event queue is empty an event
|
||||
of type <code class="docutils literal notranslate"><span class="pre">pygame.NOEVENT</span></code> will be returned immediately. The returned event
|
||||
is removed from the queue.</p>
|
||||
<div class="admonition caution">
|
||||
<p class="admonition-title">Caution</p>
|
||||
<p>This function should only be called in the thread that initialized <a class="tooltip reference internal" href="display.html#module-pygame.display" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.display</span></code><span class="tooltip-content">pygame module to control the display window and screen</span></a>.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.wait">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">wait</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.wait" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">wait for a single event from the queue</span></div>
|
||||
<div class="line"><span class="signature">wait() -> Event instance</span></div>
|
||||
<div class="line"><span class="signature">wait(timeout) -> Event instance</span></div>
|
||||
</div>
|
||||
<p>Returns a single event from the queue. If the queue is empty this function
|
||||
will wait until one is created. From pygame 2.0.0, if a <code class="docutils literal notranslate"><span class="pre">timeout</span></code> argument
|
||||
is given, the function will return an event of type <code class="docutils literal notranslate"><span class="pre">pygame.NOEVENT</span></code>
|
||||
if no events enter the queue in <code class="docutils literal notranslate"><span class="pre">timeout</span></code> milliseconds. The event is removed
|
||||
from the queue once it has been returned. While the program is waiting it will
|
||||
sleep in an idle state. This is important for programs that want to share the
|
||||
system with other applications.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0.dev13: </span>Added <code class="docutils literal notranslate"><span class="pre">timeout</span></code> argument</p>
|
||||
</div>
|
||||
<div class="admonition caution">
|
||||
<p class="admonition-title">Caution</p>
|
||||
<p>This function should only be called in the thread that initialized <a class="tooltip reference internal" href="display.html#module-pygame.display" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.display</span></code><span class="tooltip-content">pygame module to control the display window and screen</span></a>.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.peek">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">peek</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.peek" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if event types are waiting on the queue</span></div>
|
||||
<div class="line"><span class="signature">peek(eventtype=None) -> bool</span></div>
|
||||
<div class="line"><span class="signature">peek(eventtype=None, pump=True) -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if there are any events of the given type waiting on the
|
||||
queue. If a sequence of event types is passed, this will return <code class="docutils literal notranslate"><span class="pre">True</span></code> if
|
||||
any of those events are on the queue.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">pump</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), then <a class="tooltip reference internal" href="#pygame.event.pump" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.pump()</span></code><span class="tooltip-content">internally process pygame event handlers</span></a> will be called.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.5: </span>Added <code class="docutils literal notranslate"><span class="pre">pump</span></code> argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.clear">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">clear</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.clear" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">remove all events from the queue</span></div>
|
||||
<div class="line"><span class="signature">clear(eventtype=None) -> None</span></div>
|
||||
<div class="line"><span class="signature">clear(eventtype=None, pump=True) -> None</span></div>
|
||||
</div>
|
||||
<p>Removes all events from the queue. If <code class="docutils literal notranslate"><span class="pre">eventtype</span></code> is given, removes the given event
|
||||
or sequence of events. This has the same effect as <a class="tooltip reference internal" href="#pygame.event.get" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.get()</span></code><span class="tooltip-content">get events from the queue</span></a> except <code class="docutils literal notranslate"><span class="pre">None</span></code>
|
||||
is returned. It can be slightly more efficient when clearing a full event queue.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">pump</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), then <a class="tooltip reference internal" href="#pygame.event.pump" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.pump()</span></code><span class="tooltip-content">internally process pygame event handlers</span></a> will be called.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.5: </span>Added <code class="docutils literal notranslate"><span class="pre">pump</span></code> argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.event_name">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">event_name</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.event_name" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the string name from an event id</span></div>
|
||||
<div class="line"><span class="signature">event_name(type) -> string</span></div>
|
||||
</div>
|
||||
<p>Returns a string representing the name (in CapWords style) of the given
|
||||
event type.</p>
|
||||
<p>"UserEvent" is returned for all values in the user event id range.
|
||||
"Unknown" is returned when the event type does not exist.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.set_blocked">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">set_blocked</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.set_blocked" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">control which events are allowed on the queue</span></div>
|
||||
<div class="line"><span class="signature">set_blocked(type) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_blocked(typelist) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_blocked(None) -> None</span></div>
|
||||
</div>
|
||||
<p>The given event types are not allowed to appear on the event queue. By
|
||||
default all events can be placed on the queue. It is safe to disable an
|
||||
event type multiple times.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">None</span></code> is passed as the argument, ALL of the event types are blocked
|
||||
from being placed on the queue.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.set_allowed">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">set_allowed</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.set_allowed" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">control which events are allowed on the queue</span></div>
|
||||
<div class="line"><span class="signature">set_allowed(type) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_allowed(typelist) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_allowed(None) -> None</span></div>
|
||||
</div>
|
||||
<p>The given event types are allowed to appear on the event queue. By default,
|
||||
all event types can be placed on the queue. It is safe to enable an event
|
||||
type multiple times.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">None</span></code> is passed as the argument, ALL of the event types are allowed
|
||||
to be placed on the queue.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.get_blocked">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">get_blocked</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.get_blocked" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if a type of event is blocked from the queue</span></div>
|
||||
<div class="line"><span class="signature">get_blocked(type) -> bool</span></div>
|
||||
<div class="line"><span class="signature">get_blocked(typelist) -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if the given event type is blocked from the queue. If a
|
||||
sequence of event types is passed, this will return <code class="docutils literal notranslate"><span class="pre">True</span></code> if any of those
|
||||
event types are blocked.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.set_grab">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">set_grab</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.set_grab" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">control the sharing of input devices with other applications</span></div>
|
||||
<div class="line"><span class="signature">set_grab(bool) -> None</span></div>
|
||||
</div>
|
||||
<p>When your program runs in a windowed environment, it will share the mouse
|
||||
and keyboard devices with other applications that have focus. If your
|
||||
program sets the event grab to <code class="docutils literal notranslate"><span class="pre">True</span></code>, it will lock all input into your
|
||||
program.</p>
|
||||
<p>It is best to not always grab the input, since it prevents the user from
|
||||
doing other things on their system.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.get_grab">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">get_grab</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.get_grab" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if the program is sharing input devices</span></div>
|
||||
<div class="line"><span class="signature">get_grab() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> when the input events are grabbed for this application.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.set_keyboard_grab">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">set_keyboard_grab</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.set_keyboard_grab" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">grab enables capture of system keyboard shortcuts like Alt+Tab or the Meta/Super key.</span></div>
|
||||
<div class="line"><span class="signature">set_keyboard_grab(bool) -> None</span></div>
|
||||
</div>
|
||||
<p>Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or the Meta/Super key.
|
||||
Note that not all system keyboard shortcuts can be captured by applications (one example is Ctrl+Alt+Del on Windows).
|
||||
This is primarily intended for specialized applications such as VNC clients or VM frontends. Normal games should not use keyboard grab.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.5.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.get_keyboard_grab">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">get_keyboard_grab</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.get_keyboard_grab" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the current keyboard grab state</span></div>
|
||||
<div class="line"><span class="signature">get_keyboard_grab() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> when keyboard grab is enabled.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.5.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.post">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">post</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.post" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">place a new event on the queue</span></div>
|
||||
<div class="line"><span class="signature">post(Event) -> bool</span></div>
|
||||
</div>
|
||||
<p>Places the given event at the end of the event queue.</p>
|
||||
<p>This is usually used for placing custom events on the event queue.
|
||||
Any type of event can be posted, and the events posted can have any attributes.</p>
|
||||
<p>This returns a boolean on whether the event was posted or not. Blocked events
|
||||
cannot be posted, and this function returns <code class="docutils literal notranslate"><span class="pre">False</span></code> if you try to post them.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.1: </span>returns a boolean, previously returned <code class="docutils literal notranslate"><span class="pre">None</span></code></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.custom_type">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">custom_type</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.event.custom_type" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">make custom user event type</span></div>
|
||||
<div class="line"><span class="signature">custom_type() -> int</span></div>
|
||||
</div>
|
||||
<p>Reserves a <code class="docutils literal notranslate"><span class="pre">pygame.USEREVENT</span></code> for a custom use.</p>
|
||||
<p>If too many events are made a <a class="tooltip reference internal" href="pygame.html#pygame.error" title=""><code class="xref py py-exc docutils literal notranslate"><span class="pre">pygame.error</span></code><span class="tooltip-content">standard pygame exception</span></a> is raised.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.dev3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.Event">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.event.</span></span><span class="sig-name descname"><span class="pre">Event</span></span><a class="headerlink" href="#pygame.event.Event" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame object for representing events</span></div>
|
||||
<div class="line"><span class="signature">Event(type, dict) -> Event</span></div>
|
||||
<div class="line"><span class="signature">Event(type, **attributes) -> Event</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.Event.type">pygame.event.Event.type</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>event type identifier.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="event.html#pygame.event.Event.__dict__">pygame.event.Event.__dict__</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>event attribute dictionary</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>A pygame object used for representing an event. <code class="docutils literal notranslate"><span class="pre">Event</span></code> instances
|
||||
support attribute assignment and deletion.</p>
|
||||
<p>When creating the object, the attributes may come from a dictionary
|
||||
argument with string keys or from keyword arguments.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>From version 2.1.3 <code class="docutils literal notranslate"><span class="pre">EventType</span></code> is an alias for <code class="docutils literal notranslate"><span class="pre">Event</span></code>. Beforehand,
|
||||
<code class="docutils literal notranslate"><span class="pre">Event</span></code> was a function that returned <code class="docutils literal notranslate"><span class="pre">EventType</span></code> instances. Use of
|
||||
<code class="docutils literal notranslate"><span class="pre">Event</span></code> is preferred over <code class="docutils literal notranslate"><span class="pre">EventType</span></code> wherever it is possible, as
|
||||
the latter could be deprecated in a future version.</p>
|
||||
</div>
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.Event.type">
|
||||
<span class="sig-name descname"><span class="pre">type</span></span><a class="headerlink" href="#pygame.event.Event.type" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">event type identifier.</span></div>
|
||||
<div class="line"><span class="signature">type -> int</span></div>
|
||||
</div>
|
||||
<p>Read-only. The event type identifier. For user created event
|
||||
objects, this is the <code class="docutils literal notranslate"><span class="pre">type</span></code> argument passed to
|
||||
<a class="tooltip reference internal" href="#pygame.event.Event" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.Event()</span></code><span class="tooltip-content">pygame object for representing events</span></a>.</p>
|
||||
<p>For example, some predefined event identifiers are <code class="docutils literal notranslate"><span class="pre">QUIT</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">MOUSEMOTION</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.event.Event.__dict__">
|
||||
<span class="sig-name descname"><span class="pre">__dict__</span></span><a class="headerlink" href="#pygame.event.Event.__dict__" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">event attribute dictionary</span></div>
|
||||
<div class="line"><span class="signature">__dict__ -> dict</span></div>
|
||||
</div>
|
||||
<p>Read-only. The event type specific attributes of an event. The
|
||||
<code class="docutils literal notranslate"><span class="pre">dict</span></code> attribute is a synonym for backward compatibility.</p>
|
||||
<p>For example, the attributes of a <code class="docutils literal notranslate"><span class="pre">KEYDOWN</span></code> event would be <code class="docutils literal notranslate"><span class="pre">unicode</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">key</span></code>, and <code class="docutils literal notranslate"><span class="pre">mod</span></code></p>
|
||||
</dd></dl>
|
||||
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2: </span>Mutable attributes.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/event.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="examples.html" title="pygame.examples"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="draw.html" title="pygame.draw"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.event</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,703 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.examples — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.fastevent" href="fastevent.html" />
|
||||
<link rel="prev" title="pygame.event" href="event.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.examples">
|
||||
<span id="pygame-examples"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.examples</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">module of example programs</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.aliens.main">pygame.examples.aliens.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>play the full aliens example</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.stars.main">pygame.examples.stars.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>run a simple starfield example</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.chimp.main">pygame.examples.chimp.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>hit the moving chimp</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.moveit.main">pygame.examples.moveit.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display animated objects on the screen</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.fonty.main">pygame.examples.fonty.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>run a font rendering example</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.freetype_misc.main">pygame.examples.freetype_misc.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>run a FreeType rendering example</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.vgrade.main">pygame.examples.vgrade.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display a vertical gradient</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.eventlist.main">pygame.examples.eventlist.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display pygame events</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.arraydemo.main">pygame.examples.arraydemo.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>show various surfarray effects</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.sound.main">pygame.examples.sound.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>load and play a sound</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.sound_array_demos.main">pygame.examples.sound_array_demos.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>play various sndarray effects</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.liquid.main">pygame.examples.liquid.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display an animated liquid effect</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.glcube.main">pygame.examples.glcube.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display an animated 3D cube using OpenGL</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.scrap_clipboard.main">pygame.examples.scrap_clipboard.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>access the clipboard</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.mask.main">pygame.examples.mask.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display multiple images bounce off each other using collision detection</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.testsprite.main">pygame.examples.testsprite.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>show lots of sprites moving around</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.headless_no_windows_needed.main">pygame.examples.headless_no_windows_needed.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>write an image file that is smoothscaled copy of an input file</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.joystick.main">pygame.examples.joystick.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>demonstrate joystick functionality</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.blend_fill.main">pygame.examples.blend_fill.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>demonstrate the various surface.fill method blend options</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.blit_blends.main">pygame.examples.blit_blends.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>uses alternative additive fill to that of surface.fill</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.cursors.main">pygame.examples.cursors.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display two different custom cursors</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.pixelarray.main">pygame.examples.pixelarray.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display various pixelarray generated effects</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.scaletest.main">pygame.examples.scaletest.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>interactively scale an image using smoothscale</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.midi.main">pygame.examples.midi.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>run a midi example</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.scroll.main">pygame.examples.scroll.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>run a Surface.scroll example that shows a magnified image</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.camera.main">pygame.examples.camera.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>display video captured live from an attached camera</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="examples.html#pygame.examples.playmus.main">pygame.examples.playmus.main</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>play an audio file</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>These examples should help get you started with pygame. Here is a brief rundown
|
||||
of what you get. The source code for these examples is in the public domain.
|
||||
Feel free to use for your own projects.</p>
|
||||
<p>There are several ways to run the examples. First they can be run as
|
||||
stand-alone programs. Second they can be imported and their <code class="docutils literal notranslate"><span class="pre">main()</span></code> methods
|
||||
called (see below). Finally, the easiest way is to use the python -m option:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pygame</span><span class="o">.</span><span class="n">examples</span><span class="o">.<</span><span class="n">example</span> <span class="n">name</span><span class="o">></span> <span class="o"><</span><span class="n">example</span> <span class="n">arguments</span><span class="o">></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>eg:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pygame</span><span class="o">.</span><span class="n">examples</span><span class="o">.</span><span class="n">scaletest</span> <span class="n">someimage</span><span class="o">.</span><span class="n">png</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Resources such as images and sounds for the examples are found in the
|
||||
pygame/examples/data subdirectory.</p>
|
||||
<p>You can find where the example files are installed by using the following
|
||||
commands inside the python interpreter.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">pygame.examples.scaletest</span>
|
||||
<span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">examples</span><span class="o">.</span><span class="n">scaletest</span><span class="o">.</span><span class="vm">__file__</span>
|
||||
<span class="go">'/usr/lib/python2.6/site-packages/pygame/examples/scaletest.py'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>On each OS and version of Python the location will be slightly different.
|
||||
For example on Windows it might be in 'C:/Python26/Lib/site-packages/pygame/examples/'
|
||||
On Mac OS X it might be in '/Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/pygame/examples/'</p>
|
||||
<p>You can also run the examples in the python interpreter by calling each modules main() function.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">pygame.examples.scaletest</span>
|
||||
<span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">examples</span><span class="o">.</span><span class="n">scaletest</span><span class="o">.</span><span class="n">main</span><span class="p">()</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>We're always on the lookout for more examples and/or example requests. Code
|
||||
like this is probably the best way to start getting involved with python
|
||||
gaming.</p>
|
||||
<p>examples as a package is new to pygame 1.9.0. But most of the examples came with
|
||||
pygame much earlier.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.aliens.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">aliens.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.aliens.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">play the full aliens example</span></div>
|
||||
<div class="line"><span class="signature">aliens.main() -> None</span></div>
|
||||
</div>
|
||||
<p>This started off as a port of the <code class="docutils literal notranslate"><span class="pre">SDL</span></code> demonstration, Aliens. Now it has
|
||||
evolved into something sort of resembling fun. This demonstrates a lot of
|
||||
different uses of sprites and optimized blitting. Also transparency,
|
||||
colorkeys, fonts, sound, music, joystick, and more. (PS, my high score is
|
||||
117! goodluck)</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.stars.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">stars.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.stars.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">run a simple starfield example</span></div>
|
||||
<div class="line"><span class="signature">stars.main() -> None</span></div>
|
||||
</div>
|
||||
<p>A simple starfield example. You can change the center of perspective by
|
||||
leftclicking the mouse on the screen.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.chimp.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">chimp.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.chimp.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">hit the moving chimp</span></div>
|
||||
<div class="line"><span class="signature">chimp.main() -> None</span></div>
|
||||
</div>
|
||||
<p>This simple example is derived from the line-by-line tutorial that comes
|
||||
with pygame. It is based on a 'popular' web banner. Note there are comments
|
||||
here, but for the full explanation, follow along in the tutorial.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.moveit.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">moveit.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.moveit.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display animated objects on the screen</span></div>
|
||||
<div class="line"><span class="signature">moveit.main() -> None</span></div>
|
||||
</div>
|
||||
<p>This is the full and final example from the Pygame Tutorial, "How Do I Make
|
||||
It Move". It creates 10 objects and animates them on the screen.</p>
|
||||
<p>Note it's a bit scant on error checking, but it's easy to read. :]
|
||||
Fortunately, this is python, and we needn't wrestle with a pile of error
|
||||
codes.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.fonty.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">fonty.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.fonty.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">run a font rendering example</span></div>
|
||||
<div class="line"><span class="signature">fonty.main() -> None</span></div>
|
||||
</div>
|
||||
<p>Super quick, super simple application demonstrating the different ways to
|
||||
render fonts with the font module</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.freetype_misc.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">freetype_misc.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.freetype_misc.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">run a FreeType rendering example</span></div>
|
||||
<div class="line"><span class="signature">freetype_misc.main() -> None</span></div>
|
||||
</div>
|
||||
<p>A showcase of rendering features the <a class="tooltip reference internal" href="freetype.html#pygame.freetype.Font" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.freetype.Font</span></code><span class="tooltip-content">Create a new Font instance from a supported font file.</span></a>
|
||||
class provides in addition to those available with <a class="tooltip reference internal" href="font.html#pygame.font.Font" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.font.Font</span></code><span class="tooltip-content">create a new Font object from a file</span></a>.
|
||||
It is a demonstration of direct to surface rendering, with vertical text
|
||||
and rotated text, opaque text and semi transparent text, horizontally
|
||||
stretched text and vertically stretched text.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.vgrade.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">vgrade.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.vgrade.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display a vertical gradient</span></div>
|
||||
<div class="line"><span class="signature">vgrade.main() -> None</span></div>
|
||||
</div>
|
||||
<p>Demonstrates creating a vertical gradient with pixelcopy and NumPy python.
|
||||
The app will create a new gradient every half second and report the time
|
||||
needed to create and display the image. If you're not prepared to start
|
||||
working with the NumPy arrays, don't worry about the source for this one :]</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.eventlist.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">eventlist.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.eventlist.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display pygame events</span></div>
|
||||
<div class="line"><span class="signature">eventlist.main() -> None</span></div>
|
||||
</div>
|
||||
<p>Eventlist is a sloppy style of pygame, but is a handy tool for learning
|
||||
about pygame events and input. At the top of the screen are the state of
|
||||
several device values, and a scrolling list of events are displayed on the
|
||||
bottom.</p>
|
||||
<p>This is not quality 'ui' code at all, but you can see how to implement very
|
||||
non-interactive status displays, or even a crude text output control.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.arraydemo.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">arraydemo.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.arraydemo.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">show various surfarray effects</span></div>
|
||||
<div class="line"><span class="signature">arraydemo.main(arraytype=None) -> None</span></div>
|
||||
</div>
|
||||
<p>Another example filled with various surfarray effects. It requires the
|
||||
surfarray and image modules to be installed. This little demo can also make
|
||||
a good starting point for any of your own tests with surfarray</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">arraytype</span></code> parameter is deprecated; passing any value besides 'numpy'
|
||||
will raise ValueError.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.sound.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">sound.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.sound.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">load and play a sound</span></div>
|
||||
<div class="line"><span class="signature">sound.main(file_path=None) -> None</span></div>
|
||||
</div>
|
||||
<p>Extremely basic testing of the mixer module. Load a sound and play it. All
|
||||
from the command shell, no graphics.</p>
|
||||
<p>If provided, use the audio file 'file_path', otherwise use a default file.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">sound.py</span></code> optional command line argument: an audio file</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.sound_array_demos.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">sound_array_demos.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.sound_array_demos.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">play various sndarray effects</span></div>
|
||||
<div class="line"><span class="signature">sound_array_demos.main(arraytype=None) -> None</span></div>
|
||||
</div>
|
||||
<p>Uses sndarray and NumPy to create offset faded copies of the
|
||||
original sound. Currently it just uses hardcoded values for the number of
|
||||
echoes and the delay. Easy for you to recreate as needed.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">arraytype</span></code> parameter is deprecated; passing any value besides 'numpy'
|
||||
will raise ValueError.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.liquid.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">liquid.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.liquid.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display an animated liquid effect</span></div>
|
||||
<div class="line"><span class="signature">liquid.main() -> None</span></div>
|
||||
</div>
|
||||
<p>This example was created in a quick comparison with the BlitzBasic gaming
|
||||
language. Nonetheless, it demonstrates a quick 8-bit setup (with colormap).</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.glcube.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">glcube.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.glcube.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display an animated 3D cube using OpenGL</span></div>
|
||||
<div class="line"><span class="signature">glcube.main() -> None</span></div>
|
||||
</div>
|
||||
<p>Using PyOpenGL and pygame, this creates a spinning 3D multicolored cube.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.scrap_clipboard.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">scrap_clipboard.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.scrap_clipboard.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">access the clipboard</span></div>
|
||||
<div class="line"><span class="signature">scrap_clipboard.main() -> None</span></div>
|
||||
</div>
|
||||
<p>A simple demonstration example for the clipboard support.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.mask.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">mask.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.mask.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display multiple images bounce off each other using collision detection</span></div>
|
||||
<div class="line"><span class="signature">mask.main(*args) -> None</span></div>
|
||||
</div>
|
||||
<p>Positional arguments:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">one</span> <span class="ow">or</span> <span class="n">more</span> <span class="n">image</span> <span class="n">file</span> <span class="n">names</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This <code class="docutils literal notranslate"><span class="pre">pygame.masks</span></code> demo will display multiple moving sprites bouncing off
|
||||
each other. More than one sprite image can be provided.</p>
|
||||
<p>If run as a program then <code class="docutils literal notranslate"><span class="pre">mask.py</span></code> takes one or more image files as
|
||||
command line arguments.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.testsprite.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">testsprite.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.testsprite.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">show lots of sprites moving around</span></div>
|
||||
<div class="line"><span class="signature">testsprite.main(update_rects = True, use_static = False, use_FastRenderGroup = False, screen_dims = [640, 480], use_alpha = False, flags = 0) -> None</span></div>
|
||||
</div>
|
||||
<p>Optional keyword arguments:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">update_rects</span> <span class="o">-</span> <span class="n">use</span> <span class="n">the</span> <span class="n">RenderUpdate</span> <span class="n">sprite</span> <span class="n">group</span> <span class="k">class</span>
|
||||
<span class="nc">use_static</span> <span class="o">-</span> <span class="n">include</span> <span class="n">non</span><span class="o">-</span><span class="n">moving</span> <span class="n">images</span>
|
||||
<span class="n">use_FastRenderGroup</span> <span class="o">-</span> <span class="n">Use</span> <span class="n">the</span> <span class="n">FastRenderGroup</span> <span class="n">sprite</span> <span class="n">group</span>
|
||||
<span class="n">screen_dims</span> <span class="o">-</span> <span class="n">pygame</span> <span class="n">window</span> <span class="n">dimensions</span>
|
||||
<span class="n">use_alpha</span> <span class="o">-</span> <span class="n">use</span> <span class="n">alpha</span> <span class="n">blending</span>
|
||||
<span class="n">flags</span> <span class="o">-</span> <span class="n">additional</span> <span class="n">display</span> <span class="n">mode</span> <span class="n">flags</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Like the <code class="docutils literal notranslate"><span class="pre">testsprite.c</span></code> that comes with SDL, this pygame version shows
|
||||
lots of sprites moving around.</p>
|
||||
<p>If run as a stand-alone program then no command line arguments are taken.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.headless_no_windows_needed.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">headless_no_windows_needed.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.headless_no_windows_needed.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">write an image file that is smoothscaled copy of an input file</span></div>
|
||||
<div class="line"><span class="signature">headless_no_windows_needed.main(fin, fout, w, h) -> None</span></div>
|
||||
</div>
|
||||
<p>arguments:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fin</span> <span class="o">-</span> <span class="n">name</span> <span class="n">of</span> <span class="n">an</span> <span class="nb">input</span> <span class="n">image</span> <span class="n">file</span>
|
||||
<span class="n">fout</span> <span class="o">-</span> <span class="n">name</span> <span class="n">of</span> <span class="n">the</span> <span class="n">output</span> <span class="n">file</span> <span class="n">to</span> <span class="n">create</span><span class="o">/</span><span class="n">overwrite</span>
|
||||
<span class="n">w</span><span class="p">,</span> <span class="n">h</span> <span class="o">-</span> <span class="n">size</span> <span class="n">of</span> <span class="n">the</span> <span class="n">rescaled</span> <span class="n">image</span><span class="p">,</span> <span class="k">as</span> <span class="n">integer</span> <span class="n">width</span> <span class="ow">and</span> <span class="n">height</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>How to use pygame with no windowing system, like on headless servers.</p>
|
||||
<p>Thumbnail generation with scaling is an example of what you can do with
|
||||
pygame.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>: the pygame scale function uses MMX/SSE if available, and can be
|
||||
run in multiple threads.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">headless_no_windows_needed.py</span></code> is run as a program it takes the
|
||||
following command line arguments:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">scale</span> <span class="n">inputimage</span> <span class="n">outputimage</span> <span class="n">new_width</span> <span class="n">new_height</span>
|
||||
<span class="n">eg</span><span class="o">.</span> <span class="o">-</span><span class="n">scale</span> <span class="ow">in</span><span class="o">.</span><span class="n">png</span> <span class="n">outpng</span> <span class="mi">50</span> <span class="mi">50</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.joystick.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">joystick.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.joystick.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">demonstrate joystick functionality</span></div>
|
||||
<div class="line"><span class="signature">joystick.main() -> None</span></div>
|
||||
</div>
|
||||
<p>A demo showing full joystick support.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.blend_fill.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">blend_fill.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.blend_fill.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">demonstrate the various surface.fill method blend options</span></div>
|
||||
<div class="line"><span class="signature">blend_fill.main() -> None</span></div>
|
||||
</div>
|
||||
<p>A interactive demo that lets one choose which BLEND_xxx option to apply to a
|
||||
surface.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.blit_blends.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">blit_blends.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.blit_blends.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">uses alternative additive fill to that of surface.fill</span></div>
|
||||
<div class="line"><span class="signature">blit_blends.main() -> None</span></div>
|
||||
</div>
|
||||
<p>Fake additive blending. Using NumPy. it doesn't clamp. Press r,g,b Somewhat
|
||||
like blend_fill.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.cursors.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">cursors.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.cursors.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display two different custom cursors</span></div>
|
||||
<div class="line"><span class="signature">cursors.main() -> None</span></div>
|
||||
</div>
|
||||
<p>Display an arrow or circle with crossbar cursor.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.pixelarray.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">pixelarray.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.pixelarray.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display various pixelarray generated effects</span></div>
|
||||
<div class="line"><span class="signature">pixelarray.main() -> None</span></div>
|
||||
</div>
|
||||
<p>Display various pixelarray generated effects.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.scaletest.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">scaletest.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.scaletest.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">interactively scale an image using smoothscale</span></div>
|
||||
<div class="line"><span class="signature">scaletest.main(imagefile, convert_alpha=False, run_speed_test=True) -> None</span></div>
|
||||
</div>
|
||||
<p>arguments:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">imagefile</span> <span class="o">-</span> <span class="n">file</span> <span class="n">name</span> <span class="n">of</span> <span class="n">source</span> <span class="n">image</span> <span class="p">(</span><span class="n">required</span><span class="p">)</span>
|
||||
<span class="n">convert_alpha</span> <span class="o">-</span> <span class="n">use</span> <span class="n">convert_alpha</span><span class="p">()</span> <span class="n">on</span> <span class="n">the</span> <span class="n">surf</span> <span class="p">(</span><span class="n">default</span> <span class="kc">False</span><span class="p">)</span>
|
||||
<span class="n">run_speed_test</span> <span class="o">-</span> <span class="p">(</span><span class="n">default</span> <span class="kc">False</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>A smoothscale example that resized an image on the screen. Vertical and
|
||||
horizontal arrow keys are used to change the width and height of the
|
||||
displayed image. If the convert_alpha option is True then the source image
|
||||
is forced to have source alpha, whether or not the original images does. If
|
||||
run_speed_test is True then a background timing test is performed instead of
|
||||
the interactive scaler.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">scaletest.py</span></code> is run as a program then the command line options are:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ImageFile</span> <span class="p">[</span><span class="o">-</span><span class="n">t</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">convert_alpha</span><span class="p">]</span>
|
||||
<span class="p">[</span><span class="o">-</span><span class="n">t</span><span class="p">]</span> <span class="o">=</span> <span class="n">Run</span> <span class="n">Speed</span> <span class="n">Test</span>
|
||||
<span class="p">[</span><span class="o">-</span><span class="n">convert_alpha</span><span class="p">]</span> <span class="o">=</span> <span class="n">Use</span> <span class="n">convert_alpha</span><span class="p">()</span> <span class="n">on</span> <span class="n">the</span> <span class="n">surf</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.midi.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">midi.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.midi.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">run a midi example</span></div>
|
||||
<div class="line"><span class="signature">midi.main(mode='output', device_id=None) -> None</span></div>
|
||||
</div>
|
||||
<p>Arguments:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mode</span> <span class="o">-</span> <span class="k">if</span> <span class="s1">'output'</span> <span class="n">run</span> <span class="n">a</span> <span class="n">midi</span> <span class="n">keyboard</span> <span class="n">output</span> <span class="n">example</span>
|
||||
<span class="s1">'input'</span> <span class="n">run</span> <span class="n">a</span> <span class="n">midi</span> <span class="n">event</span> <span class="n">logger</span> <span class="nb">input</span> <span class="n">example</span>
|
||||
<span class="s1">'list'</span> <span class="nb">list</span> <span class="n">available</span> <span class="n">midi</span> <span class="n">devices</span>
|
||||
<span class="p">(</span><span class="n">default</span> <span class="s1">'output'</span><span class="p">)</span>
|
||||
<span class="n">device_id</span> <span class="o">-</span> <span class="n">midi</span> <span class="n">device</span> <span class="n">number</span><span class="p">;</span> <span class="k">if</span> <span class="kc">None</span> <span class="n">then</span> <span class="n">use</span> <span class="n">the</span> <span class="n">default</span> <span class="n">midi</span> <span class="nb">input</span> <span class="ow">or</span>
|
||||
<span class="n">output</span> <span class="n">device</span> <span class="k">for</span> <span class="n">the</span> <span class="n">system</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The output example shows how to translate mouse clicks or computer keyboard
|
||||
events into midi notes. It implements a rudimentary button widget and state
|
||||
machine.</p>
|
||||
<p>The input example shows how to translate midi input to pygame events.</p>
|
||||
<p>With the use of a virtual midi patch cord the output and input examples can
|
||||
be run as separate processes and connected so the keyboard output is
|
||||
displayed on a console.</p>
|
||||
<p>new to pygame 1.9.0</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.scroll.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">scroll.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.scroll.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">run a Surface.scroll example that shows a magnified image</span></div>
|
||||
<div class="line"><span class="signature">scroll.main(image_file=None) -> None</span></div>
|
||||
</div>
|
||||
<p>This example shows a scrollable image that has a zoom factor of eight. It
|
||||
uses the <a class="reference internal" href="surface.html#pygame.Surface.scroll" title="pygame.Surface.scroll"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Surface.scroll()</span></code></a>
|
||||
function to shift the image on the display surface.
|
||||
A clip rectangle protects a margin area. If called as a function,
|
||||
the example accepts an optional image file path. If run as a program it
|
||||
takes an optional file path command line argument. If no file is provided a
|
||||
default image file is used.</p>
|
||||
<p>When running click on a black triangle to move one pixel in the direction
|
||||
the triangle points. Or use the arrow keys. Close the window or press
|
||||
<code class="docutils literal notranslate"><span class="pre">ESC</span></code> to quit.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.camera.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">camera.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.camera.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">display video captured live from an attached camera</span></div>
|
||||
<div class="line"><span class="signature">camera.main() -> None</span></div>
|
||||
</div>
|
||||
<p>A simple live video player, it uses the first available camera it finds on
|
||||
the system.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.examples.playmus.main">
|
||||
<span class="sig-prename descclassname"><span class="pre">playmus.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.examples.playmus.main" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">play an audio file</span></div>
|
||||
<div class="line"><span class="signature">playmus.main(file_path) -> None</span></div>
|
||||
</div>
|
||||
<p>A simple music player with window and keyboard playback control. Playback can
|
||||
be paused and rewound to the beginning.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/examples.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="fastevent.html" title="pygame.fastevent"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="event.html" title="pygame.event"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.examples</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,277 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.fastevent — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.font" href="font.html" />
|
||||
<link rel="prev" title="pygame.examples" href="examples.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.fastevent">
|
||||
<span id="pygame-fastevent"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.fastevent</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for interacting with events and queues</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="fastevent.html#pygame.fastevent.init">pygame.fastevent.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>initialize pygame.fastevent</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="fastevent.html#pygame.fastevent.get_init">pygame.fastevent.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns True if the fastevent module is currently initialized</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="fastevent.html#pygame.fastevent.pump">pygame.fastevent.pump</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>internally process pygame event handlers</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="fastevent.html#pygame.fastevent.wait">pygame.fastevent.wait</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>wait for an event</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="fastevent.html#pygame.fastevent.poll">pygame.fastevent.poll</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get an available event</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="fastevent.html#pygame.fastevent.get">pygame.fastevent.get</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get all events from the queue</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="fastevent.html#pygame.fastevent.post">pygame.fastevent.post</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>place an event on the queue</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>IMPORTANT NOTE: THIS MODULE IS DEPRECATED IN PYGAME 2.2</p>
|
||||
<p>In older pygame versions before pygame 2, <a class="tooltip reference internal" href="event.html#module-pygame.event" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.event</span></code><span class="tooltip-content">pygame module for interacting with events and queues</span></a> was not well
|
||||
suited for posting events from different threads. This module served as a
|
||||
replacement (with less features) for multithreaded use. Now, the usage of this
|
||||
module is highly discouraged in favour of use of the main <a class="tooltip reference internal" href="event.html#module-pygame.event" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.event</span></code><span class="tooltip-content">pygame module for interacting with events and queues</span></a>
|
||||
module. This module will be removed in a future pygame version.</p>
|
||||
<p>Below, the legacy docs of the module is provided</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.fastevent.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.fastevent.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.fastevent.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">initialize pygame.fastevent</span></div>
|
||||
<div class="line"><span class="signature">init() -> None</span></div>
|
||||
</div>
|
||||
<p>Initialize the pygame.fastevent module.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.fastevent.get_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.fastevent.</span></span><span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.fastevent.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns True if the fastevent module is currently initialized</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns True if the pygame.fastevent module is currently initialized.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.fastevent.pump">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.fastevent.</span></span><span class="sig-name descname"><span class="pre">pump</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.fastevent.pump" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">internally process pygame event handlers</span></div>
|
||||
<div class="line"><span class="signature">pump() -> None</span></div>
|
||||
</div>
|
||||
<p>For each frame of your game, you will need to make some sort of call to the
|
||||
event queue. This ensures your program can internally interact with the rest
|
||||
of the operating system.</p>
|
||||
<p>This function is not necessary if your program is consistently processing
|
||||
events on the queue through the other <a class="tooltip reference internal" href="#module-pygame.fastevent" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.fastevent</span></code><span class="tooltip-content">pygame module for interacting with events and queues</span></a> functions.</p>
|
||||
<p>There are important things that must be dealt with internally in the event
|
||||
queue. The main window may need to be repainted or respond to the system. If
|
||||
you fail to make a call to the event queue for too long, the system may
|
||||
decide your program has locked up.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.fastevent.wait">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.fastevent.</span></span><span class="sig-name descname"><span class="pre">wait</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.fastevent.wait" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">wait for an event</span></div>
|
||||
<div class="line"><span class="signature">wait() -> Event</span></div>
|
||||
</div>
|
||||
<p>Returns the current event on the queue. If there are no messages
|
||||
waiting on the queue, this will not return until one is available.
|
||||
Sometimes it is important to use this wait to get events from the queue,
|
||||
it will allow your application to idle when the user isn't doing anything
|
||||
with it.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.fastevent.poll">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.fastevent.</span></span><span class="sig-name descname"><span class="pre">poll</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.fastevent.poll" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get an available event</span></div>
|
||||
<div class="line"><span class="signature">poll() -> Event</span></div>
|
||||
</div>
|
||||
<p>Returns next event on queue. If there is no event waiting on the queue,
|
||||
this will return an event with type NOEVENT.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.fastevent.get">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.fastevent.</span></span><span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.fastevent.get" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get all events from the queue</span></div>
|
||||
<div class="line"><span class="signature">get() -> list of Events</span></div>
|
||||
</div>
|
||||
<p>This will get all the messages and remove them from the queue.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.fastevent.post">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.fastevent.</span></span><span class="sig-name descname"><span class="pre">post</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.fastevent.post" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">place an event on the queue</span></div>
|
||||
<div class="line"><span class="signature">post(Event) -> None</span></div>
|
||||
</div>
|
||||
<p>This will post your own event objects onto the event queue. You can post
|
||||
any event type you want, but some care must be taken. For example, if you
|
||||
post a MOUSEBUTTONDOWN event to the queue, it is likely any code receiving
|
||||
the event will expect the standard MOUSEBUTTONDOWN attributes to be
|
||||
available, like 'pos' and 'button'.</p>
|
||||
<p>Because pygame.fastevent.post() may have to wait for the queue to empty,
|
||||
you can get into a dead lock if you try to append an event on to a full
|
||||
queue from the thread that processes events. For that reason I do not
|
||||
recommend using this function in the main thread of an SDL program.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/fastevent.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="font.html" title="pygame.font"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="examples.html" title="pygame.examples"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.fastevent</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,817 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.font — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.freetype" href="freetype.html" />
|
||||
<link rel="prev" title="pygame.fastevent" href="fastevent.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.font">
|
||||
<span id="pygame-font"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.font</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for loading and rendering fonts</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.init">pygame.font.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>initialize the font module</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.quit">pygame.font.quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>uninitialize the font module</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.get_init">pygame.font.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>true if the font module is initialized</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.get_default_font">pygame.font.get_default_font</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the filename of the default font</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.get_sdl_ttf_version">pygame.font.get_sdl_ttf_version</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>gets SDL_ttf version</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.get_fonts">pygame.font.get_fonts</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get all available fonts</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.match_font">pygame.font.match_font</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>find a specific font on the system</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.SysFont">pygame.font.SysFont</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>create a Font object from the system fonts</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font">pygame.font.Font</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>create a new Font object from a file</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The font module allows for rendering TrueType fonts into Surface objects.
|
||||
This module is built on top of the SDL_ttf library, which comes with all
|
||||
normal pygame installations.</p>
|
||||
<p>Most of the work done with fonts are done by using the actual Font objects.
|
||||
The module by itself only has routines to support the creation of Font objects
|
||||
with <a class="tooltip reference internal" href="#pygame.font.Font" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.font.Font()</span></code><span class="tooltip-content">create a new Font object from a file</span></a>.</p>
|
||||
<p>You can load fonts from the system by using the <a class="tooltip reference internal" href="#pygame.font.SysFont" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.font.SysFont()</span></code><span class="tooltip-content">create a Font object from the system fonts</span></a>
|
||||
function. There are a few other functions to help look up the system fonts.</p>
|
||||
<p>Pygame comes with a builtin default font, freesansbold. This can always be
|
||||
accessed by passing <code class="docutils literal notranslate"><span class="pre">None</span></code> as the font name.</p>
|
||||
<p>Before pygame 2.0.3, pygame.font accepts any UCS-2 / UTF-16 character
|
||||
('\u0001' to '\uFFFF'). After 2.0.3, pygame.font built with SDL_ttf
|
||||
2.0.15 accepts any valid UCS-4 / UTF-32 character
|
||||
(like emojis, if the font has them) ('\U00000001' to '\U0010FFFF')).
|
||||
More about this in <a class="reference internal" href="#pygame.font.Font.render" title="pygame.font.Font.render"><code class="xref py py-func docutils literal notranslate"><span class="pre">Font.render()</span></code></a>.</p>
|
||||
<p>Before pygame 2.0.3, this character space restriction can be avoided by
|
||||
using the <a class="tooltip reference internal" href="freetype.html#module-pygame.freetype" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.freetype</span></code><span class="tooltip-content">Enhanced pygame module for loading and rendering computer fonts</span></a> based <code class="docutils literal notranslate"><span class="pre">pygame.ftfont</span></code> to emulate the Font
|
||||
module. This can be used by defining the environment variable PYGAME_FREETYPE
|
||||
before the first import of <a class="tooltip reference internal" href="pygame.html#module-pygame" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame</span></code><span class="tooltip-content">the top level pygame package</span></a>. Since the problem <code class="docutils literal notranslate"><span class="pre">pygame.ftfont</span></code>
|
||||
solves no longer exists, it will likely be removed in the future.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">initialize the font module</span></div>
|
||||
<div class="line"><span class="signature">init() -> None</span></div>
|
||||
</div>
|
||||
<p>This method is called automatically by <code class="docutils literal notranslate"><span class="pre">pygame.init()</span></code>. It initializes the
|
||||
font module. The module must be initialized before any other functions will
|
||||
work.</p>
|
||||
<p>It is safe to call this function more than once.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.quit">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">uninitialize the font module</span></div>
|
||||
<div class="line"><span class="signature">quit() -> None</span></div>
|
||||
</div>
|
||||
<p>Manually uninitialize SDL_ttf's font system. This is called automatically by
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.quit()</span></code>.</p>
|
||||
<p>It is safe to call this function even if font is currently not initialized.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.get_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">true if the font module is initialized</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Test if the font module is initialized or not.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.get_default_font">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">get_default_font</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.get_default_font" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the filename of the default font</span></div>
|
||||
<div class="line"><span class="signature">get_default_font() -> string</span></div>
|
||||
</div>
|
||||
<p>Return the filename of the system font. This is not the full path to the
|
||||
file. This file can usually be found in the same directory as the font
|
||||
module, but it can also be bundled in separate archives.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.get_sdl_ttf_version">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">get_sdl_ttf_version</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.get_sdl_ttf_version" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">gets SDL_ttf version</span></div>
|
||||
<div class="line"><span class="signature">get_sdl_ttf_version(linked=True) -> (major, minor, patch)</span></div>
|
||||
</div>
|
||||
<p><strong>Experimental:</strong> feature still in development available for testing and feedback. It may change.
|
||||
<a class="reference external" href="https://github.com/pygame/pygame/pull/3095">Please leave get_sdl_ttf_version feedback with authors</a></p>
|
||||
<p>Returns a tuple of integers that identify SDL_ttf's version.
|
||||
SDL_ttf is the underlying font rendering library, written in C,
|
||||
on which pygame's font module depends. If 'linked' is True (the default),
|
||||
the function returns the version of the linked TTF library.
|
||||
Otherwise this function returns the version of TTF pygame was compiled with</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.get_fonts">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">get_fonts</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.get_fonts" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get all available fonts</span></div>
|
||||
<div class="line"><span class="signature">get_fonts() -> list of strings</span></div>
|
||||
</div>
|
||||
<p>Returns a list of all the fonts available on the system. The names of the
|
||||
fonts will be set to lowercase with all spaces and punctuation removed. This
|
||||
works on most systems, but some will return an empty list if they cannot
|
||||
find fonts.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.1.3: </span>Checks through user fonts instead of just global fonts for Windows.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.match_font">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">match_font</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.match_font" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">find a specific font on the system</span></div>
|
||||
<div class="line"><span class="signature">match_font(name, bold=False, italic=False) -> path</span></div>
|
||||
</div>
|
||||
<p>Returns the full path to a font file on the system. If bold or italic are
|
||||
set to true, this will attempt to find the correct family of font.</p>
|
||||
<p>The font name can also be an iterable of font names, a string of
|
||||
comma-separated font names, or a bytes of comma-separated font names, in
|
||||
which case the set of names will be searched in order.
|
||||
If none of the given names are found, None is returned.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1: </span>Accept an iterable of font names.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.1.3: </span>Checks through user fonts instead of just global fonts for Windows.</p>
|
||||
</div>
|
||||
<p>Example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span> <span class="n">pygame</span><span class="o">.</span><span class="n">font</span><span class="o">.</span><span class="n">match_font</span><span class="p">(</span><span class="s1">'bitstreamverasans'</span><span class="p">)</span>
|
||||
<span class="c1"># output is: /usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf</span>
|
||||
<span class="c1"># (but only if you have Vera on your system)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.SysFont">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">SysFont</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.SysFont" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">create a Font object from the system fonts</span></div>
|
||||
<div class="line"><span class="signature">SysFont(name, size, bold=False, italic=False) -> Font</span></div>
|
||||
</div>
|
||||
<p>Return a new Font object that is loaded from the system fonts. The font will
|
||||
match the requested bold and italic flags. Pygame uses a small set of common
|
||||
font aliases. If the specific font you ask for is not available, a reasonable
|
||||
alternative may be used. If a suitable system font is not found this will
|
||||
fall back on loading the default pygame font.</p>
|
||||
<p>The font name can also be an iterable of font names, a string of
|
||||
comma-separated font names, or a bytes of comma-separated font names, in
|
||||
which case the set of names will be searched in order.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1: </span>Accept an iterable of font names.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.1.3: </span>Checks through user fonts instead of just global fonts for Windows.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.font.</span></span><span class="sig-name descname"><span class="pre">Font</span></span><a class="headerlink" href="#pygame.font.Font" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">create a new Font object from a file</span></div>
|
||||
<div class="line"><span class="signature">Font(file_path=None, size=12) -> Font</span></div>
|
||||
<div class="line"><span class="signature">Font(file_path, size) -> Font</span></div>
|
||||
<div class="line"><span class="signature">Font(pathlib.Path, size) -> Font</span></div>
|
||||
<div class="line"><span class="signature">Font(object, size) -> Font</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.bold">pygame.font.Font.bold</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets whether the font should be rendered in (faked) bold.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.italic">pygame.font.Font.italic</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets whether the font should be rendered in (faked) italics.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.underline">pygame.font.Font.underline</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets whether the font should be rendered with an underline.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.strikethrough">pygame.font.Font.strikethrough</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets or sets whether the font should be rendered with a strikethrough.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.render">pygame.font.Font.render</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>draw text on a new Surface</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.size">pygame.font.Font.size</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>determine the amount of space needed to render text</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.set_underline">pygame.font.Font.set_underline</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>control if text is rendered with an underline</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.get_underline">pygame.font.Font.get_underline</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>check if text will be rendered with an underline</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.set_strikethrough">pygame.font.Font.set_strikethrough</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>control if text is rendered with a strikethrough</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.get_strikethrough">pygame.font.Font.get_strikethrough</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>check if text will be rendered with a strikethrough</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.set_bold">pygame.font.Font.set_bold</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>enable fake rendering of bold text</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.get_bold">pygame.font.Font.get_bold</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>check if text will be rendered bold</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.set_italic">pygame.font.Font.set_italic</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>enable fake rendering of italic text</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.metrics">pygame.font.Font.metrics</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>gets the metrics for each character in the passed string</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.get_italic">pygame.font.Font.get_italic</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>check if the text will be rendered italic</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.get_linesize">pygame.font.Font.get_linesize</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the line space of the font text</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.get_height">pygame.font.Font.get_height</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the height of the font</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.get_ascent">pygame.font.Font.get_ascent</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the ascent of the font</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.get_descent">pygame.font.Font.get_descent</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the descent of the font</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="font.html#pygame.font.Font.set_script">pygame.font.Font.set_script</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the script code for text shaping</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Load a new font from a given filename or a python file object. The size is
|
||||
the height of the font in pixels. If the filename is <code class="docutils literal notranslate"><span class="pre">None</span></code> the pygame
|
||||
default font will be loaded. If a font cannot be loaded from the arguments
|
||||
given an exception will be raised. Once the font is created the size cannot
|
||||
be changed. If no arguments are given then the default font will be used and
|
||||
a font size of 12 is used.</p>
|
||||
<p>Font objects are mainly used to render text into new Surface objects. The
|
||||
render can emulate bold or italic features, but it is better to load from a
|
||||
font with actual italic or bold glyphs.</p>
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.bold">
|
||||
<span class="sig-name descname"><span class="pre">bold</span></span><a class="headerlink" href="#pygame.font.Font.bold" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets whether the font should be rendered in (faked) bold.</span></div>
|
||||
<div class="line"><span class="signature">bold -> bool</span></div>
|
||||
</div>
|
||||
<p>Whether the font should be rendered in bold.</p>
|
||||
<p>When set to True, this enables the bold rendering of text. This
|
||||
is a fake stretching of the font that doesn't look good on many
|
||||
font types. If possible load the font from a real bold font
|
||||
file. While bold, the font will have a different width than when
|
||||
normal. This can be mixed with the italic, underline and
|
||||
strikethrough modes.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.italic">
|
||||
<span class="sig-name descname"><span class="pre">italic</span></span><a class="headerlink" href="#pygame.font.Font.italic" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets whether the font should be rendered in (faked) italics.</span></div>
|
||||
<div class="line"><span class="signature">italic -> bool</span></div>
|
||||
</div>
|
||||
<p>Whether the font should be rendered in italic.</p>
|
||||
<p>When set to True, this enables fake rendering of italic
|
||||
text. This is a fake skewing of the font that doesn't look good
|
||||
on many font types. If possible load the font from a real italic
|
||||
font file. While italic the font will have a different width
|
||||
than when normal. This can be mixed with the bold, underline and
|
||||
strikethrough modes.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.underline">
|
||||
<span class="sig-name descname"><span class="pre">underline</span></span><a class="headerlink" href="#pygame.font.Font.underline" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets whether the font should be rendered with an underline.</span></div>
|
||||
<div class="line"><span class="signature">underline -> bool</span></div>
|
||||
</div>
|
||||
<p>Whether the font should be rendered in underline.</p>
|
||||
<p>When set to True, all rendered fonts will include an
|
||||
underline. The underline is always one pixel thick, regardless
|
||||
of font size. This can be mixed with the bold, italic and
|
||||
strikethrough modes.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.strikethrough">
|
||||
<span class="sig-name descname"><span class="pre">strikethrough</span></span><a class="headerlink" href="#pygame.font.Font.strikethrough" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets or sets whether the font should be rendered with a strikethrough.</span></div>
|
||||
<div class="line"><span class="signature">strikethrough -> bool</span></div>
|
||||
</div>
|
||||
<p>Whether the font should be rendered with a strikethrough.</p>
|
||||
<p>When set to True, all rendered fonts will include an
|
||||
strikethrough. The strikethrough is always one pixel thick,
|
||||
regardless of font size. This can be mixed with the bold,
|
||||
italic and underline modes.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.render">
|
||||
<span class="sig-name descname"><span class="pre">render</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.render" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">draw text on a new Surface</span></div>
|
||||
<div class="line"><span class="signature">render(text, antialias, color, background=None) -> Surface</span></div>
|
||||
</div>
|
||||
<p>This creates a new Surface with the specified text rendered on it.
|
||||
<a class="tooltip reference internal" href="#module-pygame.font" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.font</span></code><span class="tooltip-content">pygame module for loading and rendering fonts</span></a> provides no way to directly draw text on an existing
|
||||
Surface: instead you must use <a class="reference internal" href="#pygame.font.Font.render" title="pygame.font.Font.render"><code class="xref py py-func docutils literal notranslate"><span class="pre">Font.render()</span></code></a> to create an image
|
||||
(Surface) of the text, then blit this image onto another Surface.</p>
|
||||
<p>The text can only be a single line: newline characters are not rendered.
|
||||
Null characters ('x00') raise a TypeError. Both Unicode and char (byte)
|
||||
strings are accepted. For Unicode strings only UCS-2 characters
|
||||
('\u0001' to '\uFFFF') were previously supported and any greater
|
||||
unicode codepoint would raise a UnicodeError. Now, characters in the
|
||||
UCS-4 range are supported. For char strings a <code class="docutils literal notranslate"><span class="pre">LATIN1</span></code> encoding is
|
||||
assumed. The antialias argument is a boolean: if True the characters
|
||||
will have smooth edges. The color argument is the color of the text
|
||||
[e.g.: (0,0,255) for blue]. The optional background argument is a color
|
||||
to use for the text background. If no background is passed the area
|
||||
outside the text will be transparent.</p>
|
||||
<p>The Surface returned will be of the dimensions required to hold the text.
|
||||
(the same as those returned by <a class="reference internal" href="#pygame.font.Font.size" title="pygame.font.Font.size"><code class="xref py py-func docutils literal notranslate"><span class="pre">Font.size()</span></code></a>). If an empty string is passed
|
||||
for the text, a blank surface will be returned that is zero pixel wide and
|
||||
the height of the font.</p>
|
||||
<p>Depending on the type of background and antialiasing used, this returns
|
||||
different types of Surfaces. For performance reasons, it is good to know
|
||||
what type of image will be used. If antialiasing is not used, the return
|
||||
image will always be an 8-bit image with a two-color palette. If the
|
||||
background is transparent a colorkey will be set. Antialiased images are
|
||||
rendered to 24-bit <code class="docutils literal notranslate"><span class="pre">RGB</span></code> images. If the background is transparent a
|
||||
pixel alpha will be included.</p>
|
||||
<p>Optimization: if you know that the final destination for the text (on the
|
||||
screen) will always have a solid background, and the text is antialiased,
|
||||
you can improve performance by specifying the background color. This will
|
||||
cause the resulting image to maintain transparency information by
|
||||
colorkey rather than (much less efficient) alpha values.</p>
|
||||
<p>If you render '\n' an unknown char will be rendered. Usually a
|
||||
rectangle. Instead you need to handle newlines yourself.</p>
|
||||
<p>Font rendering is not thread safe: only a single thread can render text
|
||||
at any time.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.3: </span>Rendering UCS4 unicode works and does not
|
||||
raise an exception. Use <cite>if hasattr(pygame.font, "UCS4"):</cite> to see if
|
||||
pygame supports rendering UCS4 unicode including more languages and
|
||||
emoji.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.size">
|
||||
<span class="sig-name descname"><span class="pre">size</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.size" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">determine the amount of space needed to render text</span></div>
|
||||
<div class="line"><span class="signature">size(text) -> (width, height)</span></div>
|
||||
</div>
|
||||
<p>Returns the dimensions needed to render the text. This can be used to
|
||||
help determine the positioning needed for text before it is rendered. It
|
||||
can also be used for word wrapping and other layout effects.</p>
|
||||
<p>Be aware that most fonts use kerning which adjusts the widths for
|
||||
specific letter pairs. For example, the width for "ae" will not always
|
||||
match the width for "a" + "e".</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.set_underline">
|
||||
<span class="sig-name descname"><span class="pre">set_underline</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.set_underline" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">control if text is rendered with an underline</span></div>
|
||||
<div class="line"><span class="signature">set_underline(bool) -> None</span></div>
|
||||
</div>
|
||||
<p>When enabled, all rendered fonts will include an underline. The underline
|
||||
is always one pixel thick, regardless of font size. This can be mixed
|
||||
with the bold, italic and strikethrough modes.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is the same as the <a class="reference internal" href="#pygame.font.Font.underline" title="pygame.font.Font.underline"><code class="xref py py-attr docutils literal notranslate"><span class="pre">underline</span></code></a> attribute.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.get_underline">
|
||||
<span class="sig-name descname"><span class="pre">get_underline</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.get_underline" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">check if text will be rendered with an underline</span></div>
|
||||
<div class="line"><span class="signature">get_underline() -> bool</span></div>
|
||||
</div>
|
||||
<p>Return True when the font underline is enabled.</p>
|
||||
<blockquote>
|
||||
<div><div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is the same as the <a class="reference internal" href="#pygame.font.Font.underline" title="pygame.font.Font.underline"><code class="xref py py-attr docutils literal notranslate"><span class="pre">underline</span></code></a> attribute.</p>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.set_strikethrough">
|
||||
<span class="sig-name descname"><span class="pre">set_strikethrough</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.set_strikethrough" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">control if text is rendered with a strikethrough</span></div>
|
||||
<div class="line"><span class="signature">set_strikethrough(bool) -> None</span></div>
|
||||
</div>
|
||||
<p>When enabled, all rendered fonts will include a strikethrough. The
|
||||
strikethrough is always one pixel thick, regardless of font size.
|
||||
This can be mixed with the bold, italic and underline modes.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is the same as the <a class="reference internal" href="#pygame.font.Font.strikethrough" title="pygame.font.Font.strikethrough"><code class="xref py py-attr docutils literal notranslate"><span class="pre">strikethrough</span></code></a> attribute.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.get_strikethrough">
|
||||
<span class="sig-name descname"><span class="pre">get_strikethrough</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.get_strikethrough" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">check if text will be rendered with a strikethrough</span></div>
|
||||
<div class="line"><span class="signature">get_strikethrough() -> bool</span></div>
|
||||
</div>
|
||||
<p>Return True when the font strikethrough is enabled.</p>
|
||||
<blockquote>
|
||||
<div><div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is the same as the <a class="reference internal" href="#pygame.font.Font.strikethrough" title="pygame.font.Font.strikethrough"><code class="xref py py-attr docutils literal notranslate"><span class="pre">strikethrough</span></code></a> attribute.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.set_bold">
|
||||
<span class="sig-name descname"><span class="pre">set_bold</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.set_bold" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">enable fake rendering of bold text</span></div>
|
||||
<div class="line"><span class="signature">set_bold(bool) -> None</span></div>
|
||||
</div>
|
||||
<p>Enables the bold rendering of text. This is a fake stretching of the font
|
||||
that doesn't look good on many font types. If possible load the font from
|
||||
a real bold font file. While bold, the font will have a different width
|
||||
than when normal. This can be mixed with the italic, underline and
|
||||
strikethrough modes.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is the same as the <a class="reference internal" href="#pygame.font.Font.bold" title="pygame.font.Font.bold"><code class="xref py py-attr docutils literal notranslate"><span class="pre">bold</span></code></a> attribute.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.get_bold">
|
||||
<span class="sig-name descname"><span class="pre">get_bold</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.get_bold" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">check if text will be rendered bold</span></div>
|
||||
<div class="line"><span class="signature">get_bold() -> bool</span></div>
|
||||
</div>
|
||||
<p>Return True when the font bold rendering mode is enabled.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is the same as the <a class="reference internal" href="#pygame.font.Font.bold" title="pygame.font.Font.bold"><code class="xref py py-attr docutils literal notranslate"><span class="pre">bold</span></code></a> attribute.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.set_italic">
|
||||
<span class="sig-name descname"><span class="pre">set_italic</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.set_italic" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">enable fake rendering of italic text</span></div>
|
||||
<div class="line"><span class="signature">set_italic(bool) -> None</span></div>
|
||||
</div>
|
||||
<p>Enables fake rendering of italic text. This is a fake skewing of the font
|
||||
that doesn't look good on many font types. If possible load the font from
|
||||
a real italic font file. While italic the font will have a different
|
||||
width than when normal. This can be mixed with the bold, underline and
|
||||
strikethrough modes.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is the same as the <a class="reference internal" href="#pygame.font.Font.italic" title="pygame.font.Font.italic"><code class="xref py py-attr docutils literal notranslate"><span class="pre">italic</span></code></a> attribute.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.metrics">
|
||||
<span class="sig-name descname"><span class="pre">metrics</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.metrics" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">gets the metrics for each character in the passed string</span></div>
|
||||
<div class="line"><span class="signature">metrics(text) -> list</span></div>
|
||||
</div>
|
||||
<p>The list contains tuples for each character, which contain the minimum
|
||||
<code class="docutils literal notranslate"><span class="pre">X</span></code> offset, the maximum <code class="docutils literal notranslate"><span class="pre">X</span></code> offset, the minimum <code class="docutils literal notranslate"><span class="pre">Y</span></code> offset, the
|
||||
maximum <code class="docutils literal notranslate"><span class="pre">Y</span></code> offset and the advance offset (bearing plus width) of the
|
||||
character. [(minx, maxx, miny, maxy, advance), (minx, maxx, miny, maxy,
|
||||
advance), ...]. None is entered in the list for each unrecognized
|
||||
character.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.get_italic">
|
||||
<span class="sig-name descname"><span class="pre">get_italic</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.get_italic" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">check if the text will be rendered italic</span></div>
|
||||
<div class="line"><span class="signature">get_italic() -> bool</span></div>
|
||||
</div>
|
||||
<p>Return True when the font italic rendering mode is enabled.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is the same as the <a class="reference internal" href="#pygame.font.Font.italic" title="pygame.font.Font.italic"><code class="xref py py-attr docutils literal notranslate"><span class="pre">italic</span></code></a> attribute.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.get_linesize">
|
||||
<span class="sig-name descname"><span class="pre">get_linesize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.get_linesize" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the line space of the font text</span></div>
|
||||
<div class="line"><span class="signature">get_linesize() -> int</span></div>
|
||||
</div>
|
||||
<p>Return the height in pixels for a line of text with the font. When
|
||||
rendering multiple lines of text this is the recommended amount of space
|
||||
between lines.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.get_height">
|
||||
<span class="sig-name descname"><span class="pre">get_height</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.get_height" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the height of the font</span></div>
|
||||
<div class="line"><span class="signature">get_height() -> int</span></div>
|
||||
</div>
|
||||
<p>Return the height in pixels of the actual rendered text. This is the
|
||||
average size for each glyph in the font.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.get_ascent">
|
||||
<span class="sig-name descname"><span class="pre">get_ascent</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.get_ascent" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the ascent of the font</span></div>
|
||||
<div class="line"><span class="signature">get_ascent() -> int</span></div>
|
||||
</div>
|
||||
<p>Return the height in pixels for the font ascent. The ascent is the number
|
||||
of pixels from the font baseline to the top of the font.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.get_descent">
|
||||
<span class="sig-name descname"><span class="pre">get_descent</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.get_descent" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the descent of the font</span></div>
|
||||
<div class="line"><span class="signature">get_descent() -> int</span></div>
|
||||
</div>
|
||||
<p>Return the height in pixels for the font descent. The descent is the
|
||||
number of pixels from the font baseline to the bottom of the font.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.font.Font.set_script">
|
||||
<span class="sig-name descname"><span class="pre">set_script</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.font.Font.set_script" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the script code for text shaping</span></div>
|
||||
<div class="line"><span class="signature">set_script(str) -> None</span></div>
|
||||
</div>
|
||||
<p><strong>Experimental:</strong> feature still in development available for testing and feedback. It may change.
|
||||
<a class="reference external" href="https://github.com/pygame/pygame/pull/3330">Please leave feedback with authors</a></p>
|
||||
<p>Sets the script used by harfbuzz text shaping, taking a 4 character
|
||||
script code as input. For example, Hindi is written in the Devanagari
|
||||
script, for which the script code is <cite>"Deva"</cite>. See the full list of
|
||||
script codes in <a class="reference external" href="https://www.unicode.org/iso15924/iso15924-codes.html">ISO 15924</a>.</p>
|
||||
<p>This method requires pygame built with SDL_ttf 2.20.0 or above. Otherwise the
|
||||
method will raise a pygame.error.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.2.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/font.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="freetype.html" title="pygame.freetype"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="fastevent.html" title="pygame.fastevent"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.font</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,557 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.image — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.joystick" href="joystick.html" />
|
||||
<link rel="prev" title="pygame.gfxdraw" href="gfxdraw.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.image">
|
||||
<span id="pygame-image"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.image</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for image transfer</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.load">pygame.image.load</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>load new image from a file (or file-like object)</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.save">pygame.image.save</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>save an image to file (or file-like object)</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.get_sdl_image_version">pygame.image.get_sdl_image_version</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get version number of the SDL_Image library being used</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.get_extended">pygame.image.get_extended</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if extended image formats can be loaded</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.tostring">pygame.image.tostring</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>transfer image to byte buffer</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.tobytes">pygame.image.tobytes</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>transfer image to byte buffer</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.fromstring">pygame.image.fromstring</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>create new Surface from a byte buffer</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.frombytes">pygame.image.frombytes</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>create new Surface from a byte buffer</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.frombuffer">pygame.image.frombuffer</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>create a new Surface that shares data inside a bytes buffer</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.load_basic">pygame.image.load_basic</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>load new BMP image from a file (or file-like object)</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.load_extended">pygame.image.load_extended</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>load an image from a file (or file-like object)</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="image.html#pygame.image.save_extended">pygame.image.save_extended</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>save a png/jpg image to file (or file-like object)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The image module contains functions for loading and saving pictures, as well as
|
||||
transferring Surfaces to formats usable by other packages.</p>
|
||||
<p>Note that there is no Image class; an image is loaded as a Surface object. The
|
||||
Surface class allows manipulation (drawing lines, setting pixels, capturing
|
||||
regions, etc.).</p>
|
||||
<p>In the vast majority of installations, pygame is built to support extended
|
||||
formats, using the SDL_Image library behind the scenes. However, some
|
||||
installations may only support uncompressed <code class="docutils literal notranslate"><span class="pre">BMP</span></code> images. With full image
|
||||
support, the <a class="tooltip reference internal" href="#pygame.image.load" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.load()</span></code><span class="tooltip-content">load new image from a file (or file-like object)</span></a> function can load the following
|
||||
formats.</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">BMP</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">GIF</span></code> (non-animated)</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">JPEG</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">LBM</span></code> (and <code class="docutils literal notranslate"><span class="pre">PBM</span></code>, <code class="docutils literal notranslate"><span class="pre">PGM</span></code>, <code class="docutils literal notranslate"><span class="pre">PPM</span></code>)</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">PCX</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">PNG</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">PNM</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">SVG</span></code> (limited support, using Nano SVG)</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">TGA</span></code> (uncompressed)</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">TIFF</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">WEBP</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">XPM</span></code></p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0: </span>Loading SVG, WebP, PNM</p>
|
||||
</div>
|
||||
<p>Saving images only supports a limited set of formats. You can save to the
|
||||
following formats.</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">BMP</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">JPEG</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">PNG</span></code></p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">TGA</span></code></p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">JPEG</span></code> and <code class="docutils literal notranslate"><span class="pre">JPG</span></code>, as well as <code class="docutils literal notranslate"><span class="pre">TIF</span></code> and <code class="docutils literal notranslate"><span class="pre">TIFF</span></code> refer to the same file format</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8: </span>Saving PNG and JPEG files.</p>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.load">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">load</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.load" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">load new image from a file (or file-like object)</span></div>
|
||||
<div class="line"><span class="signature">load(filename) -> Surface</span></div>
|
||||
<div class="line"><span class="signature">load(fileobj, namehint="") -> Surface</span></div>
|
||||
</div>
|
||||
<p>Load an image from a file source. You can pass either a filename, a Python
|
||||
file-like object, or a pathlib.Path.</p>
|
||||
<p>Pygame will automatically determine the image type (e.g., <code class="docutils literal notranslate"><span class="pre">GIF</span></code> or bitmap)
|
||||
and create a new Surface object from the data. In some cases it will need to
|
||||
know the file extension (e.g., <code class="docutils literal notranslate"><span class="pre">GIF</span></code> images should end in ".gif"). If you
|
||||
pass a raw file-like object, you may also want to pass the original filename
|
||||
as the namehint argument.</p>
|
||||
<p>The returned Surface will contain the same color format, colorkey and alpha
|
||||
transparency as the file it came from. You will often want to call
|
||||
<a class="tooltip reference internal" href="surface.html#pygame.Surface.convert" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.Surface.convert()</span></code><span class="tooltip-content">change the pixel format of an image</span></a> with no arguments, to create a copy that
|
||||
will draw more quickly on the screen.</p>
|
||||
<p>For alpha transparency, like in .png images, use the
|
||||
<a class="tooltip reference internal" href="surface.html#pygame.Surface.convert_alpha" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.Surface.convert_alpha()</span></code><span class="tooltip-content">change the pixel format of an image including per pixel alphas</span></a> method after loading so that the
|
||||
image has per pixel transparency.</p>
|
||||
<p>Pygame may not always be built to support all image formats. At minimum it
|
||||
will support uncompressed <code class="docutils literal notranslate"><span class="pre">BMP</span></code>. If <a class="tooltip reference internal" href="#pygame.image.get_extended" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.get_extended()</span></code><span class="tooltip-content">test if extended image formats can be loaded</span></a>
|
||||
returns <code class="docutils literal notranslate"><span class="pre">True</span></code>, you should be able to load most images (including PNG, JPG
|
||||
and GIF).</p>
|
||||
<p>You should use <code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.join()</span></code> for compatibility.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">eg</span><span class="o">.</span> <span class="n">asurf</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">image</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s1">'data'</span><span class="p">,</span> <span class="s1">'bla.png'</span><span class="p">))</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.save">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">save</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.save" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">save an image to file (or file-like object)</span></div>
|
||||
<div class="line"><span class="signature">save(Surface, filename) -> None</span></div>
|
||||
<div class="line"><span class="signature">save(Surface, fileobj, namehint="") -> None</span></div>
|
||||
</div>
|
||||
<p>This will save your Surface as either a <code class="docutils literal notranslate"><span class="pre">BMP</span></code>, <code class="docutils literal notranslate"><span class="pre">TGA</span></code>, <code class="docutils literal notranslate"><span class="pre">PNG</span></code>, or
|
||||
<code class="docutils literal notranslate"><span class="pre">JPEG</span></code> image. If the filename extension is unrecognized it will default to
|
||||
<code class="docutils literal notranslate"><span class="pre">TGA</span></code>. Both <code class="docutils literal notranslate"><span class="pre">TGA</span></code>, and <code class="docutils literal notranslate"><span class="pre">BMP</span></code> file formats create uncompressed files.
|
||||
You can pass a filename, a pathlib.Path or a Python file-like object.
|
||||
For file-like object, the image is saved to <code class="docutils literal notranslate"><span class="pre">TGA</span></code> format unless
|
||||
a namehint with a recognizable extension is passed in.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>When saving to a file-like object, it seems that for most formats,
|
||||
the object needs to be flushed after saving to it to make loading
|
||||
from it possible.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.8: </span>Saving PNG and JPEG files.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>The <code class="docutils literal notranslate"><span class="pre">namehint</span></code> parameter was added to make it possible
|
||||
to save other formats than <code class="docutils literal notranslate"><span class="pre">TGA</span></code> to a file-like object.
|
||||
Saving to a file-like object with JPEG is possible.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.get_sdl_image_version">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">get_sdl_image_version</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.get_sdl_image_version" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get version number of the SDL_Image library being used</span></div>
|
||||
<div class="line"><span class="signature">get_sdl_image_version(linked=True) -> None</span></div>
|
||||
<div class="line"><span class="signature">get_sdl_image_version(linked=True) -> (major, minor, patch)</span></div>
|
||||
</div>
|
||||
<p>If pygame is built with extended image formats, then this function will
|
||||
return the SDL_Image library's version number as a tuple of 3 integers
|
||||
<code class="docutils literal notranslate"><span class="pre">(major,</span> <span class="pre">minor,</span> <span class="pre">patch)</span></code>. If not, then it will return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">linked=True</span></code> is the default behavior and the function will return the
|
||||
version of the library that Pygame is linked against, while <code class="docutils literal notranslate"><span class="pre">linked=False</span></code>
|
||||
will return the version of the library that Pygame is compiled against.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.2.0: </span><code class="docutils literal notranslate"><span class="pre">linked</span></code> keyword argument added and default behavior changed from returning compiled version to returning linked version</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.get_extended">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">get_extended</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.get_extended" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if extended image formats can be loaded</span></div>
|
||||
<div class="line"><span class="signature">get_extended() -> bool</span></div>
|
||||
</div>
|
||||
<p>If pygame is built with extended image formats this function will return
|
||||
True. It is still not possible to determine which formats will be available,
|
||||
but generally you will be able to load them all.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.tostring">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">tostring</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.tostring" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">transfer image to byte buffer</span></div>
|
||||
<div class="line"><span class="signature">tostring(Surface, format, flipped=False) -> bytes</span></div>
|
||||
</div>
|
||||
<p>Creates a string of bytes that can be transferred with the <code class="docutils literal notranslate"><span class="pre">fromstring</span></code>
|
||||
or <code class="docutils literal notranslate"><span class="pre">frombytes</span></code> methods in other Python imaging packages. Some Python
|
||||
image packages prefer their images in bottom-to-top format (PyOpenGL for
|
||||
example). If you pass <code class="docutils literal notranslate"><span class="pre">True</span></code> for the flipped argument, the byte buffer
|
||||
will be vertically flipped.</p>
|
||||
<p>The format argument is a string of one of the following values. Note that
|
||||
only 8-bit Surfaces can use the "P" format. The other formats will work for
|
||||
any Surface. Also note that other Python image packages support more formats
|
||||
than pygame.</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">P</span></code>, 8-bit palettized Surfaces</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGB</span></code>, 24-bit image</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGBX</span></code>, 32-bit image with unused space</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGBA</span></code>, 32-bit image with an alpha channel</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">ARGB</span></code>, 32-bit image with alpha channel first</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">BGRA</span></code>, 32-bit image with alpha channel, red and blue channels swapped</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGBA_PREMULT</span></code>, 32-bit image with colors scaled by alpha channel</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">ARGB_PREMULT</span></code>, 32-bit image with colors scaled by alpha channel, alpha channel first</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>it is preferred to use <a class="reference internal" href="#pygame.image.tobytes" title="pygame.image.tobytes"><code class="xref py py-func docutils literal notranslate"><span class="pre">tobytes()</span></code></a> as of pygame 2.1.3</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3: </span>BGRA format</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.tobytes">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">tobytes</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.tobytes" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">transfer image to byte buffer</span></div>
|
||||
<div class="line"><span class="signature">tobytes(Surface, format, flipped=False) -> bytes</span></div>
|
||||
</div>
|
||||
<p>Creates a string of bytes that can be transferred with the <code class="docutils literal notranslate"><span class="pre">fromstring</span></code>
|
||||
or <code class="docutils literal notranslate"><span class="pre">frombytes</span></code> methods in other Python imaging packages. Some Python
|
||||
image packages prefer their images in bottom-to-top format (PyOpenGL for
|
||||
example). If you pass <code class="docutils literal notranslate"><span class="pre">True</span></code> for the flipped argument, the byte buffer
|
||||
will be vertically flipped.</p>
|
||||
<p>The format argument is a string of one of the following values. Note that
|
||||
only 8-bit Surfaces can use the "P" format. The other formats will work for
|
||||
any Surface. Also note that other Python image packages support more formats
|
||||
than pygame.</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">P</span></code>, 8-bit palettized Surfaces</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGB</span></code>, 24-bit image</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGBX</span></code>, 32-bit image with unused space</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGBA</span></code>, 32-bit image with an alpha channel</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">ARGB</span></code>, 32-bit image with alpha channel first</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">BGRA</span></code>, 32-bit image with alpha channel, red and blue channels swapped</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGBA_PREMULT</span></code>, 32-bit image with colors scaled by alpha channel</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">ARGB_PREMULT</span></code>, 32-bit image with colors scaled by alpha channel, alpha channel first</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>this function is an alias for <a class="reference internal" href="#pygame.image.tostring" title="pygame.image.tostring"><code class="xref py py-func docutils literal notranslate"><span class="pre">tostring()</span></code></a>. The use of this
|
||||
function is recommended over <a class="reference internal" href="#pygame.image.tostring" title="pygame.image.tostring"><code class="xref py py-func docutils literal notranslate"><span class="pre">tostring()</span></code></a> as of pygame 2.1.3.
|
||||
This function was introduced so it matches nicely with other
|
||||
libraries (PIL, numpy, etc), and with people's expectations.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.fromstring">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">fromstring</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.fromstring" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">create new Surface from a byte buffer</span></div>
|
||||
<div class="line"><span class="signature">fromstring(bytes, size, format, flipped=False) -> Surface</span></div>
|
||||
</div>
|
||||
<p>This function takes arguments similar to <a class="tooltip reference internal" href="#pygame.image.tostring" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.tostring()</span></code><span class="tooltip-content">transfer image to byte buffer</span></a>.
|
||||
The size argument is a pair of numbers representing the width and height.
|
||||
Once the new Surface is created it is independent from the memory of the
|
||||
bytes passed in.</p>
|
||||
<p>The bytes and format passed must compute to the exact size of image
|
||||
specified. Otherwise a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> will be raised.</p>
|
||||
<p>See the <a class="tooltip reference internal" href="#pygame.image.frombuffer" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.frombuffer()</span></code><span class="tooltip-content">create a new Surface that shares data inside a bytes buffer</span></a> method for a potentially faster
|
||||
way to transfer images into pygame.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>it is preferred to use <a class="reference internal" href="#pygame.image.frombytes" title="pygame.image.frombytes"><code class="xref py py-func docutils literal notranslate"><span class="pre">frombytes()</span></code></a> as of pygame 2.1.3</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.frombytes">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">frombytes</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.frombytes" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">create new Surface from a byte buffer</span></div>
|
||||
<div class="line"><span class="signature">frombytes(bytes, size, format, flipped=False) -> Surface</span></div>
|
||||
</div>
|
||||
<p>This function takes arguments similar to <a class="tooltip reference internal" href="#pygame.image.tobytes" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.tobytes()</span></code><span class="tooltip-content">transfer image to byte buffer</span></a>.
|
||||
The size argument is a pair of numbers representing the width and height.
|
||||
Once the new Surface is created it is independent from the memory of the
|
||||
bytes passed in.</p>
|
||||
<p>The bytes and format passed must compute to the exact size of image
|
||||
specified. Otherwise a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> will be raised.</p>
|
||||
<p>See the <a class="tooltip reference internal" href="#pygame.image.frombuffer" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.frombuffer()</span></code><span class="tooltip-content">create a new Surface that shares data inside a bytes buffer</span></a> method for a potentially faster
|
||||
way to transfer images into pygame.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>this function is an alias for <a class="reference internal" href="#pygame.image.fromstring" title="pygame.image.fromstring"><code class="xref py py-func docutils literal notranslate"><span class="pre">fromstring()</span></code></a>. The use of this
|
||||
function is recommended over <a class="reference internal" href="#pygame.image.fromstring" title="pygame.image.fromstring"><code class="xref py py-func docutils literal notranslate"><span class="pre">fromstring()</span></code></a> as of pygame 2.1.3.
|
||||
This function was introduced so it matches nicely with other
|
||||
libraries (PIL, numpy, etc), and with people's expectations.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.frombuffer">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">frombuffer</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.frombuffer" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">create a new Surface that shares data inside a bytes buffer</span></div>
|
||||
<div class="line"><span class="signature">frombuffer(buffer, size, format) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Create a new Surface that shares pixel data directly from a buffer. This
|
||||
buffer can be bytes, a bytearray, a memoryview, a
|
||||
<a class="tooltip reference internal" href="bufferproxy.html#pygame.BufferProxy" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.BufferProxy</span></code><span class="tooltip-content">pygame object to export a surface buffer through an array protocol</span></a>, or any object that supports the buffer protocol.
|
||||
This method takes similar arguments to <a class="tooltip reference internal" href="#pygame.image.fromstring" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.fromstring()</span></code><span class="tooltip-content">create new Surface from a byte buffer</span></a>, but
|
||||
is unable to vertically flip the source data.</p>
|
||||
<p>This will run much faster than <a class="tooltip reference internal" href="#pygame.image.fromstring" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.fromstring()</span></code><span class="tooltip-content">create new Surface from a byte buffer</span></a>, since no
|
||||
pixel data must be allocated and copied.</p>
|
||||
<p>It accepts the following 'format' arguments:</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">P</span></code>, 8-bit palettized Surfaces</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGB</span></code>, 24-bit image</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">BGR</span></code>, 24-bit image, red and blue channels swapped.</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGBX</span></code>, 32-bit image with unused space</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">RGBA</span></code>, 32-bit image with an alpha channel</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">ARGB</span></code>, 32-bit image with alpha channel first</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">BGRA</span></code>, 32-bit image with alpha channel, red and blue channels swapped</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3: </span>BGRA format</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.load_basic">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">load_basic</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.load_basic" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">load new BMP image from a file (or file-like object)</span></div>
|
||||
<div class="line"><span class="signature">load_basic(file) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Load an image from a file source. You can pass either a filename or a Python
|
||||
file-like object, or a pathlib.Path.</p>
|
||||
<p>This function only supports loading "basic" image format, ie <code class="docutils literal notranslate"><span class="pre">BMP</span></code>
|
||||
format.
|
||||
This function is always available, no matter how pygame was built.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.load_extended">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">load_extended</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.load_extended" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">load an image from a file (or file-like object)</span></div>
|
||||
<div class="line"><span class="signature">load_extended(filename) -> Surface</span></div>
|
||||
<div class="line"><span class="signature">load_extended(fileobj, namehint="") -> Surface</span></div>
|
||||
</div>
|
||||
<p>This function is similar to <a class="tooltip reference internal" href="#pygame.image.load" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.image.load()</span></code><span class="tooltip-content">load new image from a file (or file-like object)</span></a>, except that this
|
||||
function can only be used if pygame was built with extended image format
|
||||
support.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.1: </span>This function is always available, but raises an
|
||||
<code class="docutils literal notranslate"><span class="pre">NotImplementedError</span></code> if extended image formats are
|
||||
not supported.
|
||||
Previously, this function may or may not be
|
||||
available, depending on the state of extended image
|
||||
format support.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.image.save_extended">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.image.</span></span><span class="sig-name descname"><span class="pre">save_extended</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.image.save_extended" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">save a png/jpg image to file (or file-like object)</span></div>
|
||||
<div class="line"><span class="signature">save_extended(Surface, filename) -> None</span></div>
|
||||
<div class="line"><span class="signature">save_extended(Surface, fileobj, namehint="") -> None</span></div>
|
||||
</div>
|
||||
<p>This will save your Surface as either a <code class="docutils literal notranslate"><span class="pre">PNG</span></code> or <code class="docutils literal notranslate"><span class="pre">JPEG</span></code> image.</p>
|
||||
<p>In case the image is being saved to a file-like object, this function
|
||||
uses the namehint argument to determine the format of the file being
|
||||
saved. Saves to <code class="docutils literal notranslate"><span class="pre">JPEG</span></code> in case the namehint was not specified while
|
||||
saving to a file-like object.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.1: </span>This function is always available, but raises an
|
||||
<code class="docutils literal notranslate"><span class="pre">NotImplementedError</span></code> if extended image formats are
|
||||
not supported.
|
||||
Previously, this function may or may not be
|
||||
available, depending on the state of extended image
|
||||
format support.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/image.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="joystick.html" title="pygame.joystick"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="gfxdraw.html" title="pygame.gfxdraw"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.image</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,642 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.key — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.locals" href="locals.html" />
|
||||
<link rel="prev" title="pygame.joystick" href="joystick.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.key">
|
||||
<span id="pygame-key"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.key</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module to work with the keyboard</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.get_focused">pygame.key.get_focused</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>true if the display is receiving keyboard input from the system</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.get_pressed">pygame.key.get_pressed</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the state of all keyboard buttons</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.get_mods">pygame.key.get_mods</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>determine which modifier keys are being held</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.set_mods">pygame.key.set_mods</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>temporarily set which modifier keys are pressed</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.set_repeat">pygame.key.set_repeat</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>control how held keys are repeated</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.get_repeat">pygame.key.get_repeat</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>see how held keys are repeated</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.name">pygame.key.name</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the name of a key identifier</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.key_code">pygame.key.key_code</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the key identifier from a key name</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.start_text_input">pygame.key.start_text_input</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>start handling Unicode text input events</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.stop_text_input">pygame.key.stop_text_input</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop handling Unicode text input events</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="key.html#pygame.key.set_text_input_rect">pygame.key.set_text_input_rect</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>controls the position of the candidate list</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>This module contains functions for dealing with the keyboard.</p>
|
||||
<p>The <a class="tooltip reference internal" href="event.html#module-pygame.event" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.event</span></code><span class="tooltip-content">pygame module for interacting with events and queues</span></a> queue gets <code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code> and <code class="docutils literal notranslate"><span class="pre">pygame.KEYUP</span></code>
|
||||
events when the keyboard buttons are pressed and released. Both events have
|
||||
<code class="docutils literal notranslate"><span class="pre">key</span></code> and <code class="docutils literal notranslate"><span class="pre">mod</span></code> attributes.</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">key</span></code>: an <a class="reference internal" href="#key-constants-label"><span class="std std-ref">integer ID</span></a> representing every key
|
||||
on the keyboard</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">mod</span></code>: a bitmask of all the <a class="reference internal" href="#key-modifiers-label"><span class="std std-ref">modifier keys</span></a>
|
||||
that were in a pressed state when the event occurred</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code> event has the additional attributes <code class="docutils literal notranslate"><span class="pre">unicode</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">scancode</span></code>.</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">unicode</span></code>: a single character string that is the fully translated
|
||||
character entered, this takes into account the shift and composition keys</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">scancode</span></code>: the platform-specific key code, which could be different from
|
||||
keyboard to keyboard, but is useful for key selection of weird keys like
|
||||
the multimedia keys</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0: </span>The <code class="docutils literal notranslate"><span class="pre">pygame.TEXTINPUT</span></code> event is preferred to the <code class="docutils literal notranslate"><span class="pre">unicode</span></code> attribute
|
||||
of <code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code>. The attribute <code class="docutils literal notranslate"><span class="pre">text</span></code> contains the input.</p>
|
||||
</div>
|
||||
<p id="key-constants-label">The following is a list of all the constants (from <a class="tooltip reference internal" href="locals.html#module-pygame.locals" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.locals</span></code><span class="tooltip-content">pygame constants</span></a>) used to
|
||||
represent keyboard keys.</p>
|
||||
<p>Portability note: The integers for key constants differ between pygame 1 and 2.
|
||||
Always use key constants (<code class="docutils literal notranslate"><span class="pre">K_a</span></code>) rather than integers directly (<code class="docutils literal notranslate"><span class="pre">97</span></code>) so
|
||||
that your key handling code works well on both pygame 1 and pygame 2.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>pygame
|
||||
Constant ASCII Description
|
||||
---------------------------------
|
||||
K_BACKSPACE \b backspace
|
||||
K_TAB \t tab
|
||||
K_CLEAR clear
|
||||
K_RETURN \r return
|
||||
K_PAUSE pause
|
||||
K_ESCAPE ^[ escape
|
||||
K_SPACE space
|
||||
K_EXCLAIM ! exclaim
|
||||
K_QUOTEDBL " quotedbl
|
||||
K_HASH # hash
|
||||
K_DOLLAR $ dollar
|
||||
K_AMPERSAND & ampersand
|
||||
K_QUOTE quote
|
||||
K_LEFTPAREN ( left parenthesis
|
||||
K_RIGHTPAREN ) right parenthesis
|
||||
K_ASTERISK * asterisk
|
||||
K_PLUS + plus sign
|
||||
K_COMMA , comma
|
||||
K_MINUS - minus sign
|
||||
K_PERIOD . period
|
||||
K_SLASH / forward slash
|
||||
K_0 0 0
|
||||
K_1 1 1
|
||||
K_2 2 2
|
||||
K_3 3 3
|
||||
K_4 4 4
|
||||
K_5 5 5
|
||||
K_6 6 6
|
||||
K_7 7 7
|
||||
K_8 8 8
|
||||
K_9 9 9
|
||||
K_COLON : colon
|
||||
K_SEMICOLON ; semicolon
|
||||
K_LESS < less-than sign
|
||||
K_EQUALS = equals sign
|
||||
K_GREATER > greater-than sign
|
||||
K_QUESTION ? question mark
|
||||
K_AT @ at
|
||||
K_LEFTBRACKET [ left bracket
|
||||
K_BACKSLASH \ backslash
|
||||
K_RIGHTBRACKET ] right bracket
|
||||
K_CARET ^ caret
|
||||
K_UNDERSCORE _ underscore
|
||||
K_BACKQUOTE ` grave
|
||||
K_a a a
|
||||
K_b b b
|
||||
K_c c c
|
||||
K_d d d
|
||||
K_e e e
|
||||
K_f f f
|
||||
K_g g g
|
||||
K_h h h
|
||||
K_i i i
|
||||
K_j j j
|
||||
K_k k k
|
||||
K_l l l
|
||||
K_m m m
|
||||
K_n n n
|
||||
K_o o o
|
||||
K_p p p
|
||||
K_q q q
|
||||
K_r r r
|
||||
K_s s s
|
||||
K_t t t
|
||||
K_u u u
|
||||
K_v v v
|
||||
K_w w w
|
||||
K_x x x
|
||||
K_y y y
|
||||
K_z z z
|
||||
K_DELETE delete
|
||||
K_KP0 keypad 0
|
||||
K_KP1 keypad 1
|
||||
K_KP2 keypad 2
|
||||
K_KP3 keypad 3
|
||||
K_KP4 keypad 4
|
||||
K_KP5 keypad 5
|
||||
K_KP6 keypad 6
|
||||
K_KP7 keypad 7
|
||||
K_KP8 keypad 8
|
||||
K_KP9 keypad 9
|
||||
K_KP_PERIOD . keypad period
|
||||
K_KP_DIVIDE / keypad divide
|
||||
K_KP_MULTIPLY * keypad multiply
|
||||
K_KP_MINUS - keypad minus
|
||||
K_KP_PLUS + keypad plus
|
||||
K_KP_ENTER \r keypad enter
|
||||
K_KP_EQUALS = keypad equals
|
||||
K_UP up arrow
|
||||
K_DOWN down arrow
|
||||
K_RIGHT right arrow
|
||||
K_LEFT left arrow
|
||||
K_INSERT insert
|
||||
K_HOME home
|
||||
K_END end
|
||||
K_PAGEUP page up
|
||||
K_PAGEDOWN page down
|
||||
K_F1 F1
|
||||
K_F2 F2
|
||||
K_F3 F3
|
||||
K_F4 F4
|
||||
K_F5 F5
|
||||
K_F6 F6
|
||||
K_F7 F7
|
||||
K_F8 F8
|
||||
K_F9 F9
|
||||
K_F10 F10
|
||||
K_F11 F11
|
||||
K_F12 F12
|
||||
K_F13 F13
|
||||
K_F14 F14
|
||||
K_F15 F15
|
||||
K_NUMLOCK numlock
|
||||
K_CAPSLOCK capslock
|
||||
K_SCROLLOCK scrollock
|
||||
K_RSHIFT right shift
|
||||
K_LSHIFT left shift
|
||||
K_RCTRL right control
|
||||
K_LCTRL left control
|
||||
K_RALT right alt
|
||||
K_LALT left alt
|
||||
K_RMETA right meta
|
||||
K_LMETA left meta
|
||||
K_LSUPER left Windows key
|
||||
K_RSUPER right Windows key
|
||||
K_MODE mode shift
|
||||
K_HELP help
|
||||
K_PRINT print screen
|
||||
K_SYSREQ sysrq
|
||||
K_BREAK break
|
||||
K_MENU menu
|
||||
K_POWER power
|
||||
K_EURO Euro
|
||||
K_AC_BACK Android back button
|
||||
</pre></div>
|
||||
</div>
|
||||
<p id="key-modifiers-label">The keyboard also has a list of modifier states (from <a class="tooltip reference internal" href="locals.html#module-pygame.locals" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.locals</span></code><span class="tooltip-content">pygame constants</span></a>) that
|
||||
can be assembled by bitwise-ORing them together.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pygame</span>
|
||||
<span class="n">Constant</span> <span class="n">Description</span>
|
||||
<span class="o">-------------------------</span>
|
||||
<span class="n">KMOD_NONE</span> <span class="n">no</span> <span class="n">modifier</span> <span class="n">keys</span> <span class="n">pressed</span>
|
||||
<span class="n">KMOD_LSHIFT</span> <span class="n">left</span> <span class="n">shift</span>
|
||||
<span class="n">KMOD_RSHIFT</span> <span class="n">right</span> <span class="n">shift</span>
|
||||
<span class="n">KMOD_SHIFT</span> <span class="n">left</span> <span class="n">shift</span> <span class="ow">or</span> <span class="n">right</span> <span class="n">shift</span> <span class="ow">or</span> <span class="n">both</span>
|
||||
<span class="n">KMOD_LCTRL</span> <span class="n">left</span> <span class="n">control</span>
|
||||
<span class="n">KMOD_RCTRL</span> <span class="n">right</span> <span class="n">control</span>
|
||||
<span class="n">KMOD_CTRL</span> <span class="n">left</span> <span class="n">control</span> <span class="ow">or</span> <span class="n">right</span> <span class="n">control</span> <span class="ow">or</span> <span class="n">both</span>
|
||||
<span class="n">KMOD_LALT</span> <span class="n">left</span> <span class="n">alt</span>
|
||||
<span class="n">KMOD_RALT</span> <span class="n">right</span> <span class="n">alt</span>
|
||||
<span class="n">KMOD_ALT</span> <span class="n">left</span> <span class="n">alt</span> <span class="ow">or</span> <span class="n">right</span> <span class="n">alt</span> <span class="ow">or</span> <span class="n">both</span>
|
||||
<span class="n">KMOD_LMETA</span> <span class="n">left</span> <span class="n">meta</span>
|
||||
<span class="n">KMOD_RMETA</span> <span class="n">right</span> <span class="n">meta</span>
|
||||
<span class="n">KMOD_META</span> <span class="n">left</span> <span class="n">meta</span> <span class="ow">or</span> <span class="n">right</span> <span class="n">meta</span> <span class="ow">or</span> <span class="n">both</span>
|
||||
<span class="n">KMOD_CAPS</span> <span class="n">caps</span> <span class="n">lock</span>
|
||||
<span class="n">KMOD_NUM</span> <span class="n">num</span> <span class="n">lock</span>
|
||||
<span class="n">KMOD_MODE</span> <span class="n">AltGr</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The modifier information is contained in the <code class="docutils literal notranslate"><span class="pre">mod</span></code> attribute of the
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code> and <code class="docutils literal notranslate"><span class="pre">pygame.KEYUP</span></code> events. The <code class="docutils literal notranslate"><span class="pre">mod</span></code> attribute is a
|
||||
bitmask of all the modifier keys that were in a pressed state when the event
|
||||
occurred. The modifier information can be decoded using a bitwise AND (except
|
||||
for <code class="docutils literal notranslate"><span class="pre">KMOD_NONE</span></code>, which should be compared using equals <code class="docutils literal notranslate"><span class="pre">==</span></code>). For example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">event</span> <span class="ow">in</span> <span class="n">pygame</span><span class="o">.</span><span class="n">event</span><span class="o">.</span><span class="n">get</span><span class="p">():</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">pygame</span><span class="o">.</span><span class="n">KEYDOWN</span> <span class="ow">or</span> <span class="n">event</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">pygame</span><span class="o">.</span><span class="n">KEYUP</span><span class="p">:</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">mod</span> <span class="o">==</span> <span class="n">pygame</span><span class="o">.</span><span class="n">KMOD_NONE</span><span class="p">:</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s1">'No modifier keys were in a pressed state when this '</span>
|
||||
<span class="s1">'event occurred.'</span><span class="p">)</span>
|
||||
<span class="k">else</span><span class="p">:</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">mod</span> <span class="o">&</span> <span class="n">pygame</span><span class="o">.</span><span class="n">KMOD_LSHIFT</span><span class="p">:</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Left shift was in a pressed state when this event '</span>
|
||||
<span class="s1">'occurred.'</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">mod</span> <span class="o">&</span> <span class="n">pygame</span><span class="o">.</span><span class="n">KMOD_RSHIFT</span><span class="p">:</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Right shift was in a pressed state when this event '</span>
|
||||
<span class="s1">'occurred.'</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">mod</span> <span class="o">&</span> <span class="n">pygame</span><span class="o">.</span><span class="n">KMOD_SHIFT</span><span class="p">:</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Left shift or right shift or both were in a '</span>
|
||||
<span class="s1">'pressed state when this event occurred.'</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.get_focused">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">get_focused</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.get_focused" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">true if the display is receiving keyboard input from the system</span></div>
|
||||
<div class="line"><span class="signature">get_focused() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> when the display window has keyboard focus from the
|
||||
system. If the display needs to ensure it does not lose keyboard focus, it
|
||||
can use <a class="tooltip reference internal" href="event.html#pygame.event.set_grab" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.event.set_grab()</span></code><span class="tooltip-content">control the sharing of input devices with other applications</span></a> to grab all input.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.get_pressed">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">get_pressed</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.get_pressed" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the state of all keyboard buttons</span></div>
|
||||
<div class="line"><span class="signature">get_pressed() -> bools</span></div>
|
||||
</div>
|
||||
<p>Returns a sequence of boolean values representing the state of every key on
|
||||
the keyboard. Use the key constant values to index the array. A <code class="docutils literal notranslate"><span class="pre">True</span></code>
|
||||
value means that the button is pressed.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Getting the list of pushed buttons with this function is not the proper
|
||||
way to handle text entry from the user. There is no way to know the order
|
||||
of keys pressed, and rapidly pushed keys can be completely unnoticed
|
||||
between two calls to <code class="docutils literal notranslate"><span class="pre">pygame.key.get_pressed()</span></code>. There is also no way to
|
||||
translate these pushed keys into a fully translated character value. See
|
||||
the <code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code> events on the <a class="tooltip reference internal" href="event.html#module-pygame.event" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.event</span></code><span class="tooltip-content">pygame module for interacting with events and queues</span></a> queue for this
|
||||
functionality.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.2.0: </span>The collection of bools returned by <code class="docutils literal notranslate"><span class="pre">get_pressed</span></code> can not be iterated
|
||||
over because the indexes of the internal tuple does not correpsond to the
|
||||
keycodes.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.5.0: </span>Iteration over the collection of bools returned by <code class="docutils literal notranslate"><span class="pre">get_pressed</span></code> is now
|
||||
restored. However it still does not make sense to iterate over it. Currently.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.get_mods">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">get_mods</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.get_mods" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">determine which modifier keys are being held</span></div>
|
||||
<div class="line"><span class="signature">get_mods() -> int</span></div>
|
||||
</div>
|
||||
<p>Returns a single integer representing a bitmask of all the modifier keys
|
||||
being held. Using bitwise operators you can test if specific
|
||||
<a class="reference internal" href="#key-modifiers-label"><span class="std std-ref">modifier keys</span></a> are pressed.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.set_mods">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">set_mods</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.set_mods" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">temporarily set which modifier keys are pressed</span></div>
|
||||
<div class="line"><span class="signature">set_mods(int) -> None</span></div>
|
||||
</div>
|
||||
<p>Create a bitmask of the <a class="reference internal" href="#key-modifiers-label"><span class="std std-ref">modifier key constants</span></a>
|
||||
you want to impose on your program.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.set_repeat">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">set_repeat</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.set_repeat" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">control how held keys are repeated</span></div>
|
||||
<div class="line"><span class="signature">set_repeat() -> None</span></div>
|
||||
<div class="line"><span class="signature">set_repeat(delay) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_repeat(delay, interval) -> None</span></div>
|
||||
</div>
|
||||
<p>When the keyboard repeat is enabled, keys that are held down will generate
|
||||
multiple <code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code> events. The <code class="docutils literal notranslate"><span class="pre">delay</span></code> parameter is the number of
|
||||
milliseconds before the first repeated <code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code> event will be sent.
|
||||
After that, another <code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code> event will be sent every <code class="docutils literal notranslate"><span class="pre">interval</span></code>
|
||||
milliseconds. If a <code class="docutils literal notranslate"><span class="pre">delay</span></code> value is provided and an <code class="docutils literal notranslate"><span class="pre">interval</span></code> value is
|
||||
not provided or is 0, then the <code class="docutils literal notranslate"><span class="pre">interval</span></code> will be set to the same value as
|
||||
<code class="docutils literal notranslate"><span class="pre">delay</span></code>.</p>
|
||||
<p>To disable key repeat call this function with no arguments or with <code class="docutils literal notranslate"><span class="pre">delay</span></code>
|
||||
set to 0.</p>
|
||||
<p>When pygame is initialized the key repeat is disabled.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>ValueError</strong> -- if <code class="docutils literal notranslate"><span class="pre">delay</span></code> or <code class="docutils literal notranslate"><span class="pre">interval</span></code> is < 0</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>A <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> is now raised (instead of a
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.error</span></code>) if <code class="docutils literal notranslate"><span class="pre">delay</span></code> or <code class="docutils literal notranslate"><span class="pre">interval</span></code> is < 0.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.get_repeat">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">get_repeat</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.get_repeat" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">see how held keys are repeated</span></div>
|
||||
<div class="line"><span class="signature">get_repeat() -> (delay, interval)</span></div>
|
||||
</div>
|
||||
<p>Get the <code class="docutils literal notranslate"><span class="pre">delay</span></code> and <code class="docutils literal notranslate"><span class="pre">interval</span></code> keyboard repeat values. Refer to
|
||||
<a class="tooltip reference internal" href="#pygame.key.set_repeat" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.key.set_repeat()</span></code><span class="tooltip-content">control how held keys are repeated</span></a> for a description of these values.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.name">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">name</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.name" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the name of a key identifier</span></div>
|
||||
<div class="line"><span class="signature">name(key, use_compat=True) -> str</span></div>
|
||||
</div>
|
||||
<p>Get the descriptive name of the button from a keyboard button id constant.
|
||||
Returns an empty string (<code class="docutils literal notranslate"><span class="pre">""</span></code>) if the key is not found.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">use_compat</span></code> argument is <code class="docutils literal notranslate"><span class="pre">True</span></code> (which is the default), this function
|
||||
returns the legacy name of a key where applicable. The return value is
|
||||
expected to be the same across different pygame versions (provided the
|
||||
corresponding key constant exists and is unique). If the return value is
|
||||
passed to the <code class="docutils literal notranslate"><span class="pre">key_code</span></code> function, the original constant will be returned.</p>
|
||||
<p><strong>Experimental:</strong> <code class="docutils literal notranslate"><span class="pre">use_compat</span></code> paramater still in development for testing and feedback. It may change.
|
||||
<a class="reference external" href="https://github.com/pygame/pygame/pull/3312">Please leave use_compat feedback with authors</a></p>
|
||||
<p>If this argument is <code class="docutils literal notranslate"><span class="pre">False</span></code>, the returned name may be prettier to display
|
||||
and may cover a wider range of keys than with <code class="docutils literal notranslate"><span class="pre">use_compat</span></code>, but there are
|
||||
no guarantees that this name will be the same across different pygame
|
||||
versions. If the name returned is passed to the <code class="docutils literal notranslate"><span class="pre">key_code</span></code> function, the
|
||||
original constant is returned back (this is an implementation detail which
|
||||
may change later, do not rely on this)</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.1.3: </span>Added <code class="docutils literal notranslate"><span class="pre">use_compat</span></code> argument and guaranteed API stability for it</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.key_code">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">key_code</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.key_code" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the key identifier from a key name</span></div>
|
||||
<div class="line"><span class="signature">key_code(name=string) -> int</span></div>
|
||||
</div>
|
||||
<p>Get the key identifier code from the descriptive name of the key. This
|
||||
returns an integer matching one of the K_* keycodes. For example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">key_code</span><span class="p">(</span><span class="s2">"return"</span><span class="p">)</span> <span class="o">==</span> <span class="n">pygame</span><span class="o">.</span><span class="n">K_RETURN</span>
|
||||
<span class="go">True</span>
|
||||
<span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">key_code</span><span class="p">(</span><span class="s2">"0"</span><span class="p">)</span> <span class="o">==</span> <span class="n">pygame</span><span class="o">.</span><span class="n">K_0</span>
|
||||
<span class="go">True</span>
|
||||
<span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">key_code</span><span class="p">(</span><span class="s2">"space"</span><span class="p">)</span> <span class="o">==</span> <span class="n">pygame</span><span class="o">.</span><span class="n">K_SPACE</span>
|
||||
<span class="go">True</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>ValueError</strong> -- if the key name is not known.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.start_text_input">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">start_text_input</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.start_text_input" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">start handling Unicode text input events</span></div>
|
||||
<div class="line"><span class="signature">start_text_input() -> None</span></div>
|
||||
</div>
|
||||
<p>Start receiving <code class="docutils literal notranslate"><span class="pre">pygame.TEXTEDITING</span></code> and <code class="docutils literal notranslate"><span class="pre">pygame.TEXTINPUT</span></code>
|
||||
events. If applicable, show the on-screen keyboard or IME editor.</p>
|
||||
<p>For many languages, key presses will automatically generate a
|
||||
corresponding <code class="docutils literal notranslate"><span class="pre">pygame.TEXTINPUT</span></code> event. Special keys like
|
||||
escape or function keys, and certain key combinations will not
|
||||
generate <code class="docutils literal notranslate"><span class="pre">pygame.TEXTINPUT</span></code> events.</p>
|
||||
<p>In other languages, entering a single symbol may require multiple
|
||||
key presses, or a language-specific user interface. In this case,
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.TEXTINPUT</span></code> events are preferable to <code class="docutils literal notranslate"><span class="pre">pygame.KEYDOWN</span></code>
|
||||
events for text input.</p>
|
||||
<p>A <code class="docutils literal notranslate"><span class="pre">pygame.TEXTEDITING</span></code> event is received when an IME composition
|
||||
is started or changed. It contains the composition <code class="docutils literal notranslate"><span class="pre">text</span></code>, <code class="docutils literal notranslate"><span class="pre">length</span></code>,
|
||||
and editing <code class="docutils literal notranslate"><span class="pre">start</span></code> position within the composition (attributes
|
||||
<code class="docutils literal notranslate"><span class="pre">text</span></code>, <code class="docutils literal notranslate"><span class="pre">length</span></code>, and <code class="docutils literal notranslate"><span class="pre">start</span></code>, respectively).
|
||||
When the composition is committed (or non-IME input is received),
|
||||
a <code class="docutils literal notranslate"><span class="pre">pygame.TEXTINPUT</span></code> event is generated.</p>
|
||||
<p>Text input events handling is on by default.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.stop_text_input">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">stop_text_input</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.stop_text_input" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop handling Unicode text input events</span></div>
|
||||
<div class="line"><span class="signature">stop_text_input() -> None</span></div>
|
||||
</div>
|
||||
<p>Stop receiving <code class="docutils literal notranslate"><span class="pre">pygame.TEXTEDITING</span></code> and <code class="docutils literal notranslate"><span class="pre">pygame.TEXTINPUT</span></code>
|
||||
events. If an on-screen keyboard or IME editor was shown with
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.key.start_text_input()</span></code>, hide it again.</p>
|
||||
<p>Text input events handling is on by default.</p>
|
||||
<p>To avoid triggering the IME editor or the on-screen keyboard
|
||||
when the user is holding down a key during gameplay, text input
|
||||
should be disabled once text entry is finished, or when the user
|
||||
clicks outside of a text box.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.key.set_text_input_rect">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.key.</span></span><span class="sig-name descname"><span class="pre">set_text_input_rect</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.key.set_text_input_rect" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">controls the position of the candidate list</span></div>
|
||||
<div class="line"><span class="signature">set_text_input_rect(Rect) -> None</span></div>
|
||||
</div>
|
||||
<p>This sets the rectangle used for typing with an IME.
|
||||
It controls where the candidate list will open, if supported.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/key.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="locals.html" title="pygame.locals"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="joystick.html" title="pygame.joystick"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.key</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,157 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.locals — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.mask" href="mask.html" />
|
||||
<link rel="prev" title="pygame.key" href="key.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.locals">
|
||||
<span id="pygame-locals"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.locals</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame constants</span></div>
|
||||
</div>
|
||||
<p>This module contains various constants used by pygame. Its contents are
|
||||
automatically placed in the pygame module namespace. However, an application
|
||||
can use <code class="docutils literal notranslate"><span class="pre">pygame.locals</span></code> to include only the pygame constants with a <code class="docutils literal notranslate"><span class="pre">from</span>
|
||||
<span class="pre">pygame.locals</span> <span class="pre">import</span> <span class="pre">*</span></code>.</p>
|
||||
<p>Detailed descriptions of the various constants can be found throughout the
|
||||
pygame documentation. Here are the locations of some of them.</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p>The <a class="tooltip reference internal" href="display.html#module-pygame.display" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.display</span></code><span class="tooltip-content">pygame module to control the display window and screen</span></a> module contains flags like <code class="docutils literal notranslate"><span class="pre">FULLSCREEN</span></code> used
|
||||
by <a class="tooltip reference internal" href="display.html#pygame.display.set_mode" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.display.set_mode()</span></code><span class="tooltip-content">Initialize a window or screen for display</span></a>.</p></li>
|
||||
<li><p>The <a class="tooltip reference internal" href="event.html#module-pygame.event" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.event</span></code><span class="tooltip-content">pygame module for interacting with events and queues</span></a> module contains the various event types.</p></li>
|
||||
<li><p>The <a class="tooltip reference internal" href="key.html#module-pygame.key" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.key</span></code><span class="tooltip-content">pygame module to work with the keyboard</span></a> module lists the keyboard constants and modifiers
|
||||
(<code class="docutils literal notranslate"><span class="pre">K_</span></code>* and <code class="docutils literal notranslate"><span class="pre">MOD_</span></code>*) relating to the <code class="docutils literal notranslate"><span class="pre">key</span></code> and <code class="docutils literal notranslate"><span class="pre">mod</span></code> attributes of
|
||||
the <code class="docutils literal notranslate"><span class="pre">KEYDOWN</span></code> and <code class="docutils literal notranslate"><span class="pre">KEYUP</span></code> events.</p></li>
|
||||
<li><p>The <a class="tooltip reference internal" href="time.html#module-pygame.time" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.time</span></code><span class="tooltip-content">pygame module for monitoring time</span></a> module defines <code class="docutils literal notranslate"><span class="pre">TIMER_RESOLUTION</span></code>.</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/locals.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="mask.html" title="pygame.mask"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="key.html" title="pygame.key"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.locals</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,826 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.midi — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.mixer" href="mixer.html" />
|
||||
<link rel="prev" title="pygame.math" href="math.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.midi">
|
||||
<span id="pygame-midi"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.midi</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for interacting with midi input and output.</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.init">pygame.midi.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>initialize the midi module</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.quit">pygame.midi.quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>uninitialize the midi module</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.get_init">pygame.midi.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns True if the midi module is currently initialized</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Input">pygame.midi.Input</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Input is used to get midi input from midi devices.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output">pygame.midi.Output</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Output is used to send midi to an output device</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.get_count">pygame.midi.get_count</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>gets the number of devices.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.get_default_input_id">pygame.midi.get_default_input_id</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>gets default input device number</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.get_default_output_id">pygame.midi.get_default_output_id</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>gets default output device number</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.get_device_info">pygame.midi.get_device_info</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns information about a midi device</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.midis2events">pygame.midi.midis2events</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>converts midi events to pygame events</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.time">pygame.midi.time</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns the current time in ms of the PortMidi timer</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.frequency_to_midi">pygame.midi.frequency_to_midi</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Converts a frequency into a MIDI note. Rounds to the closest midi note.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.midi_to_frequency">pygame.midi.midi_to_frequency</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Converts a midi note to a frequency.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.midi_to_ansi_note">pygame.midi.midi_to_ansi_note</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns the Ansi Note name for a midi number.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.MidiException">pygame.midi.MidiException</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>exception that pygame.midi functions and classes can raise</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.0.</span></p>
|
||||
</div>
|
||||
<p>The midi module can send output to midi devices and get input from midi
|
||||
devices. It can also list midi devices on the system.</p>
|
||||
<p>The midi module supports real and virtual midi devices.</p>
|
||||
<p>It uses the portmidi library. Is portable to which ever platforms portmidi
|
||||
supports (currently Windows, Mac OS X, and Linux).</p>
|
||||
<p>This uses pyportmidi for now, but may use its own bindings at some point in the
|
||||
future. The pyportmidi bindings are included with pygame.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
<p>These are pygame events (<a class="tooltip reference internal" href="event.html#module-pygame.event" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.event</span></code><span class="tooltip-content">pygame module for interacting with events and queues</span></a>) reserved for midi use. The
|
||||
<code class="docutils literal notranslate"><span class="pre">MIDIIN</span></code> event is used by <a class="tooltip reference internal" href="#pygame.midi.midis2events" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.midi.midis2events()</span></code><span class="tooltip-content">converts midi events to pygame events</span></a> when converting
|
||||
midi events to pygame events.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">MIDIIN</span>
|
||||
<span class="n">MIDIOUT</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">initialize the midi module</span></div>
|
||||
<div class="line"><span class="signature">init() -> None</span></div>
|
||||
</div>
|
||||
<p>Initializes the <a class="tooltip reference internal" href="#module-pygame.midi" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code><span class="tooltip-content">pygame module for interacting with midi input and output.</span></a> module. Must be called before using the
|
||||
<a class="tooltip reference internal" href="#module-pygame.midi" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code><span class="tooltip-content">pygame module for interacting with midi input and output.</span></a> module.</p>
|
||||
<p>It is safe to call this more than once.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.quit">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">uninitialize the midi module</span></div>
|
||||
<div class="line"><span class="signature">quit() -> None</span></div>
|
||||
</div>
|
||||
<p>Uninitializes the <a class="tooltip reference internal" href="#module-pygame.midi" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code><span class="tooltip-content">pygame module for interacting with midi input and output.</span></a> module. If <a class="tooltip reference internal" href="#pygame.midi.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.midi.init()</span></code><span class="tooltip-content">initialize the midi module</span></a> was
|
||||
called to initialize the <a class="tooltip reference internal" href="#module-pygame.midi" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code><span class="tooltip-content">pygame module for interacting with midi input and output.</span></a> module, then this function will
|
||||
be called automatically when your program exits.</p>
|
||||
<p>It is safe to call this function more than once.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.get_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns True if the midi module is currently initialized</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Gets the initialization state of the <a class="tooltip reference internal" href="#module-pygame.midi" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code><span class="tooltip-content">pygame module for interacting with midi input and output.</span></a> module.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the <a class="tooltip reference internal" href="#module-pygame.midi" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code><span class="tooltip-content">pygame module for interacting with midi input and output.</span></a> module is currently initialized.</p>
|
||||
</dd>
|
||||
<dt class="field-even">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>bool</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.5.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Input">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">Input</span></span><a class="headerlink" href="#pygame.midi.Input" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Input is used to get midi input from midi devices.</span></div>
|
||||
<div class="line"><span class="signature">Input(device_id) -> None</span></div>
|
||||
<div class="line"><span class="signature">Input(device_id, buffer_size) -> None</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Input.close">pygame.midi.Input.close</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>closes a midi stream, flushing any pending buffers.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Input.poll">pygame.midi.Input.poll</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns True if there's data, or False if not.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Input.read">pygame.midi.Input.read</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>reads num_events midi events from the buffer.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>device_id</strong> (<em>int</em>) -- midi device id</p></li>
|
||||
<li><p><strong>buffer_size</strong> (<em>int</em>) -- (optional) the number of input events to be buffered</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Input.close">
|
||||
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Input.close" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">closes a midi stream, flushing any pending buffers.</span></div>
|
||||
<div class="line"><span class="signature">close() -> None</span></div>
|
||||
</div>
|
||||
<p>PortMidi attempts to close open streams when the application exits.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is particularly difficult under Windows.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Input.poll">
|
||||
<span class="sig-name descname"><span class="pre">poll</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Input.poll" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns True if there's data, or False if not.</span></div>
|
||||
<div class="line"><span class="signature">poll() -> bool</span></div>
|
||||
</div>
|
||||
<p>Used to indicate if any data exists.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if there is data, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise</p>
|
||||
</dd>
|
||||
<dt class="field-even">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>bool</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="reference internal" href="#pygame.midi.MidiException" title="pygame.midi.MidiException"><strong>MidiException</strong></a> -- on error</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Input.read">
|
||||
<span class="sig-name descname"><span class="pre">read</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Input.read" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">reads num_events midi events from the buffer.</span></div>
|
||||
<div class="line"><span class="signature">read(num_events) -> midi_event_list</span></div>
|
||||
</div>
|
||||
<p>Reads from the input buffer and gives back midi events.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>num_events</strong> (<em>int</em>) -- number of input events to read</p>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>the format for midi_event_list is
|
||||
<code class="docutils literal notranslate"><span class="pre">[[[status,</span> <span class="pre">data1,</span> <span class="pre">data2,</span> <span class="pre">data3],</span> <span class="pre">timestamp],</span> <span class="pre">...]</span></code></p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>list</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">Output</span></span><a class="headerlink" href="#pygame.midi.Output" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Output is used to send midi to an output device</span></div>
|
||||
<div class="line"><span class="signature">Output(device_id) -> None</span></div>
|
||||
<div class="line"><span class="signature">Output(device_id, latency=0) -> None</span></div>
|
||||
<div class="line"><span class="signature">Output(device_id, buffer_size=256) -> None</span></div>
|
||||
<div class="line"><span class="signature">Output(device_id, latency, buffer_size) -> None</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.abort">pygame.midi.Output.abort</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>terminates outgoing messages immediately</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.close">pygame.midi.Output.close</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>closes a midi stream, flushing any pending buffers.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.note_off">pygame.midi.Output.note_off</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>turns a midi note off (note must be on)</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.note_on">pygame.midi.Output.note_on</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>turns a midi note on (note must be off)</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.set_instrument">pygame.midi.Output.set_instrument</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>select an instrument, with a value between 0 and 127</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.pitch_bend">pygame.midi.Output.pitch_bend</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>modify the pitch of a channel.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.write">pygame.midi.Output.write</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>writes a list of midi data to the Output</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.write_short">pygame.midi.Output.write_short</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>writes up to 3 bytes of midi data to the Output</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="midi.html#pygame.midi.Output.write_sys_ex">pygame.midi.Output.write_sys_ex</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>writes a timestamped system-exclusive midi message.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">buffer_size</span></code> specifies the number of output events to be buffered
|
||||
waiting for output. In some cases (see below) PortMidi does not buffer
|
||||
output at all and merely passes data to a lower-level API, in which case
|
||||
buffersize is ignored.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">latency</span></code> is the delay in milliseconds applied to timestamps to determine
|
||||
when the output should actually occur. If <code class="docutils literal notranslate"><span class="pre">latency</span></code> is <<0, 0 is assumed.</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">latency</span></code> is zero, timestamps are ignored and all output is delivered
|
||||
immediately. If <code class="docutils literal notranslate"><span class="pre">latency</span></code> is greater than zero, output is delayed until the
|
||||
message timestamp plus the <code class="docutils literal notranslate"><span class="pre">latency</span></code>. In some cases, PortMidi can obtain
|
||||
better timing than your application by passing timestamps along to the
|
||||
device driver or hardware. Latency may also help you to synchronize midi
|
||||
data to audio data by matching midi latency to the audio buffer latency.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Time is measured relative to the time source indicated by time_proc.
|
||||
Timestamps are absolute, not relative delays or offsets.</p>
|
||||
</div>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.abort">
|
||||
<span class="sig-name descname"><span class="pre">abort</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.abort" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">terminates outgoing messages immediately</span></div>
|
||||
<div class="line"><span class="signature">abort() -> None</span></div>
|
||||
</div>
|
||||
<p>The caller should immediately close the output port; this call may result
|
||||
in transmission of a partial midi message. There is no abort for Midi
|
||||
input because the user can simply ignore messages in the buffer and close
|
||||
an input device at any time.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.close">
|
||||
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.close" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">closes a midi stream, flushing any pending buffers.</span></div>
|
||||
<div class="line"><span class="signature">close() -> None</span></div>
|
||||
</div>
|
||||
<p>PortMidi attempts to close open streams when the application exits.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This is particularly difficult under Windows.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.note_off">
|
||||
<span class="sig-name descname"><span class="pre">note_off</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.note_off" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">turns a midi note off (note must be on)</span></div>
|
||||
<div class="line"><span class="signature">note_off(note, velocity=None, channel=0) -> None</span></div>
|
||||
</div>
|
||||
<p>Turn a note off in the output stream. The note must already be on for
|
||||
this to work correctly.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.note_on">
|
||||
<span class="sig-name descname"><span class="pre">note_on</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.note_on" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">turns a midi note on (note must be off)</span></div>
|
||||
<div class="line"><span class="signature">note_on(note, velocity=None, channel=0) -> None</span></div>
|
||||
</div>
|
||||
<p>Turn a note on in the output stream. The note must already be off for
|
||||
this to work correctly.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.set_instrument">
|
||||
<span class="sig-name descname"><span class="pre">set_instrument</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.set_instrument" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">select an instrument, with a value between 0 and 127</span></div>
|
||||
<div class="line"><span class="signature">set_instrument(instrument_id, channel=0) -> None</span></div>
|
||||
</div>
|
||||
<p>Select an instrument.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.pitch_bend">
|
||||
<span class="sig-name descname"><span class="pre">pitch_bend</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.pitch_bend" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">modify the pitch of a channel.</span></div>
|
||||
<div class="line"><span class="signature">set_instrument(value=0, channel=0) -> None</span></div>
|
||||
</div>
|
||||
<p>Adjust the pitch of a channel. The value is a signed integer
|
||||
from -8192 to +8191. For example, 0 means "no change", +4096 is
|
||||
typically a semitone higher, and -8192 is 1 whole tone lower (though
|
||||
the musical range corresponding to the pitch bend range can also be
|
||||
changed in some synthesizers).</p>
|
||||
<p>If no value is given, the pitch bend is returned to "no change".</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.4.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.write">
|
||||
<span class="sig-name descname"><span class="pre">write</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.write" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">writes a list of midi data to the Output</span></div>
|
||||
<div class="line"><span class="signature">write(data) -> None</span></div>
|
||||
</div>
|
||||
<p>Writes series of MIDI information in the form of a list.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>data</strong> (<em>list</em>) -- data to write, the expected format is
|
||||
<code class="docutils literal notranslate"><span class="pre">[[[status,</span> <span class="pre">data1=0,</span> <span class="pre">data2=0,</span> <span class="pre">...],</span> <span class="pre">timestamp],</span> <span class="pre">...]</span></code>
|
||||
with the <code class="docutils literal notranslate"><span class="pre">data#</span></code> fields being optional</p>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p><strong>IndexError</strong> -- if more than 1024 elements in the data list</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<p>Example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Program change at time 20000 and 500ms later send note 65 with</span>
|
||||
<span class="c1"># velocity 100.</span>
|
||||
<span class="n">write</span><span class="p">([[[</span><span class="mh">0xc0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="mi">20000</span><span class="p">],</span> <span class="p">[[</span><span class="mh">0x90</span><span class="p">,</span> <span class="mi">60</span><span class="p">,</span> <span class="mi">100</span><span class="p">],</span> <span class="mi">20500</span><span class="p">]])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<ul class="simple">
|
||||
<li><p>Timestamps will be ignored if latency = 0</p></li>
|
||||
<li><p>To get a note to play immediately, send MIDI info with timestamp
|
||||
read from function Time</p></li>
|
||||
<li><p>Optional data fields: <code class="docutils literal notranslate"><span class="pre">write([[[0xc0,</span> <span class="pre">0,</span> <span class="pre">0],</span> <span class="pre">20000]])</span></code> is
|
||||
equivalent to <code class="docutils literal notranslate"><span class="pre">write([[[0xc0],</span> <span class="pre">20000]])</span></code></p></li>
|
||||
</ul>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.write_short">
|
||||
<span class="sig-name descname"><span class="pre">write_short</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.write_short" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">writes up to 3 bytes of midi data to the Output</span></div>
|
||||
<div class="line"><span class="signature">write_short(status) -> None</span></div>
|
||||
<div class="line"><span class="signature">write_short(status, data1=0, data2=0) -> None</span></div>
|
||||
</div>
|
||||
<p>Output MIDI information of 3 bytes or less. The <code class="docutils literal notranslate"><span class="pre">data</span></code> fields are
|
||||
optional and assumed to be 0 if omitted.</p>
|
||||
<p>Examples of status byte values:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mh">0xc0</span> <span class="c1"># program change</span>
|
||||
<span class="mh">0x90</span> <span class="c1"># note on</span>
|
||||
<span class="c1"># etc.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># note 65 on with velocity 100</span>
|
||||
<span class="n">write_short</span><span class="p">(</span><span class="mh">0x90</span><span class="p">,</span> <span class="mi">65</span><span class="p">,</span> <span class="mi">100</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.Output.write_sys_ex">
|
||||
<span class="sig-name descname"><span class="pre">write_sys_ex</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.Output.write_sys_ex" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">writes a timestamped system-exclusive midi message.</span></div>
|
||||
<div class="line"><span class="signature">write_sys_ex(when, msg) -> None</span></div>
|
||||
</div>
|
||||
<p>Writes a timestamped system-exclusive midi message.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>msg</strong> (<em>list</em><em>[</em><em>int</em><em>] or </em><em>str</em>) -- midi message</p></li>
|
||||
<li><p><strong>when</strong> -- timestamp in milliseconds</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<p>Example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">midi_output</span><span class="o">.</span><span class="n">write_sys_ex</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="s1">'</span><span class="se">\xF0\x7D\x10\x11\x12\x13\xF7</span><span class="s1">'</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># is equivalent to</span>
|
||||
|
||||
<span class="n">midi_output</span><span class="o">.</span><span class="n">write_sys_ex</span><span class="p">(</span><span class="n">pygame</span><span class="o">.</span><span class="n">midi</span><span class="o">.</span><span class="n">time</span><span class="p">(),</span>
|
||||
<span class="p">[</span><span class="mh">0xF0</span><span class="p">,</span> <span class="mh">0x7D</span><span class="p">,</span> <span class="mh">0x10</span><span class="p">,</span> <span class="mh">0x11</span><span class="p">,</span> <span class="mh">0x12</span><span class="p">,</span> <span class="mh">0x13</span><span class="p">,</span> <span class="mh">0xF7</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.get_count">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">get_count</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.get_count" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">gets the number of devices.</span></div>
|
||||
<div class="line"><span class="signature">get_count() -> num_devices</span></div>
|
||||
</div>
|
||||
<p>Device ids range from 0 to <code class="docutils literal notranslate"><span class="pre">get_count()</span> <span class="pre">-</span> <span class="pre">1</span></code></p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.get_default_input_id">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">get_default_input_id</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.get_default_input_id" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">gets default input device number</span></div>
|
||||
<div class="line"><span class="signature">get_default_input_id() -> default_id</span></div>
|
||||
</div>
|
||||
<p>The following describes the usage details for this function and the
|
||||
<a class="reference internal" href="#pygame.midi.get_default_output_id" title="pygame.midi.get_default_output_id"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_default_output_id()</span></code></a> function.</p>
|
||||
<p>Return the default device ID or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if there are no devices. The result
|
||||
can be passed to the <a class="reference internal" href="#pygame.midi.Input" title="pygame.midi.Input"><code class="xref py py-class docutils literal notranslate"><span class="pre">Input</span></code></a>/<a class="reference internal" href="#pygame.midi.Output" title="pygame.midi.Output"><code class="xref py py-class docutils literal notranslate"><span class="pre">Output</span></code></a> class.</p>
|
||||
<p>On a PC the user can specify a default device by setting an environment
|
||||
variable. To use device #1, for example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">set</span> <span class="n">PM_RECOMMENDED_INPUT_DEVICE</span><span class="o">=</span><span class="mi">1</span>
|
||||
<span class="ow">or</span>
|
||||
<span class="nb">set</span> <span class="n">PM_RECOMMENDED_OUTPUT_DEVICE</span><span class="o">=</span><span class="mi">1</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The user should first determine the available device ID by using the
|
||||
supplied application "testin" or "testout".</p>
|
||||
<p>In general, the registry is a better place for this kind of info. With
|
||||
USB devices that can come and go, using integers is not very reliable
|
||||
for device identification. Under Windows, if <code class="docutils literal notranslate"><span class="pre">PM_RECOMMENDED_INPUT_DEVICE</span></code>
|
||||
(or <code class="docutils literal notranslate"><span class="pre">PM_RECOMMENDED_OUTPUT_DEVICE</span></code>) is NOT found in the environment,
|
||||
then the default device is obtained by looking for a string in the registry
|
||||
under:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">HKEY_LOCAL_MACHINE</span><span class="o">/</span><span class="n">SOFTWARE</span><span class="o">/</span><span class="n">PortMidi</span><span class="o">/</span><span class="n">Recommended_Input_Device</span>
|
||||
<span class="ow">or</span>
|
||||
<span class="n">HKEY_LOCAL_MACHINE</span><span class="o">/</span><span class="n">SOFTWARE</span><span class="o">/</span><span class="n">PortMidi</span><span class="o">/</span><span class="n">Recommended_Output_Device</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The number of the first device with a substring that matches the
|
||||
string exactly is returned. For example, if the string in the registry is
|
||||
"USB" and device 1 is named "In USB MidiSport 1x1", then that will be
|
||||
the default input because it contains the string "USB".</p>
|
||||
<p>In addition to the name, <a class="reference internal" href="#pygame.midi.get_device_info" title="pygame.midi.get_device_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_device_info()</span></code></a> returns "interf", which is
|
||||
the interface name. The "interface" is the underlying software system or
|
||||
API used by PortMidi to access devices. Supported interfaces:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">MMSystem</span> <span class="c1"># the only Win32 interface currently supported</span>
|
||||
<span class="n">ALSA</span> <span class="c1"># the only Linux interface currently supported</span>
|
||||
<span class="n">CoreMIDI</span> <span class="c1"># the only Mac OS X interface currently supported</span>
|
||||
<span class="c1"># DirectX - not implemented</span>
|
||||
<span class="c1"># OSS - not implemented</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>To specify both the interface and the device name in the registry, separate
|
||||
the two with a comma and a space. The string before the comma must be a
|
||||
substring of the "interf" string and the string after the space must be a
|
||||
substring of the "name" name string in order to match the device. e.g.:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">MMSystem</span><span class="p">,</span> <span class="n">In</span> <span class="n">USB</span> <span class="n">MidiSport</span> <span class="mi">1</span><span class="n">x1</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>In the current release, the default is simply the first device (the
|
||||
input or output device with the lowest PmDeviceID).</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.get_default_output_id">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">get_default_output_id</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.get_default_output_id" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">gets default output device number</span></div>
|
||||
<div class="line"><span class="signature">get_default_output_id() -> default_id</span></div>
|
||||
</div>
|
||||
<p>See <a class="reference internal" href="#pygame.midi.get_default_input_id" title="pygame.midi.get_default_input_id"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_default_input_id()</span></code></a> for usage details.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.get_device_info">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">get_device_info</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.get_device_info" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns information about a midi device</span></div>
|
||||
<div class="line"><span class="signature">get_device_info(an_id) -> (interf, name, input, output, opened)</span></div>
|
||||
<div class="line"><span class="signature">get_device_info(an_id) -> None</span></div>
|
||||
</div>
|
||||
<p>Gets the device info for a given id.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>an_id</strong> (<em>int</em>) -- id of the midi device being queried</p>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p><p>if the id is out of range <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned, otherwise
|
||||
a tuple of (interf, name, input, output, opened) is returned.</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p>interf: string describing the device interface (e.g. 'ALSA')</p></li>
|
||||
<li><p>name: string name of the device (e.g. 'Midi Through Port-0')</p></li>
|
||||
<li><p>input: 1 if the device is an input device, otherwise 0</p></li>
|
||||
<li><p>output: 1 if the device is an output device, otherwise 0</p></li>
|
||||
<li><p>opened: 1 if the device is opened, otherwise 0</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>tuple or None</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.midis2events">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">midis2events</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.midis2events" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">converts midi events to pygame events</span></div>
|
||||
<div class="line"><span class="signature">midis2events(midi_events, device_id) -> [Event, ...]</span></div>
|
||||
</div>
|
||||
<p>Takes a sequence of midi events and returns list of pygame events.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">midi_events</span></code> data is expected to be a sequence of
|
||||
<code class="docutils literal notranslate"><span class="pre">((status,</span> <span class="pre">data1,</span> <span class="pre">data2,</span> <span class="pre">data3),</span> <span class="pre">timestamp)</span></code> midi events (all values
|
||||
required).</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>a list of pygame events of event type <code class="docutils literal notranslate"><span class="pre">MIDIIN</span></code></p>
|
||||
</dd>
|
||||
<dt class="field-even">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>list</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.time">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">time</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.time" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns the current time in ms of the PortMidi timer</span></div>
|
||||
<div class="line"><span class="signature">time() -> time</span></div>
|
||||
</div>
|
||||
<p>The time is reset to 0 when the <a class="tooltip reference internal" href="#module-pygame.midi" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code><span class="tooltip-content">pygame module for interacting with midi input and output.</span></a> module is initialized.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.frequency_to_midi">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">frequency_to_midi</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.frequency_to_midi" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Converts a frequency into a MIDI note. Rounds to the closest midi note.</span></div>
|
||||
<div class="line"><span class="signature">frequency_to_midi(midi_note) -> midi_note</span></div>
|
||||
</div>
|
||||
<p>example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">frequency_to_midi</span><span class="p">(</span><span class="mf">27.5</span><span class="p">)</span> <span class="o">==</span> <span class="mi">21</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.5.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.midi_to_frequency">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">midi_to_frequency</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.midi_to_frequency" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Converts a midi note to a frequency.</span></div>
|
||||
<div class="line"><span class="signature">midi_to_frequency(midi_note) -> frequency</span></div>
|
||||
</div>
|
||||
<p>example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">midi_to_frequency</span><span class="p">(</span><span class="mi">21</span><span class="p">)</span> <span class="o">==</span> <span class="mf">27.5</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.5.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.midi_to_ansi_note">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">midi_to_ansi_note</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.midi.midi_to_ansi_note" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns the Ansi Note name for a midi number.</span></div>
|
||||
<div class="line"><span class="signature">midi_to_ansi_note(midi_note) -> ansi_note</span></div>
|
||||
</div>
|
||||
<p>example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">midi_to_ansi_note</span><span class="p">(</span><span class="mi">21</span><span class="p">)</span> <span class="o">==</span> <span class="s1">'A0'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.5.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py exception definition">
|
||||
<dt class="sig sig-object py title" id="pygame.midi.MidiException">
|
||||
<em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pygame.midi.</span></span><span class="sig-name descname"><span class="pre">MidiException</span></span><a class="headerlink" href="#pygame.midi.MidiException" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">exception that pygame.midi functions and classes can raise</span></div>
|
||||
<div class="line"><span class="signature">MidiException(errno) -> None</span></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/midi.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="mixer.html" title="pygame.mixer"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="math.html" title="pygame.math"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.midi</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,977 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.mixer — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.mouse" href="mouse.html" />
|
||||
<link rel="prev" title="pygame.midi" href="midi.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.mixer">
|
||||
<span id="pygame-mixer"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mixer</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for loading and playing sounds</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.init">pygame.mixer.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>initialize the mixer module</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.pre_init">pygame.mixer.pre_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>preset the mixer init arguments</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.quit">pygame.mixer.quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>uninitialize the mixer</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.get_init">pygame.mixer.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if the mixer is initialized</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.stop">pygame.mixer.stop</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop playback of all sound channels</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.pause">pygame.mixer.pause</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>temporarily stop playback of all sound channels</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.unpause">pygame.mixer.unpause</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>resume paused playback of sound channels</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.fadeout">pygame.mixer.fadeout</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>fade out the volume on all sounds before stopping</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.set_num_channels">pygame.mixer.set_num_channels</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the total number of playback channels</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.get_num_channels">pygame.mixer.get_num_channels</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the total number of playback channels</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.set_reserved">pygame.mixer.set_reserved</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>reserve channels from being automatically used</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.find_channel">pygame.mixer.find_channel</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>find an unused channel</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.get_busy">pygame.mixer.get_busy</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if any sound is being mixed</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.get_sdl_mixer_version">pygame.mixer.get_sdl_mixer_version</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the mixer's SDL version</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound">pygame.mixer.Sound</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Create a new Sound object from a file or buffer object</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel">pygame.mixer.Channel</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Create a Channel object for controlling playback</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>This module contains classes for loading Sound objects and controlling
|
||||
playback. The mixer module is optional and depends on SDL_mixer. Your program
|
||||
should test that <a class="tooltip reference internal" href="#module-pygame.mixer" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mixer</span></code><span class="tooltip-content">pygame module for loading and playing sounds</span></a> is available and initialized before using
|
||||
it.</p>
|
||||
<p>The mixer module has a limited number of channels for playback of sounds.
|
||||
Usually programs tell pygame to start playing audio and it selects an available
|
||||
channel automatically. The default is 8 simultaneous channels, but complex
|
||||
programs can get more precise control over the number of channels and their
|
||||
use.</p>
|
||||
<p>All sound playback is mixed in background threads. When you begin to play a
|
||||
Sound object, it will return immediately while the sound continues to play. A
|
||||
single Sound object can also be actively played back multiple times.</p>
|
||||
<p>The mixer also has a special streaming channel. This is for music playback and
|
||||
is accessed through the <a class="tooltip reference internal" href="music.html#module-pygame.mixer.music" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mixer.music</span></code><span class="tooltip-content">pygame module for controlling streamed audio</span></a> module. Consider using this
|
||||
module for playing long running music. Unlike mixer module, the music module
|
||||
streams the music from the files without loading music at once into memory.</p>
|
||||
<p>The mixer module must be initialized like other pygame modules, but it has some
|
||||
extra conditions. The <code class="docutils literal notranslate"><span class="pre">pygame.mixer.init()</span></code> function takes several optional
|
||||
arguments to control the playback rate and sample size. Pygame will default to
|
||||
reasonable values, but pygame cannot perform Sound resampling, so the mixer
|
||||
should be initialized to match the values of your audio resources.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>: For less laggy sound use a smaller buffer size. The default
|
||||
is set to reduce the chance of scratchy sounds on some computers. You can
|
||||
change the default buffer by calling <a class="tooltip reference internal" href="#pygame.mixer.pre_init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.mixer.pre_init()</span></code><span class="tooltip-content">preset the mixer init arguments</span></a> before
|
||||
<a class="tooltip reference internal" href="#pygame.mixer.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.mixer.init()</span></code><span class="tooltip-content">initialize the mixer module</span></a> or <a class="tooltip reference internal" href="pygame.html#pygame.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.init()</span></code><span class="tooltip-content">initialize all imported pygame modules</span></a> is called. For example:
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mixer.pre_init(44100,-16,2,</span> <span class="pre">1024)</span></code></p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">initialize the mixer module</span></div>
|
||||
<div class="line"><span class="signature">init(frequency=44100, size=-16, channels=2, buffer=512, devicename=None, allowedchanges=AUDIO_ALLOW_FREQUENCY_CHANGE | AUDIO_ALLOW_CHANNELS_CHANGE) -> None</span></div>
|
||||
</div>
|
||||
<p>Initialize the mixer module for Sound loading and playback. The default
|
||||
arguments can be overridden to provide specific audio mixing. Keyword
|
||||
arguments are accepted. For backwards compatibility, argument values of
|
||||
0 are replaced with the startup defaults, except for <code class="docutils literal notranslate"><span class="pre">allowedchanges</span></code>,
|
||||
where -1 is used. (startup defaults may be changed by a <a class="reference internal" href="#pygame.mixer.pre_init" title="pygame.mixer.pre_init"><code class="xref py py-func docutils literal notranslate"><span class="pre">pre_init()</span></code></a> call).</p>
|
||||
<p>The size argument represents how many bits are used for each audio sample.
|
||||
If the value is negative then signed sample values will be used. Positive
|
||||
values mean unsigned audio samples will be used. An invalid value raises an
|
||||
exception.</p>
|
||||
<p>The channels argument is used to specify whether to use mono or stereo. 1
|
||||
for mono and 2 for stereo.</p>
|
||||
<p>The buffer argument controls the number of internal samples used in the
|
||||
sound mixer. The default value should work for most cases. It can be lowered
|
||||
to reduce latency, but sound dropout may occur. It can be raised to larger
|
||||
values to ensure playback never skips, but it will impose latency on sound
|
||||
playback. The buffer size must be a power of two (if not it is rounded up to
|
||||
the next nearest power of 2).</p>
|
||||
<p>Some platforms require the <a class="tooltip reference internal" href="#module-pygame.mixer" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mixer</span></code><span class="tooltip-content">pygame module for loading and playing sounds</span></a> module to be initialized
|
||||
after the display modules have initialized. The top level <code class="docutils literal notranslate"><span class="pre">pygame.init()</span></code>
|
||||
takes care of this automatically, but cannot pass any arguments to the mixer
|
||||
init. To solve this, mixer has a function <code class="docutils literal notranslate"><span class="pre">pygame.mixer.pre_init()</span></code> to set
|
||||
the proper defaults before the toplevel init is used.</p>
|
||||
<p>When using allowedchanges=0 it will convert the samples at runtime to match
|
||||
what the hardware supports. For example a sound card may not
|
||||
support 16bit sound samples, so instead it will use 8bit samples internally.
|
||||
If AUDIO_ALLOW_FORMAT_CHANGE is supplied, then the requested format will
|
||||
change to the closest that SDL2 supports.</p>
|
||||
<p>Apart from 0, allowedchanged accepts the following constants ORed together:</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p>AUDIO_ALLOW_FREQUENCY_CHANGE</p></li>
|
||||
<li><p>AUDIO_ALLOW_FORMAT_CHANGE</p></li>
|
||||
<li><p>AUDIO_ALLOW_CHANNELS_CHANGE</p></li>
|
||||
<li><p>AUDIO_ALLOW_ANY_CHANGE</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<p>It is safe to call this more than once, but after the mixer is initialized
|
||||
you cannot change the playback arguments without first calling
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mixer.quit()</span></code>.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.8: </span>The default <code class="docutils literal notranslate"><span class="pre">buffersize</span></code> changed from 1024 to 3072.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.1: </span>The default <code class="docutils literal notranslate"><span class="pre">buffersize</span></code> changed from 3072 to 4096.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>The default <code class="docutils literal notranslate"><span class="pre">buffersize</span></code> changed from 4096 to 512.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>The default <code class="docutils literal notranslate"><span class="pre">frequency</span></code> changed from 22050 to 44100.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span><code class="docutils literal notranslate"><span class="pre">size</span></code> can be 32 (32-bit floats).</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span><code class="docutils literal notranslate"><span class="pre">channels</span></code> can also be 4 or 6.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0: </span><code class="docutils literal notranslate"><span class="pre">allowedchanges</span></code>, <code class="docutils literal notranslate"><span class="pre">devicename</span></code> arguments added</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.pre_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">pre_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.pre_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">preset the mixer init arguments</span></div>
|
||||
<div class="line"><span class="signature">pre_init(frequency=44100, size=-16, channels=2, buffer=512, devicename=None, allowedchanges=AUDIO_ALLOW_FREQUENCY_CHANGE | AUDIO_ALLOW_CHANNELS_CHANGE) -> None</span></div>
|
||||
</div>
|
||||
<p>Call pre_init to change the defaults used when the real
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mixer.init()</span></code> is called. Keyword arguments are accepted. The best
|
||||
way to set custom mixer playback values is to call
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mixer.pre_init()</span></code> before calling the top level <code class="docutils literal notranslate"><span class="pre">pygame.init()</span></code>.
|
||||
For backwards compatibility, argument values of 0 are replaced with the
|
||||
startup defaults, except for <code class="docutils literal notranslate"><span class="pre">allowedchanges</span></code>, where -1 is used.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.8: </span>The default <code class="docutils literal notranslate"><span class="pre">buffersize</span></code> changed from 1024 to 3072.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.1: </span>The default <code class="docutils literal notranslate"><span class="pre">buffersize</span></code> changed from 3072 to 4096.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>The default <code class="docutils literal notranslate"><span class="pre">buffersize</span></code> changed from 4096 to 512.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>The default <code class="docutils literal notranslate"><span class="pre">frequency</span></code> changed from 22050 to 44100.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0: </span><code class="docutils literal notranslate"><span class="pre">allowedchanges</span></code>, <code class="docutils literal notranslate"><span class="pre">devicename</span></code> arguments added</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.quit">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">uninitialize the mixer</span></div>
|
||||
<div class="line"><span class="signature">quit() -> None</span></div>
|
||||
</div>
|
||||
<p>This will uninitialize <a class="tooltip reference internal" href="#module-pygame.mixer" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mixer</span></code><span class="tooltip-content">pygame module for loading and playing sounds</span></a>. All playback will stop and any
|
||||
loaded Sound objects may not be compatible with the mixer if it is
|
||||
reinitialized later.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.get_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if the mixer is initialized</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> (frequency, format, channels)</span></div>
|
||||
</div>
|
||||
<p>If the mixer is initialized, this returns the playback arguments it is
|
||||
using. If the mixer has not been initialized this returns <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.stop">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.stop" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop playback of all sound channels</span></div>
|
||||
<div class="line"><span class="signature">stop() -> None</span></div>
|
||||
</div>
|
||||
<p>This will stop all playback of all active mixer channels.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.pause">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">pause</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.pause" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">temporarily stop playback of all sound channels</span></div>
|
||||
<div class="line"><span class="signature">pause() -> None</span></div>
|
||||
</div>
|
||||
<p>This will temporarily stop all playback on the active mixer channels. The
|
||||
playback can later be resumed with <code class="docutils literal notranslate"><span class="pre">pygame.mixer.unpause()</span></code></p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.unpause">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">unpause</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.unpause" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">resume paused playback of sound channels</span></div>
|
||||
<div class="line"><span class="signature">unpause() -> None</span></div>
|
||||
</div>
|
||||
<p>This will resume all active sound channels after they have been paused.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.fadeout">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">fadeout</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.fadeout" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">fade out the volume on all sounds before stopping</span></div>
|
||||
<div class="line"><span class="signature">fadeout(time) -> None</span></div>
|
||||
</div>
|
||||
<p>This will fade out the volume on all active channels over the time argument
|
||||
in milliseconds. After the sound is muted the playback will stop.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.set_num_channels">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">set_num_channels</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.set_num_channels" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the total number of playback channels</span></div>
|
||||
<div class="line"><span class="signature">set_num_channels(count) -> None</span></div>
|
||||
</div>
|
||||
<p>Sets the number of available channels for the mixer. The default value is 8.
|
||||
The value can be increased or decreased. If the value is decreased, sounds
|
||||
playing on the truncated channels are stopped.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.get_num_channels">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">get_num_channels</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.get_num_channels" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the total number of playback channels</span></div>
|
||||
<div class="line"><span class="signature">get_num_channels() -> count</span></div>
|
||||
</div>
|
||||
<p>Returns the number of currently active playback channels.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.set_reserved">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">set_reserved</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.set_reserved" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">reserve channels from being automatically used</span></div>
|
||||
<div class="line"><span class="signature">set_reserved(count) -> count</span></div>
|
||||
</div>
|
||||
<p>The mixer can reserve any number of channels that will not be automatically
|
||||
selected for playback by Sounds. This means that whenever you play a Sound
|
||||
without specifying a channel, a reserved channel will never be used. If sounds
|
||||
are currently playing on the reserved channels they will not be stopped.</p>
|
||||
<p>This allows the application to reserve a specific number of channels for
|
||||
important sounds that must not be dropped or have a guaranteed channel to
|
||||
play on.</p>
|
||||
<p>Will return number of channels actually reserved, this may be less than requested
|
||||
depending on the number of channels previously allocated.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.find_channel">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">find_channel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.find_channel" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">find an unused channel</span></div>
|
||||
<div class="line"><span class="signature">find_channel(force=False) -> Channel</span></div>
|
||||
</div>
|
||||
<p>This will find and return an inactive Channel object. If there are no
|
||||
inactive Channels this function will return <code class="docutils literal notranslate"><span class="pre">None</span></code>. If there are no
|
||||
inactive channels and the force argument is <code class="docutils literal notranslate"><span class="pre">True</span></code>, this will find the
|
||||
Channel with the longest running Sound and return it.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.get_busy">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">get_busy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.get_busy" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if any sound is being mixed</span></div>
|
||||
<div class="line"><span class="signature">get_busy() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if the mixer is busy mixing any channels. If the mixer is
|
||||
idle then this return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.get_sdl_mixer_version">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">get_sdl_mixer_version</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.get_sdl_mixer_version" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the mixer's SDL version</span></div>
|
||||
<div class="line"><span class="signature">get_sdl_mixer_version() -> (major, minor, patch)</span></div>
|
||||
<div class="line"><span class="signature">get_sdl_mixer_version(linked=True) -> (major, minor, patch)</span></div>
|
||||
</div>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>linked</strong> (<em>bool</em>) -- if <code class="docutils literal notranslate"><span class="pre">True</span></code> (default) the linked version number is
|
||||
returned, otherwise the compiled version number is returned</p>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>the mixer's SDL library version number (linked or compiled
|
||||
depending on the <code class="docutils literal notranslate"><span class="pre">linked</span></code> parameter) as a tuple of 3 integers
|
||||
<code class="docutils literal notranslate"><span class="pre">(major,</span> <span class="pre">minor,</span> <span class="pre">patch)</span></code></p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>tuple</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The linked and compile version numbers should be the same.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">Sound</span></span><a class="headerlink" href="#pygame.mixer.Sound" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Create a new Sound object from a file or buffer object</span></div>
|
||||
<div class="line"><span class="signature">Sound(filename) -> Sound</span></div>
|
||||
<div class="line"><span class="signature">Sound(file=filename) -> Sound</span></div>
|
||||
<div class="line"><span class="signature">Sound(file=pathlib_path) -> Sound</span></div>
|
||||
<div class="line"><span class="signature">Sound(buffer) -> Sound</span></div>
|
||||
<div class="line"><span class="signature">Sound(buffer=buffer) -> Sound</span></div>
|
||||
<div class="line"><span class="signature">Sound(object) -> Sound</span></div>
|
||||
<div class="line"><span class="signature">Sound(file=object) -> Sound</span></div>
|
||||
<div class="line"><span class="signature">Sound(array=object) -> Sound</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound.play">pygame.mixer.Sound.play</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>begin sound playback</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound.stop">pygame.mixer.Sound.stop</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop sound playback</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound.fadeout">pygame.mixer.Sound.fadeout</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop sound playback after fading out</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound.set_volume">pygame.mixer.Sound.set_volume</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the playback volume for this Sound</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound.get_volume">pygame.mixer.Sound.get_volume</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the playback volume</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound.get_num_channels">pygame.mixer.Sound.get_num_channels</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>count how many times this Sound is playing</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound.get_length">pygame.mixer.Sound.get_length</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the length of the Sound</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Sound.get_raw">pygame.mixer.Sound.get_raw</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>return a bytestring copy of the Sound samples.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Load a new sound buffer from a filename, a python file object or a readable
|
||||
buffer object. Limited resampling will be performed to help the sample match
|
||||
the initialize arguments for the mixer. A Unicode string can only be a file
|
||||
pathname. A bytes object can be either a pathname or a buffer object.
|
||||
Use the 'file' or 'buffer' keywords to avoid ambiguity; otherwise Sound may
|
||||
guess wrong. If the array keyword is used, the object is expected to export
|
||||
a new buffer interface (The object is checked for a buffer interface first.)</p>
|
||||
<p>The Sound object represents actual sound sample data. Methods that change
|
||||
the state of the Sound object will the all instances of the Sound playback.
|
||||
A Sound object also exports a new buffer interface.</p>
|
||||
<p>The Sound can be loaded from an <code class="docutils literal notranslate"><span class="pre">OGG</span></code> audio file or from an uncompressed
|
||||
<code class="docutils literal notranslate"><span class="pre">WAV</span></code>.</p>
|
||||
<p>Note: The buffer will be copied internally, no data will be shared between
|
||||
it and the Sound object.</p>
|
||||
<p>For now buffer and array support is consistent with <code class="docutils literal notranslate"><span class="pre">sndarray.make_sound</span></code>
|
||||
for Numeric arrays, in that sample sign and byte order are ignored. This
|
||||
will change, either by correctly handling sign and byte order, or by raising
|
||||
an exception when different. Also, source samples are truncated to fit the
|
||||
audio sample size. This will not change.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8: </span><code class="docutils literal notranslate"><span class="pre">pygame.mixer.Sound(buffer)</span></code></p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2: </span><a class="tooltip reference internal" href="#pygame.mixer.Sound" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.mixer.Sound</span></code><span class="tooltip-content">Create a new Sound object from a file or buffer object</span></a> keyword arguments and array interface support</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1: </span>pathlib.Path support on Python 3.</p>
|
||||
</div>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound.play">
|
||||
<span class="sig-name descname"><span class="pre">play</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Sound.play" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">begin sound playback</span></div>
|
||||
<div class="line"><span class="signature">play(loops=0, maxtime=0, fade_ms=0) -> Channel</span></div>
|
||||
</div>
|
||||
<p>Begin playback of the Sound (i.e., on the computer's speakers) on an
|
||||
available Channel. This will forcibly select a Channel, so playback may
|
||||
cut off a currently playing sound if necessary.</p>
|
||||
<p>The loops argument controls how many times the sample will be repeated
|
||||
after being played the first time. A value of 5 means that the sound will
|
||||
be played once, then repeated five times, and so is played a total of six
|
||||
times. The default value (zero) means the Sound is not repeated, and so
|
||||
is only played once. If loops is set to -1 the Sound will loop
|
||||
indefinitely (though you can still call <code class="docutils literal notranslate"><span class="pre">stop()</span></code> to stop it).</p>
|
||||
<p>The maxtime argument can be used to stop playback after a given number of
|
||||
milliseconds.</p>
|
||||
<p>The fade_ms argument will make the sound start playing at 0 volume and
|
||||
fade up to full volume over the time given. The sample may end before the
|
||||
fade-in is complete.</p>
|
||||
<p>This returns the Channel object for the channel that was selected.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound.stop">
|
||||
<span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Sound.stop" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop sound playback</span></div>
|
||||
<div class="line"><span class="signature">stop() -> None</span></div>
|
||||
</div>
|
||||
<p>This will stop the playback of this Sound on any active Channels.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound.fadeout">
|
||||
<span class="sig-name descname"><span class="pre">fadeout</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Sound.fadeout" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop sound playback after fading out</span></div>
|
||||
<div class="line"><span class="signature">fadeout(time) -> None</span></div>
|
||||
</div>
|
||||
<p>This will stop playback of the sound after fading it out over the time
|
||||
argument in milliseconds. The Sound will fade and stop on all actively
|
||||
playing channels.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound.set_volume">
|
||||
<span class="sig-name descname"><span class="pre">set_volume</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Sound.set_volume" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the playback volume for this Sound</span></div>
|
||||
<div class="line"><span class="signature">set_volume(value) -> None</span></div>
|
||||
</div>
|
||||
<p>This will set the playback volume (loudness) for this Sound. This will
|
||||
immediately affect the Sound if it is playing. It will also affect any
|
||||
future playback of this Sound.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>value</strong> (<em>float</em>) -- <p>volume in the range of 0.0 to 1.0 (inclusive)</p>
|
||||
<div class="line-block">
|
||||
<div class="line">If value < 0.0, the volume will not be changed</div>
|
||||
<div class="line">If value > 1.0, the volume will be set to 1.0</div>
|
||||
</div>
|
||||
</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound.get_volume">
|
||||
<span class="sig-name descname"><span class="pre">get_volume</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Sound.get_volume" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the playback volume</span></div>
|
||||
<div class="line"><span class="signature">get_volume() -> value</span></div>
|
||||
</div>
|
||||
<p>Return a value from 0.0 to 1.0 representing the volume for this Sound.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound.get_num_channels">
|
||||
<span class="sig-name descname"><span class="pre">get_num_channels</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Sound.get_num_channels" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">count how many times this Sound is playing</span></div>
|
||||
<div class="line"><span class="signature">get_num_channels() -> count</span></div>
|
||||
</div>
|
||||
<p>Return the number of active channels this sound is playing on.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound.get_length">
|
||||
<span class="sig-name descname"><span class="pre">get_length</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Sound.get_length" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the length of the Sound</span></div>
|
||||
<div class="line"><span class="signature">get_length() -> seconds</span></div>
|
||||
</div>
|
||||
<p>Return the length of this Sound in seconds.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Sound.get_raw">
|
||||
<span class="sig-name descname"><span class="pre">get_raw</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Sound.get_raw" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">return a bytestring copy of the Sound samples.</span></div>
|
||||
<div class="line"><span class="signature">get_raw() -> bytes</span></div>
|
||||
</div>
|
||||
<p>Return a copy of the Sound object buffer as a bytes.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.</span></span><span class="sig-name descname"><span class="pre">Channel</span></span><a class="headerlink" href="#pygame.mixer.Channel" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Create a Channel object for controlling playback</span></div>
|
||||
<div class="line"><span class="signature">Channel(id) -> Channel</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.play">pygame.mixer.Channel.play</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>play a Sound on a specific Channel</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.stop">pygame.mixer.Channel.stop</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop playback on a Channel</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.pause">pygame.mixer.Channel.pause</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>temporarily stop playback of a channel</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.unpause">pygame.mixer.Channel.unpause</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>resume pause playback of a channel</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.fadeout">pygame.mixer.Channel.fadeout</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop playback after fading channel out</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.set_volume">pygame.mixer.Channel.set_volume</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the volume of a playing channel</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.get_volume">pygame.mixer.Channel.get_volume</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the volume of the playing channel</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.get_busy">pygame.mixer.Channel.get_busy</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>check if the channel is active</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.get_sound">pygame.mixer.Channel.get_sound</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the currently playing Sound</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.queue">pygame.mixer.Channel.queue</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>queue a Sound object to follow the current</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.get_queue">pygame.mixer.Channel.get_queue</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>return any Sound that is queued</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.set_endevent">pygame.mixer.Channel.set_endevent</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>have the channel send an event when playback stops</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mixer.html#pygame.mixer.Channel.get_endevent">pygame.mixer.Channel.get_endevent</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the event a channel sends when playback stops</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Return a Channel object for one of the current channels. The id must be a
|
||||
value from 0 to the value of <code class="docutils literal notranslate"><span class="pre">pygame.mixer.get_num_channels()</span></code>.</p>
|
||||
<p>The Channel object can be used to get fine control over the playback of
|
||||
Sounds. A channel can only playback a single Sound at time. Using channels
|
||||
is entirely optional since pygame can manage them by default.</p>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.play">
|
||||
<span class="sig-name descname"><span class="pre">play</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.play" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">play a Sound on a specific Channel</span></div>
|
||||
<div class="line"><span class="signature">play(Sound, loops=0, maxtime=0, fade_ms=0) -> None</span></div>
|
||||
</div>
|
||||
<p>This will begin playback of a Sound on a specific Channel. If the Channel
|
||||
is currently playing any other Sound it will be stopped.</p>
|
||||
<p>The loops argument has the same meaning as in <code class="docutils literal notranslate"><span class="pre">Sound.play()</span></code>: it is the
|
||||
number of times to repeat the sound after the first time. If it is 3, the
|
||||
sound will be played 4 times (the first time, then three more). If loops
|
||||
is -1 then the playback will repeat indefinitely.</p>
|
||||
<p>As in <code class="docutils literal notranslate"><span class="pre">Sound.play()</span></code>, the maxtime argument can be used to stop playback
|
||||
of the Sound after a given number of milliseconds.</p>
|
||||
<p>As in <code class="docutils literal notranslate"><span class="pre">Sound.play()</span></code>, the fade_ms argument can be used fade in the
|
||||
sound.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.stop">
|
||||
<span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.stop" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop playback on a Channel</span></div>
|
||||
<div class="line"><span class="signature">stop() -> None</span></div>
|
||||
</div>
|
||||
<p>Stop sound playback on a channel. After playback is stopped the channel
|
||||
becomes available for new Sounds to play on it.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.pause">
|
||||
<span class="sig-name descname"><span class="pre">pause</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.pause" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">temporarily stop playback of a channel</span></div>
|
||||
<div class="line"><span class="signature">pause() -> None</span></div>
|
||||
</div>
|
||||
<p>Temporarily stop the playback of sound on a channel. It can be resumed at
|
||||
a later time with <code class="docutils literal notranslate"><span class="pre">Channel.unpause()</span></code></p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.unpause">
|
||||
<span class="sig-name descname"><span class="pre">unpause</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.unpause" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">resume pause playback of a channel</span></div>
|
||||
<div class="line"><span class="signature">unpause() -> None</span></div>
|
||||
</div>
|
||||
<p>Resume the playback on a paused channel.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.fadeout">
|
||||
<span class="sig-name descname"><span class="pre">fadeout</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.fadeout" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop playback after fading channel out</span></div>
|
||||
<div class="line"><span class="signature">fadeout(time) -> None</span></div>
|
||||
</div>
|
||||
<p>Stop playback of a channel after fading out the sound over the given time
|
||||
argument in milliseconds.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.set_volume">
|
||||
<span class="sig-name descname"><span class="pre">set_volume</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.set_volume" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the volume of a playing channel</span></div>
|
||||
<div class="line"><span class="signature">set_volume(value) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_volume(left, right) -> None</span></div>
|
||||
</div>
|
||||
<p>Set the volume (loudness) of a playing sound. When a channel starts to
|
||||
play its volume value is reset. This only affects the current sound. The
|
||||
value argument is between 0.0 and 1.0.</p>
|
||||
<p>If one argument is passed, it will be the volume of both speakers. If two
|
||||
arguments are passed and the mixer is in stereo mode, the first argument
|
||||
will be the volume of the left speaker and the second will be the volume
|
||||
of the right speaker. (If the second argument is <code class="docutils literal notranslate"><span class="pre">None</span></code>, the first
|
||||
argument will be the volume of both speakers.)</p>
|
||||
<p>If the channel is playing a Sound on which <code class="docutils literal notranslate"><span class="pre">set_volume()</span></code> has also been
|
||||
called, both calls are taken into account. For example:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sound</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">mixer</span><span class="o">.</span><span class="n">Sound</span><span class="p">(</span><span class="s2">"s.wav"</span><span class="p">)</span>
|
||||
<span class="n">channel</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">play</span><span class="p">()</span> <span class="c1"># Sound plays at full volume by default</span>
|
||||
<span class="n">sound</span><span class="o">.</span><span class="n">set_volume</span><span class="p">(</span><span class="mf">0.9</span><span class="p">)</span> <span class="c1"># Now plays at 90% of full volume.</span>
|
||||
<span class="n">sound</span><span class="o">.</span><span class="n">set_volume</span><span class="p">(</span><span class="mf">0.6</span><span class="p">)</span> <span class="c1"># Now plays at 60% (previous value replaced).</span>
|
||||
<span class="n">channel</span><span class="o">.</span><span class="n">set_volume</span><span class="p">(</span><span class="mf">0.5</span><span class="p">)</span> <span class="c1"># Now plays at 30% (0.6 * 0.5).</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.get_volume">
|
||||
<span class="sig-name descname"><span class="pre">get_volume</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.get_volume" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the volume of the playing channel</span></div>
|
||||
<div class="line"><span class="signature">get_volume() -> value</span></div>
|
||||
</div>
|
||||
<p>Return the volume of the channel for the current playing sound. This does
|
||||
not take into account stereo separation used by
|
||||
<a class="reference internal" href="#pygame.mixer.Channel.set_volume" title="pygame.mixer.Channel.set_volume"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Channel.set_volume()</span></code></a>. The Sound object also has its own volume
|
||||
which is mixed with the channel.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.get_busy">
|
||||
<span class="sig-name descname"><span class="pre">get_busy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.get_busy" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">check if the channel is active</span></div>
|
||||
<div class="line"><span class="signature">get_busy() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if the channel is actively mixing sound. If the channel
|
||||
is idle this returns <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.get_sound">
|
||||
<span class="sig-name descname"><span class="pre">get_sound</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.get_sound" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the currently playing Sound</span></div>
|
||||
<div class="line"><span class="signature">get_sound() -> Sound</span></div>
|
||||
</div>
|
||||
<p>Return the actual Sound object currently playing on this channel. If the
|
||||
channel is idle <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.queue">
|
||||
<span class="sig-name descname"><span class="pre">queue</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.queue" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">queue a Sound object to follow the current</span></div>
|
||||
<div class="line"><span class="signature">queue(Sound) -> None</span></div>
|
||||
</div>
|
||||
<p>When a Sound is queued on a Channel, it will begin playing immediately
|
||||
after the current Sound is finished. Each channel can only have a single
|
||||
Sound queued at a time. The queued Sound will only play if the current
|
||||
playback finished automatically. It is cleared on any other call to
|
||||
<code class="docutils literal notranslate"><span class="pre">Channel.stop()</span></code> or <code class="docutils literal notranslate"><span class="pre">Channel.play()</span></code>.</p>
|
||||
<p>If there is no sound actively playing on the Channel then the Sound will
|
||||
begin playing immediately.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.get_queue">
|
||||
<span class="sig-name descname"><span class="pre">get_queue</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.get_queue" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">return any Sound that is queued</span></div>
|
||||
<div class="line"><span class="signature">get_queue() -> Sound</span></div>
|
||||
</div>
|
||||
<p>If a Sound is already queued on this channel it will be returned. Once
|
||||
the queued sound begins playback it will no longer be on the queue.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.set_endevent">
|
||||
<span class="sig-name descname"><span class="pre">set_endevent</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.set_endevent" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">have the channel send an event when playback stops</span></div>
|
||||
<div class="line"><span class="signature">set_endevent() -> None</span></div>
|
||||
<div class="line"><span class="signature">set_endevent(type) -> None</span></div>
|
||||
</div>
|
||||
<p>When an endevent is set for a channel, it will send an event to the
|
||||
pygame queue every time a sound finishes playing on that channel (not
|
||||
just the first time). Use <code class="docutils literal notranslate"><span class="pre">pygame.event.get()</span></code> to retrieve the endevent
|
||||
once it's sent.</p>
|
||||
<p>Note that if you called <code class="docutils literal notranslate"><span class="pre">Sound.play(n)</span></code> or <code class="docutils literal notranslate"><span class="pre">Channel.play(sound,n)</span></code>,
|
||||
the end event is sent only once: after the sound has been played "n+1"
|
||||
times (see the documentation of Sound.play).</p>
|
||||
<p>If <code class="docutils literal notranslate"><span class="pre">Channel.stop()</span></code> or <code class="docutils literal notranslate"><span class="pre">Channel.play()</span></code> is called while the sound was
|
||||
still playing, the event will be posted immediately.</p>
|
||||
<p>The type argument will be the event id sent to the queue. This can be any
|
||||
valid event type, but a good choice would be a value between
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.locals.USEREVENT</span></code> and <code class="docutils literal notranslate"><span class="pre">pygame.locals.NUMEVENTS</span></code>. If no type
|
||||
argument is given then the Channel will stop sending endevents.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.Channel.get_endevent">
|
||||
<span class="sig-name descname"><span class="pre">get_endevent</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.Channel.get_endevent" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the event a channel sends when playback stops</span></div>
|
||||
<div class="line"><span class="signature">get_endevent() -> type</span></div>
|
||||
</div>
|
||||
<p>Returns the event type to be sent every time the Channel finishes
|
||||
playback of a Sound. If there is no endevent the function returns
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.NOEVENT</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/mixer.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="mouse.html" title="pygame.mouse"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="midi.html" title="pygame.midi"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mixer</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,397 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.mouse — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.mixer.music" href="music.html" />
|
||||
<link rel="prev" title="pygame.mixer" href="mixer.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.mouse">
|
||||
<span id="pygame-mouse"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mouse</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module to work with the mouse</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.get_pressed">pygame.mouse.get_pressed</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the state of the mouse buttons</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.get_pos">pygame.mouse.get_pos</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the mouse cursor position</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.get_rel">pygame.mouse.get_rel</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the amount of mouse movement</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.set_pos">pygame.mouse.set_pos</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the mouse cursor position</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.set_visible">pygame.mouse.set_visible</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>hide or show the mouse cursor</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.get_visible">pygame.mouse.get_visible</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the current visibility state of the mouse cursor</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.get_focused">pygame.mouse.get_focused</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>check if the display is receiving mouse input</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.set_cursor">pygame.mouse.set_cursor</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the mouse cursor to a new cursor</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="mouse.html#pygame.mouse.get_cursor">pygame.mouse.get_cursor</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the current mouse cursor</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The mouse functions can be used to get the current state of the mouse device.
|
||||
These functions can also alter the system cursor for the mouse.</p>
|
||||
<p>When the display mode is set, the event queue will start receiving mouse
|
||||
events. The mouse buttons generate <code class="docutils literal notranslate"><span class="pre">pygame.MOUSEBUTTONDOWN</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.MOUSEBUTTONUP</span></code> events when they are pressed and released. These
|
||||
events contain a button attribute representing which button was pressed. The
|
||||
mouse wheel will generate <code class="docutils literal notranslate"><span class="pre">pygame.MOUSEBUTTONDOWN</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.MOUSEBUTTONUP</span></code> events when rolled. The button will be set to 4
|
||||
when the wheel is rolled up, and to button 5 when the wheel is rolled down.
|
||||
Whenever the mouse is moved it generates a <code class="docutils literal notranslate"><span class="pre">pygame.MOUSEMOTION</span></code> event. The
|
||||
mouse movement is broken into small and accurate motion events. As the mouse
|
||||
is moving many motion events will be placed on the queue. Mouse motion events
|
||||
that are not properly cleaned from the event queue are the primary reason the
|
||||
event queue fills up.</p>
|
||||
<p>If the mouse cursor is hidden, and input is grabbed to the current display the
|
||||
mouse will enter a virtual input mode, where the relative movements of the
|
||||
mouse will never be stopped by the borders of the screen. See the functions
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mouse.set_visible()</span></code> and <code class="docutils literal notranslate"><span class="pre">pygame.event.set_grab()</span></code> to get this
|
||||
configured.</p>
|
||||
<p><strong>Mouse Wheel Behavior in pygame 2</strong></p>
|
||||
<p>There is proper functionality for mouse wheel behaviour with pygame 2 supporting
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.MOUSEWHEEL</span></code> events. The new events support horizontal and vertical
|
||||
scroll movements, with signed integer values representing the amount scrolled
|
||||
(<code class="docutils literal notranslate"><span class="pre">x</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span></code>), as well as <code class="docutils literal notranslate"><span class="pre">flipped</span></code> direction (the set positive and
|
||||
negative values for each axis is flipped). Read more about SDL2
|
||||
input-related changes here <a class="reference external" href="https://wiki.libsdl.org/MigrationGuide#input">https://wiki.libsdl.org/MigrationGuide#input</a></p>
|
||||
<p>In pygame 2, the mouse wheel functionality can be used by listening for the
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.MOUSEWHEEL</span></code> type of an event (Bear in mind they still emit
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.MOUSEBUTTONDOWN</span></code> events like in pygame 1.x, as well).
|
||||
When this event is triggered, a developer can access the appropriate <code class="docutils literal notranslate"><span class="pre">Event</span></code> object
|
||||
with <code class="docutils literal notranslate"><span class="pre">pygame.event.get()</span></code>. The object can be used to access data about the mouse
|
||||
scroll, such as <code class="docutils literal notranslate"><span class="pre">which</span></code> (it will tell you what exact mouse device trigger the event).</p>
|
||||
<div class="literal-block-wrapper docutils container" id="test-py">
|
||||
<div class="code-block-caption"><span class="caption-text">Code example of mouse scroll (tested on 2.0.0.dev7)</span><a class="headerlink" href="#test-py" title="Permalink to this code">¶</a></div>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Taken from husano896's PR thread (slightly modified)</span>
|
||||
<span class="kn">import</span> <span class="nn">pygame</span>
|
||||
<span class="kn">from</span> <span class="nn">pygame.locals</span> <span class="kn">import</span> <span class="o">*</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">init</span><span class="p">()</span>
|
||||
<span class="n">screen</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">display</span><span class="o">.</span><span class="n">set_mode</span><span class="p">((</span><span class="mi">640</span><span class="p">,</span> <span class="mi">480</span><span class="p">))</span>
|
||||
<span class="n">clock</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">time</span><span class="o">.</span><span class="n">Clock</span><span class="p">()</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
|
||||
<span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
|
||||
<span class="k">for</span> <span class="n">event</span> <span class="ow">in</span> <span class="n">pygame</span><span class="o">.</span><span class="n">event</span><span class="o">.</span><span class="n">get</span><span class="p">():</span>
|
||||
<span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">QUIT</span><span class="p">:</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>
|
||||
<span class="k">return</span>
|
||||
<span class="k">elif</span> <span class="n">event</span><span class="o">.</span><span class="n">type</span> <span class="o">==</span> <span class="n">MOUSEWHEEL</span><span class="p">:</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">event</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">event</span><span class="o">.</span><span class="n">y</span><span class="p">)</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">event</span><span class="o">.</span><span class="n">flipped</span><span class="p">)</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">event</span><span class="o">.</span><span class="n">which</span><span class="p">)</span>
|
||||
<span class="c1"># can access properties with</span>
|
||||
<span class="c1"># proper notation(ex: event.y)</span>
|
||||
<span class="n">clock</span><span class="o">.</span><span class="n">tick</span><span class="p">(</span><span class="mi">60</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># Execute game:</span>
|
||||
<span class="n">main</span><span class="p">()</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.get_pressed">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">get_pressed</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.get_pressed" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the state of the mouse buttons</span></div>
|
||||
<div class="line"><span class="signature">get_pressed(num_buttons=3) -> (button1, button2, button3)</span></div>
|
||||
<div class="line"><span class="signature">get_pressed(num_buttons=5) -> (button1, button2, button3, button4, button5)</span></div>
|
||||
</div>
|
||||
<p>Returns a sequence of booleans representing the state of all the mouse
|
||||
buttons. A true value means the mouse is currently being pressed at the time
|
||||
of the call.</p>
|
||||
<p>Note, to get all of the mouse events it is better to use either
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.event.wait()</span></code> or <code class="docutils literal notranslate"><span class="pre">pygame.event.get()</span></code> and check all of those
|
||||
events to see if they are <code class="docutils literal notranslate"><span class="pre">MOUSEBUTTONDOWN</span></code>, <code class="docutils literal notranslate"><span class="pre">MOUSEBUTTONUP</span></code>, or
|
||||
<code class="docutils literal notranslate"><span class="pre">MOUSEMOTION</span></code>.</p>
|
||||
<p>Note, that on <code class="docutils literal notranslate"><span class="pre">X11</span></code> some X servers use middle button emulation. When you
|
||||
click both buttons <code class="docutils literal notranslate"><span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">3</span></code> at the same time a <code class="docutils literal notranslate"><span class="pre">2</span></code> button event
|
||||
can be emitted.</p>
|
||||
<p>Note, remember to call <code class="docutils literal notranslate"><span class="pre">pygame.event.get()</span></code> before this function.
|
||||
Otherwise it will not work as expected.</p>
|
||||
<p>To support five button mice, an optional parameter <code class="docutils literal notranslate"><span class="pre">num_buttons</span></code> has been
|
||||
added in pygame 2. When this is set to <code class="docutils literal notranslate"><span class="pre">5</span></code>, <code class="docutils literal notranslate"><span class="pre">button4</span></code> and <code class="docutils literal notranslate"><span class="pre">button5</span></code>
|
||||
are added to the returned tuple. Only <code class="docutils literal notranslate"><span class="pre">3</span></code> and <code class="docutils literal notranslate"><span class="pre">5</span></code> are valid values
|
||||
for this parameter.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span><code class="docutils literal notranslate"><span class="pre">num_buttons</span></code> argument added</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.get_pos">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">get_pos</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.get_pos" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the mouse cursor position</span></div>
|
||||
<div class="line"><span class="signature">get_pos() -> (x, y)</span></div>
|
||||
</div>
|
||||
<p>Returns the <code class="docutils literal notranslate"><span class="pre">x</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span></code> position of the mouse cursor. The position is
|
||||
relative to the top-left corner of the display. The cursor position can be
|
||||
located outside of the display window, but is always constrained to the
|
||||
screen.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.get_rel">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">get_rel</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.get_rel" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the amount of mouse movement</span></div>
|
||||
<div class="line"><span class="signature">get_rel() -> (x, y)</span></div>
|
||||
</div>
|
||||
<p>Returns the amount of movement in <code class="docutils literal notranslate"><span class="pre">x</span></code> and <code class="docutils literal notranslate"><span class="pre">y</span></code> since the previous call to
|
||||
this function. The relative movement of the mouse cursor is constrained to
|
||||
the edges of the screen, but see the virtual input mouse mode for a way
|
||||
around this. Virtual input mode is described at the top of the page.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.set_pos">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">set_pos</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.set_pos" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the mouse cursor position</span></div>
|
||||
<div class="line"><span class="signature">set_pos([x, y]) -> None</span></div>
|
||||
</div>
|
||||
<p>Set the current mouse position to arguments given. If the mouse cursor is
|
||||
visible it will jump to the new coordinates. Moving the mouse will generate
|
||||
a new <code class="docutils literal notranslate"><span class="pre">pygame.MOUSEMOTION</span></code> event.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.set_visible">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">set_visible</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.set_visible" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">hide or show the mouse cursor</span></div>
|
||||
<div class="line"><span class="signature">set_visible(bool) -> bool</span></div>
|
||||
</div>
|
||||
<p>If the bool argument is true, the mouse cursor will be visible. This will
|
||||
return the previous visible state of the cursor.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.get_visible">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">get_visible</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.get_visible" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the current visibility state of the mouse cursor</span></div>
|
||||
<div class="line"><span class="signature">get_visible() -> bool</span></div>
|
||||
</div>
|
||||
<p>Get the current visibility state of the mouse cursor. <code class="docutils literal notranslate"><span class="pre">True</span></code> if the mouse is
|
||||
visible, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.get_focused">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">get_focused</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.get_focused" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">check if the display is receiving mouse input</span></div>
|
||||
<div class="line"><span class="signature">get_focused() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns true when pygame is receiving mouse input events (or, in windowing
|
||||
terminology, is "active" or has the "focus").</p>
|
||||
<p>This method is most useful when working in a window. By contrast, in
|
||||
full-screen mode, this method always returns true.</p>
|
||||
<p>Note: under <code class="docutils literal notranslate"><span class="pre">MS</span></code> Windows, the window that has the mouse focus also has the
|
||||
keyboard focus. But under X-Windows, one window can receive mouse events and
|
||||
another receive keyboard events. <code class="docutils literal notranslate"><span class="pre">pygame.mouse.get_focused()</span></code> indicates
|
||||
whether the pygame window receives mouse events.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.set_cursor">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">set_cursor</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.set_cursor" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the mouse cursor to a new cursor</span></div>
|
||||
<div class="line"><span class="signature">set_cursor(pygame.cursors.Cursor) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_cursor(size, hotspot, xormasks, andmasks) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_cursor(hotspot, surface) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_cursor(constant) -> None</span></div>
|
||||
</div>
|
||||
<p>Set the mouse cursor to something new. This function accepts either an explicit
|
||||
<code class="docutils literal notranslate"><span class="pre">Cursor</span></code> object or arguments to create a <code class="docutils literal notranslate"><span class="pre">Cursor</span></code> object.</p>
|
||||
<p>See <a class="tooltip reference internal" href="cursors.html#pygame.cursors.Cursor" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.cursors.Cursor</span></code><span class="tooltip-content">pygame object representing a cursor</span></a> for help creating cursors and for examples.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mouse.get_cursor">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mouse.</span></span><span class="sig-name descname"><span class="pre">get_cursor</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mouse.get_cursor" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the current mouse cursor</span></div>
|
||||
<div class="line"><span class="signature">get_cursor() -> pygame.cursors.Cursor</span></div>
|
||||
</div>
|
||||
<p>Get the information about the mouse system cursor. The return value contains
|
||||
the same data as the arguments passed into <a class="tooltip reference internal" href="#pygame.mouse.set_cursor" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.mouse.set_cursor()</span></code><span class="tooltip-content">set the mouse cursor to a new cursor</span></a>.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Code that unpacked a get_cursor() call into
|
||||
<code class="docutils literal notranslate"><span class="pre">size,</span> <span class="pre">hotspot,</span> <span class="pre">xormasks,</span> <span class="pre">andmasks</span></code> will still work,
|
||||
assuming the call returns an old school type cursor.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/mouse.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="music.html" title="pygame.mixer.music"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="mixer.html" title="pygame.mixer"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mouse</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,493 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.mixer.music — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.Overlay" href="overlay.html" />
|
||||
<link rel="prev" title="pygame.mouse" href="mouse.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.mixer.music">
|
||||
<span id="pygame-mixer-music"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.mixer.music</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for controlling streamed audio</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.load">pygame.mixer.music.load</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Load a music file for playback</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.unload">pygame.mixer.music.unload</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Unload the currently loaded music to free up resources</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.play">pygame.mixer.music.play</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Start the playback of the music stream</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.rewind">pygame.mixer.music.rewind</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>restart music</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.stop">pygame.mixer.music.stop</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop the music playback</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.pause">pygame.mixer.music.pause</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>temporarily stop music playback</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.unpause">pygame.mixer.music.unpause</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>resume paused music</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.fadeout">pygame.mixer.music.fadeout</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>stop music playback after fading out</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.set_volume">pygame.mixer.music.set_volume</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the music volume</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.get_volume">pygame.mixer.music.get_volume</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the music volume</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.get_busy">pygame.mixer.music.get_busy</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>check if the music stream is playing</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.set_pos">pygame.mixer.music.set_pos</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set position to play from</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.get_pos">pygame.mixer.music.get_pos</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the music play time</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.queue">pygame.mixer.music.queue</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>queue a sound file to follow the current</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.set_endevent">pygame.mixer.music.set_endevent</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>have the music send an event when playback stops</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="music.html#pygame.mixer.music.get_endevent">pygame.mixer.music.get_endevent</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the event a channel sends when playback stops</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The music module is closely tied to <a class="tooltip reference internal" href="mixer.html#module-pygame.mixer" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mixer</span></code><span class="tooltip-content">pygame module for loading and playing sounds</span></a>. Use the music module
|
||||
to control the playback of music in the sound mixer.</p>
|
||||
<p>The difference between the music playback and regular Sound playback is that
|
||||
the music is streamed, and never actually loaded all at once. The mixer system
|
||||
only supports a single music stream at once.</p>
|
||||
<p>On older pygame versions, <code class="docutils literal notranslate"><span class="pre">MP3</span></code> support was limited under Mac and Linux. This
|
||||
changed in pygame <code class="docutils literal notranslate"><span class="pre">v2.0.2</span></code> which got improved MP3 support. Consider using
|
||||
<code class="docutils literal notranslate"><span class="pre">OGG</span></code> file format for music as that can give slightly better compression than
|
||||
MP3 in most cases.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.load">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">load</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.load" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Load a music file for playback</span></div>
|
||||
<div class="line"><span class="signature">load(filename) -> None</span></div>
|
||||
<div class="line"><span class="signature">load(fileobj, namehint="") -> None</span></div>
|
||||
</div>
|
||||
<p>This will load a music filename/file object and prepare it for playback. If
|
||||
a music stream is already playing it will be stopped. This does not start
|
||||
the music playing.</p>
|
||||
<p>If you are loading from a file object, the namehint parameter can be used to specify
|
||||
the type of music data in the object. For example: <code class="code docutils literal notranslate"><span class="pre">load(fileobj,</span> <span class="pre">"ogg")</span></code>.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2: </span>Added optional <code class="docutils literal notranslate"><span class="pre">namehint</span></code> argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.unload">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">unload</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.unload" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Unload the currently loaded music to free up resources</span></div>
|
||||
<div class="line"><span class="signature">unload() -> None</span></div>
|
||||
</div>
|
||||
<p>This closes resources like files for any music that may be loaded.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.play">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">play</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.play" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Start the playback of the music stream</span></div>
|
||||
<div class="line"><span class="signature">play(loops=0, start=0.0, fade_ms=0) -> None</span></div>
|
||||
</div>
|
||||
<p>This will play the loaded music stream. If the music is already playing it
|
||||
will be restarted.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">loops</span></code> is an optional integer argument, which is <code class="docutils literal notranslate"><span class="pre">0</span></code> by default, which
|
||||
indicates how many times to repeat the music. The music repeats indefinitely if
|
||||
this argument is set to <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">start</span></code> is an optional float argument, which is <code class="docutils literal notranslate"><span class="pre">0.0</span></code> by default, which
|
||||
denotes the position in time from which the music starts playing. The starting
|
||||
position depends on the format of the music played. <code class="docutils literal notranslate"><span class="pre">MP3</span></code> and <code class="docutils literal notranslate"><span class="pre">OGG</span></code> use
|
||||
the position as time in seconds. For <code class="docutils literal notranslate"><span class="pre">MP3</span></code> files the start time position
|
||||
selected may not be accurate as things like variable bit rate encoding and ID3
|
||||
tags can throw off the timing calculations. For <code class="docutils literal notranslate"><span class="pre">MOD</span></code> music it is the pattern
|
||||
order number. Passing a start position will raise a NotImplementedError if
|
||||
the start position cannot be set.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">fade_ms</span></code> is an optional integer argument, which is <code class="docutils literal notranslate"><span class="pre">0</span></code> by default,
|
||||
which denotes the period of time (in milliseconds) over which the music
|
||||
will fade up from volume level <code class="docutils literal notranslate"><span class="pre">0.0</span></code> to full volume (or the volume level
|
||||
previously set by <a class="reference internal" href="#pygame.mixer.music.set_volume" title="pygame.mixer.music.set_volume"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_volume()</span></code></a>). The sample may end before the fade-in
|
||||
is complete. If the music is already streaming <code class="docutils literal notranslate"><span class="pre">fade_ms</span></code> is ignored.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.0: </span>Added optional <code class="docutils literal notranslate"><span class="pre">fade_ms</span></code> argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.rewind">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">rewind</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.rewind" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">restart music</span></div>
|
||||
<div class="line"><span class="signature">rewind() -> None</span></div>
|
||||
</div>
|
||||
<p>Resets playback of the current music to the beginning. If <a class="reference internal" href="#pygame.mixer.music.pause" title="pygame.mixer.music.pause"><code class="xref py py-func docutils literal notranslate"><span class="pre">pause()</span></code></a> has
|
||||
previously been used to pause the music, the music will remain paused.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p><a class="reference internal" href="#pygame.mixer.music.rewind" title="pygame.mixer.music.rewind"><code class="xref py py-func docutils literal notranslate"><span class="pre">rewind()</span></code></a> supports a limited number of file types and notably
|
||||
<code class="docutils literal notranslate"><span class="pre">WAV</span></code> files are NOT supported. For unsupported file types use <a class="reference internal" href="#pygame.mixer.music.play" title="pygame.mixer.music.play"><code class="xref py py-func docutils literal notranslate"><span class="pre">play()</span></code></a>
|
||||
which will restart the music that's already playing (note that this
|
||||
will start the music playing again even if previously paused).</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.stop">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.stop" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop the music playback</span></div>
|
||||
<div class="line"><span class="signature">stop() -> None</span></div>
|
||||
</div>
|
||||
<p>Stops the music playback if it is currently playing.
|
||||
endevent will be triggered, if set.
|
||||
It won't unload the music.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.pause">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">pause</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.pause" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">temporarily stop music playback</span></div>
|
||||
<div class="line"><span class="signature">pause() -> None</span></div>
|
||||
</div>
|
||||
<p>Temporarily stop playback of the music stream. It can be resumed with the
|
||||
<a class="reference internal" href="#pygame.mixer.music.unpause" title="pygame.mixer.music.unpause"><code class="xref py py-func docutils literal notranslate"><span class="pre">unpause()</span></code></a> function.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.unpause">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">unpause</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.unpause" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">resume paused music</span></div>
|
||||
<div class="line"><span class="signature">unpause() -> None</span></div>
|
||||
</div>
|
||||
<p>This will resume the playback of a music stream after it has been paused.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.fadeout">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">fadeout</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.fadeout" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">stop music playback after fading out</span></div>
|
||||
<div class="line"><span class="signature">fadeout(time) -> None</span></div>
|
||||
</div>
|
||||
<p>Fade out and stop the currently playing music.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">time</span></code> argument denotes the integer milliseconds for which the
|
||||
fading effect is generated.</p>
|
||||
<p>Note, that this function blocks until the music has faded out. Calls
|
||||
to <a class="reference internal" href="#pygame.mixer.music.fadeout" title="pygame.mixer.music.fadeout"><code class="xref py py-func docutils literal notranslate"><span class="pre">fadeout()</span></code></a> and <a class="reference internal" href="#pygame.mixer.music.set_volume" title="pygame.mixer.music.set_volume"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_volume()</span></code></a> will have no effect during
|
||||
this time. If an event was set using <a class="reference internal" href="#pygame.mixer.music.set_endevent" title="pygame.mixer.music.set_endevent"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_endevent()</span></code></a> it will be
|
||||
called after the music has faded.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.set_volume">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">set_volume</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.set_volume" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the music volume</span></div>
|
||||
<div class="line"><span class="signature">set_volume(volume) -> None</span></div>
|
||||
</div>
|
||||
<p>Set the volume of the music playback.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">volume</span></code> argument is a float between <code class="docutils literal notranslate"><span class="pre">0.0</span></code> and <code class="docutils literal notranslate"><span class="pre">1.0</span></code> that sets
|
||||
the volume level. When new music is loaded the volume is reset to full
|
||||
volume. If <code class="docutils literal notranslate"><span class="pre">volume</span></code> is a negative value it will be ignored and the
|
||||
volume will remain set at the current level. If the <code class="docutils literal notranslate"><span class="pre">volume</span></code> argument
|
||||
is greater than <code class="docutils literal notranslate"><span class="pre">1.0</span></code>, the volume will be set to <code class="docutils literal notranslate"><span class="pre">1.0</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.get_volume">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">get_volume</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.get_volume" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the music volume</span></div>
|
||||
<div class="line"><span class="signature">get_volume() -> value</span></div>
|
||||
</div>
|
||||
<p>Returns the current volume for the mixer. The value will be between <code class="docutils literal notranslate"><span class="pre">0.0</span></code>
|
||||
and <code class="docutils literal notranslate"><span class="pre">1.0</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.get_busy">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">get_busy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.get_busy" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">check if the music stream is playing</span></div>
|
||||
<div class="line"><span class="signature">get_busy() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns True when the music stream is actively playing. When the music is
|
||||
idle this returns False. In pygame 2.0.1 and above this function returns
|
||||
False when the music is paused. In pygame 1 it returns True when the music
|
||||
is paused.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.1: </span>Returns False when music paused.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.set_pos">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">set_pos</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.set_pos" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set position to play from</span></div>
|
||||
<div class="line"><span class="signature">set_pos(pos) -> None</span></div>
|
||||
</div>
|
||||
<p>This sets the position in the music file where playback will start.
|
||||
The meaning of "pos", a float (or a number that can be converted to a float),
|
||||
depends on the music format.</p>
|
||||
<p>For <code class="docutils literal notranslate"><span class="pre">MOD</span></code> files, pos is the integer pattern number in the module.
|
||||
For <code class="docutils literal notranslate"><span class="pre">OGG</span></code> it is the absolute position, in seconds, from
|
||||
the beginning of the sound. For <code class="docutils literal notranslate"><span class="pre">MP3</span></code> files, it is the relative position,
|
||||
in seconds, from the current position. For absolute positioning in an <code class="docutils literal notranslate"><span class="pre">MP3</span></code>
|
||||
file, first call <a class="reference internal" href="#pygame.mixer.music.rewind" title="pygame.mixer.music.rewind"><code class="xref py py-func docutils literal notranslate"><span class="pre">rewind()</span></code></a>.</p>
|
||||
<p>Other file formats are unsupported. Newer versions of SDL_mixer have
|
||||
better positioning support than earlier ones. An SDLError is raised if a
|
||||
particular format does not support positioning.</p>
|
||||
<p>Function <a class="reference internal" href="#pygame.mixer.music.set_pos" title="pygame.mixer.music.set_pos"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_pos()</span></code></a> calls underlining SDL_mixer function
|
||||
<code class="docutils literal notranslate"><span class="pre">Mix_SetMusicPosition</span></code>.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.get_pos">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">get_pos</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.get_pos" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the music play time</span></div>
|
||||
<div class="line"><span class="signature">get_pos() -> time</span></div>
|
||||
</div>
|
||||
<p>This gets the number of milliseconds that the music has been playing for.
|
||||
The returned time only represents how long the music has been playing; it
|
||||
does not take into account any starting position offsets.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.queue">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">queue</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.queue" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">queue a sound file to follow the current</span></div>
|
||||
<div class="line"><span class="signature">queue(filename) -> None</span></div>
|
||||
<div class="line"><span class="signature">queue(fileobj, namehint="", loops=0) -> None</span></div>
|
||||
</div>
|
||||
<p>This will load a sound file and queue it. A queued sound file will begin as
|
||||
soon as the current sound naturally ends. Only one sound can be queued at a
|
||||
time. Queuing a new sound while another sound is queued will result in the
|
||||
new sound becoming the queued sound. Also, if the current sound is ever
|
||||
stopped or changed, the queued sound will be lost.</p>
|
||||
<p>If you are loading from a file object, the namehint parameter can be used to specify
|
||||
the type of music data in the object. For example: <code class="code docutils literal notranslate"><span class="pre">queue(fileobj,</span> <span class="pre">"ogg")</span></code>.</p>
|
||||
<p>The following example will play music by Bach six times, then play music by
|
||||
Mozart once:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pygame</span><span class="o">.</span><span class="n">mixer</span><span class="o">.</span><span class="n">music</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="s1">'bach.ogg'</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">mixer</span><span class="o">.</span><span class="n">music</span><span class="o">.</span><span class="n">play</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span> <span class="c1"># Plays six times, not five!</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">mixer</span><span class="o">.</span><span class="n">music</span><span class="o">.</span><span class="n">queue</span><span class="p">(</span><span class="s1">'mozart.ogg'</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2: </span>Added optional <code class="docutils literal notranslate"><span class="pre">namehint</span></code> argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.set_endevent">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">set_endevent</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.set_endevent" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">have the music send an event when playback stops</span></div>
|
||||
<div class="line"><span class="signature">set_endevent() -> None</span></div>
|
||||
<div class="line"><span class="signature">set_endevent(type) -> None</span></div>
|
||||
</div>
|
||||
<p>This causes pygame to signal (by means of the event queue) when the music is
|
||||
done playing. The argument determines the type of event that will be queued.</p>
|
||||
<p>The event will be queued every time the music finishes, not just the first
|
||||
time. To stop the event from being queued, call this method with no
|
||||
argument.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.mixer.music.get_endevent">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.mixer.music.</span></span><span class="sig-name descname"><span class="pre">get_endevent</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.mixer.music.get_endevent" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the event a channel sends when playback stops</span></div>
|
||||
<div class="line"><span class="signature">get_endevent() -> type</span></div>
|
||||
</div>
|
||||
<p>Returns the event type to be sent every time the music finishes playback. If
|
||||
there is no endevent the function returns <code class="docutils literal notranslate"><span class="pre">pygame.NOEVENT</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/music.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="overlay.html" title="pygame.Overlay"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="mouse.html" title="pygame.mouse"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.mixer.music</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,222 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.Overlay — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.PixelArray" href="pixelarray.html" />
|
||||
<link rel="prev" title="pygame.mixer.music" href="music.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="pygame-overlay">
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>This module is non functional in pygame 2.0 and above, unless you have manually compiled pygame with SDL1.
|
||||
This module will not be supported in the future.</p>
|
||||
</div>
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Overlay">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">Overlay</span></span><a class="headerlink" href="#pygame.Overlay" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame object for video overlay graphics</span></div>
|
||||
<div class="line"><span class="signature">Overlay(format, (width, height)) -> Overlay</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="overlay.html#pygame.Overlay.display">pygame.Overlay.display</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the overlay pixel data</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="overlay.html#pygame.Overlay.set_location">pygame.Overlay.set_location</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>control where the overlay is displayed</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="overlay.html#pygame.Overlay.get_hardware">pygame.Overlay.get_hardware</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if the Overlay is hardware accelerated</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The Overlay objects provide support for accessing hardware video overlays.
|
||||
Video overlays do not use standard <code class="docutils literal notranslate"><span class="pre">RGB</span></code> pixel formats, and can use
|
||||
multiple resolutions of data to create a single image.</p>
|
||||
<p>The Overlay objects represent lower level access to the display hardware. To
|
||||
use the object you must understand the technical details of video overlays.</p>
|
||||
<p>The Overlay format determines the type of pixel data used. Not all hardware
|
||||
will support all types of overlay formats. Here is a list of available
|
||||
format types:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">YV12_OVERLAY</span><span class="p">,</span> <span class="n">IYUV_OVERLAY</span><span class="p">,</span> <span class="n">YUY2_OVERLAY</span><span class="p">,</span> <span class="n">UYVY_OVERLAY</span><span class="p">,</span> <span class="n">YVYU_OVERLAY</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The width and height arguments control the size for the overlay image data.
|
||||
The overlay image can be displayed at any size, not just the resolution of
|
||||
the overlay.</p>
|
||||
<p>The overlay objects are always visible, and always show above the regular
|
||||
display contents.</p>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Overlay.display">
|
||||
<span class="sig-name descname"><span class="pre">display</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Overlay.display" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the overlay pixel data</span></div>
|
||||
<div class="line"><span class="signature">display((y, u, v)) -> None</span></div>
|
||||
<div class="line"><span class="signature">display() -> None</span></div>
|
||||
</div>
|
||||
<p>Display the YUV data in SDL's overlay planes. The y, u, and v arguments
|
||||
are strings of binary data. The data must be in the correct format used
|
||||
to create the Overlay.</p>
|
||||
<p>If no argument is passed in, the Overlay will simply be redrawn with the
|
||||
current data. This can be useful when the Overlay is not really hardware
|
||||
accelerated.</p>
|
||||
<p>The strings are not validated, and improperly sized strings could crash
|
||||
the program.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Overlay.set_location">
|
||||
<span class="sig-name descname"><span class="pre">set_location</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Overlay.set_location" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">control where the overlay is displayed</span></div>
|
||||
<div class="line"><span class="signature">set_location(rect) -> None</span></div>
|
||||
</div>
|
||||
<p>Set the location for the overlay. The overlay will always be shown
|
||||
relative to the main display Surface. This does not actually redraw the
|
||||
overlay, it will be updated on the next call to <code class="docutils literal notranslate"><span class="pre">Overlay.display()</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Overlay.get_hardware">
|
||||
<span class="sig-name descname"><span class="pre">get_hardware</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Overlay.get_hardware" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if the Overlay is hardware accelerated</span></div>
|
||||
<div class="line"><span class="signature">get_hardware(rect) -> int</span></div>
|
||||
</div>
|
||||
<p>Returns a True value when the Overlay is hardware accelerated. If the
|
||||
platform does not support acceleration, software rendering is used.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/overlay.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="pixelarray.html" title="pygame.PixelArray"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="music.html" title="pygame.mixer.music"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.Overlay</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,477 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.PixelArray — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.pixelcopy" href="pixelcopy.html" />
|
||||
<link rel="prev" title="pygame.Overlay" href="overlay.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="pygame-pixelarray">
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">PixelArray</span></span><a class="headerlink" href="#pygame.PixelArray" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame object for direct pixel access of surfaces</span></div>
|
||||
<div class="line"><span class="signature">PixelArray(Surface) -> PixelArray</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.surface">pygame.PixelArray.surface</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the Surface the PixelArray uses.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.itemsize">pygame.PixelArray.itemsize</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns the byte size of a pixel array item</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.ndim">pygame.PixelArray.ndim</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns the number of dimensions.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.shape">pygame.PixelArray.shape</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns the array size.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.strides">pygame.PixelArray.strides</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns byte offsets for each array dimension.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.make_surface">pygame.PixelArray.make_surface</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Creates a new Surface from the current PixelArray.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.replace">pygame.PixelArray.replace</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Replaces the passed color in the PixelArray with another one.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.extract">pygame.PixelArray.extract</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Extracts the passed color from the PixelArray.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.compare">pygame.PixelArray.compare</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Compares the PixelArray with another one.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.transpose">pygame.PixelArray.transpose</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Exchanges the x and y axis.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pixelarray.html#pygame.PixelArray.close">pygame.PixelArray.close</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Closes the PixelArray, and releases Surface lock.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The PixelArray wraps a Surface and provides direct access to the
|
||||
surface's pixels. A pixel array can be one or two dimensional.
|
||||
A two dimensional array, like its surface, is indexed [column, row].
|
||||
Pixel arrays support slicing, both for returning a subarray or
|
||||
for assignment. A pixel array sliced on a single column or row
|
||||
returns a one dimensional pixel array. Arithmetic and other operations
|
||||
are not supported. A pixel array can be safely assigned to itself.
|
||||
Finally, pixel arrays export an array struct interface, allowing
|
||||
them to interact with <a class="tooltip reference internal" href="pixelcopy.html#module-pygame.pixelcopy" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.pixelcopy</span></code><span class="tooltip-content">pygame module for general pixel array copying</span></a> methods and NumPy
|
||||
arrays.</p>
|
||||
<p>A PixelArray pixel item can be assigned a raw integer values, a
|
||||
<a class="tooltip reference internal" href="color.html#pygame.Color" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.Color</span></code><span class="tooltip-content">pygame object for color representations</span></a> instance, or a (r, g, b[, a]) tuple.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pxarray</span><span class="p">[</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">]</span> <span class="o">=</span> <span class="mh">0xFF00FF</span>
|
||||
<span class="n">pxarray</span><span class="p">[</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">]</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">Color</span><span class="p">(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">255</span><span class="p">)</span>
|
||||
<span class="n">pxarray</span><span class="p">[</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">255</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>However, only a pixel's integer value is returned. So, to compare a pixel
|
||||
to a particular color the color needs to be first mapped using
|
||||
the <a class="reference internal" href="surface.html#pygame.Surface.map_rgb" title="pygame.Surface.map_rgb"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Surface.map_rgb()</span></code></a> method of the Surface object for which the
|
||||
PixelArray was created.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pxarray</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">PixelArray</span><span class="p">(</span><span class="n">surface</span><span class="p">)</span>
|
||||
<span class="c1"># Check, if the first pixel at the topleft corner is blue</span>
|
||||
<span class="k">if</span> <span class="n">pxarray</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="n">surface</span><span class="o">.</span><span class="n">map_rgb</span><span class="p">((</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">255</span><span class="p">)):</span>
|
||||
<span class="o">...</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>When assigning to a range of of pixels, a non tuple sequence of colors or
|
||||
a PixelArray can be used as the value. For a sequence, the length must
|
||||
match the PixelArray width.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pxarray</span><span class="p">[</span><span class="n">a</span><span class="p">:</span><span class="n">b</span><span class="p">]</span> <span class="o">=</span> <span class="mh">0xFF00FF</span> <span class="c1"># set all pixels to 0xFF00FF</span>
|
||||
<span class="n">pxarray</span><span class="p">[</span><span class="n">a</span><span class="p">:</span><span class="n">b</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mh">0xFF00FF</span><span class="p">,</span> <span class="mh">0xAACCEE</span><span class="p">,</span> <span class="o">...</span> <span class="p">)</span> <span class="c1"># first pixel = 0xFF00FF,</span>
|
||||
<span class="c1"># second pixel = 0xAACCEE, ...</span>
|
||||
<span class="n">pxarray</span><span class="p">[</span><span class="n">a</span><span class="p">:</span><span class="n">b</span><span class="p">]</span> <span class="o">=</span> <span class="p">[(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">255</span><span class="p">),</span> <span class="p">(</span><span class="mi">170</span><span class="p">,</span> <span class="mi">204</span><span class="p">,</span> <span class="mi">238</span><span class="p">),</span> <span class="o">...</span><span class="p">]</span> <span class="c1"># same as above</span>
|
||||
<span class="n">pxarray</span><span class="p">[</span><span class="n">a</span><span class="p">:</span><span class="n">b</span><span class="p">]</span> <span class="o">=</span> <span class="p">[(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">255</span><span class="p">),</span> <span class="mh">0xAACCEE</span><span class="p">,</span> <span class="o">...</span><span class="p">]</span> <span class="c1"># same as above</span>
|
||||
<span class="n">pxarray</span><span class="p">[</span><span class="n">a</span><span class="p">:</span><span class="n">b</span><span class="p">]</span> <span class="o">=</span> <span class="n">otherarray</span><span class="p">[</span><span class="n">x</span><span class="p">:</span><span class="n">y</span><span class="p">]</span> <span class="c1"># slice sizes must match</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For PixelArray assignment, if the right hand side array has a row length
|
||||
of 1, then the column is broadcast over the target array's rows. An
|
||||
array of height 1 is broadcast over the target's columns, and is equivalent
|
||||
to assigning a 1D PixelArray.</p>
|
||||
<p>Subscript slices can also be used to assign to a rectangular subview of
|
||||
the target PixelArray.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create some new PixelArray objects providing a different view</span>
|
||||
<span class="c1"># of the original array/surface.</span>
|
||||
<span class="n">newarray</span> <span class="o">=</span> <span class="n">pxarray</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span>
|
||||
<span class="n">otherarray</span> <span class="o">=</span> <span class="n">pxarray</span><span class="p">[::</span><span class="mi">2</span><span class="p">,</span> <span class="p">::</span><span class="mi">2</span><span class="p">]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Subscript slices can also be used to do fast rectangular pixel manipulations
|
||||
instead of iterating over the x or y axis. The</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pxarray</span><span class="p">[::</span><span class="mi">2</span><span class="p">,</span> <span class="p">:]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="c1"># Make even columns black.</span>
|
||||
<span class="n">pxarray</span><span class="p">[::</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="c1"># Same as [::2, :]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>During its lifetime, the PixelArray locks the surface, thus you explicitly
|
||||
have to close() it once its not used any more and the surface should perform
|
||||
operations in the same scope. It is best to use it as a context manager
|
||||
using the with PixelArray(surf) as pixel_array: style. So it works on pypy too.</p>
|
||||
<p>A simple <code class="docutils literal notranslate"><span class="pre">:</span></code> slice index for the column can be omitted.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pxarray</span><span class="p">[::</span><span class="mi">2</span><span class="p">,</span> <span class="o">...</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="c1"># Same as pxarray[::2, :]</span>
|
||||
<span class="n">pxarray</span><span class="p">[</span><span class="o">...</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="c1"># Same as pxarray[:]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>A note about PixelArray to PixelArray assignment, for arrays with an
|
||||
item size of 3 (created from 24 bit surfaces) pixel values are translated
|
||||
from the source to the destinations format. The red, green, and blue
|
||||
color elements of each pixel are shifted to match the format of the
|
||||
target surface. For all other pixel sizes no such remapping occurs.
|
||||
This should change in later pygame releases, where format conversions
|
||||
are performed for all pixel sizes. To avoid code breakage when full mapped
|
||||
copying is implemented it is suggested PixelArray to PixelArray copies be
|
||||
only between surfaces of identical format.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.4: </span></p>
|
||||
<ul class="simple">
|
||||
<li><p>close() method was added. For explicitly cleaning up.</p></li>
|
||||
<li><p>being able to use PixelArray as a context manager for cleanup.</p></li>
|
||||
<li><p>both of these are useful for when working without reference counting (pypy).</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2: </span></p>
|
||||
<ul class="simple">
|
||||
<li><p>array struct interface</p></li>
|
||||
<li><p>transpose method</p></li>
|
||||
<li><p>broadcasting for a length 1 dimension</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.2: </span></p>
|
||||
<ul class="simple">
|
||||
<li><p>A 2D PixelArray can have a length 1 dimension.
|
||||
Only an integer index on a 2D PixelArray returns a 1D array.</p></li>
|
||||
<li><p>For assignment, a tuple can only be a color. Any other sequence type
|
||||
is a sequence of colors.</p></li>
|
||||
</ul>
|
||||
</div>
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.surface">
|
||||
<span class="sig-name descname"><span class="pre">surface</span></span><a class="headerlink" href="#pygame.PixelArray.surface" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the Surface the PixelArray uses.</span></div>
|
||||
<div class="line"><span class="signature">surface -> Surface</span></div>
|
||||
</div>
|
||||
<p>The Surface the PixelArray was created for.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.itemsize">
|
||||
<span class="sig-name descname"><span class="pre">itemsize</span></span><a class="headerlink" href="#pygame.PixelArray.itemsize" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns the byte size of a pixel array item</span></div>
|
||||
<div class="line"><span class="signature">itemsize -> int</span></div>
|
||||
</div>
|
||||
<p>This is the same as <a class="reference internal" href="surface.html#pygame.Surface.get_bytesize" title="pygame.Surface.get_bytesize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Surface.get_bytesize()</span></code></a> for the
|
||||
pixel array's surface.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.ndim">
|
||||
<span class="sig-name descname"><span class="pre">ndim</span></span><a class="headerlink" href="#pygame.PixelArray.ndim" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns the number of dimensions.</span></div>
|
||||
<div class="line"><span class="signature">ndim -> int</span></div>
|
||||
</div>
|
||||
<p>A pixel array can be 1 or 2 dimensional.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.shape">
|
||||
<span class="sig-name descname"><span class="pre">shape</span></span><a class="headerlink" href="#pygame.PixelArray.shape" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns the array size.</span></div>
|
||||
<div class="line"><span class="signature">shape -> tuple of int's</span></div>
|
||||
</div>
|
||||
<p>A tuple or length <a class="reference internal" href="#pygame.PixelArray.ndim" title="pygame.PixelArray.ndim"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ndim</span></code></a> giving the length of each
|
||||
dimension. Analogous to <a class="reference internal" href="surface.html#pygame.Surface.get_size" title="pygame.Surface.get_size"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Surface.get_size()</span></code></a>.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py attribute definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.strides">
|
||||
<span class="sig-name descname"><span class="pre">strides</span></span><a class="headerlink" href="#pygame.PixelArray.strides" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns byte offsets for each array dimension.</span></div>
|
||||
<div class="line"><span class="signature">strides -> tuple of int's</span></div>
|
||||
</div>
|
||||
<p>A tuple or length <a class="reference internal" href="#pygame.PixelArray.ndim" title="pygame.PixelArray.ndim"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ndim</span></code></a> byte counts. When a stride is
|
||||
multiplied by the corresponding index it gives the offset
|
||||
of that index from the start of the array. A stride is negative
|
||||
for an array that has is inverted (has a negative step).</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.make_surface">
|
||||
<span class="sig-name descname"><span class="pre">make_surface</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.PixelArray.make_surface" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Creates a new Surface from the current PixelArray.</span></div>
|
||||
<div class="line"><span class="signature">make_surface() -> Surface</span></div>
|
||||
</div>
|
||||
<p>Creates a new Surface from the current PixelArray. Depending on the
|
||||
current PixelArray the size, pixel order etc. will be different from the
|
||||
original Surface.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create a new surface flipped around the vertical axis.</span>
|
||||
<span class="n">sf</span> <span class="o">=</span> <span class="n">pxarray</span><span class="p">[:,::</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">make_surface</span> <span class="p">()</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.replace">
|
||||
<span class="sig-name descname"><span class="pre">replace</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.PixelArray.replace" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Replaces the passed color in the PixelArray with another one.</span></div>
|
||||
<div class="line"><span class="signature">replace(color, repcolor, distance=0, weights=(0.299, 0.587, 0.114)) -> None</span></div>
|
||||
</div>
|
||||
<p>Replaces the pixels with the passed color in the PixelArray by changing
|
||||
them them to the passed replacement color.</p>
|
||||
<p>It uses a simple weighted Euclidean distance formula to calculate the
|
||||
distance between the colors. The distance space ranges from 0.0 to 1.0
|
||||
and is used as threshold for the color detection. This causes the
|
||||
replacement to take pixels with a similar, but not exactly identical
|
||||
color, into account as well.</p>
|
||||
<p>This is an in place operation that directly affects the pixels of the
|
||||
PixelArray.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.extract">
|
||||
<span class="sig-name descname"><span class="pre">extract</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.PixelArray.extract" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Extracts the passed color from the PixelArray.</span></div>
|
||||
<div class="line"><span class="signature">extract(color, distance=0, weights=(0.299, 0.587, 0.114)) -> PixelArray</span></div>
|
||||
</div>
|
||||
<p>Extracts the passed color by changing all matching pixels to white, while
|
||||
non-matching pixels are changed to black. This returns a new PixelArray
|
||||
with the black/white color mask.</p>
|
||||
<p>It uses a simple weighted Euclidean distance formula to calculate the
|
||||
distance between the colors. The distance space ranges from 0.0 to 1.0
|
||||
and is used as threshold for the color detection. This causes the
|
||||
extraction to take pixels with a similar, but not exactly identical
|
||||
color, into account as well.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.compare">
|
||||
<span class="sig-name descname"><span class="pre">compare</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.PixelArray.compare" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Compares the PixelArray with another one.</span></div>
|
||||
<div class="line"><span class="signature">compare(array, distance=0, weights=(0.299, 0.587, 0.114)) -> PixelArray</span></div>
|
||||
</div>
|
||||
<p>Compares the contents of the PixelArray with those from the passed in
|
||||
PixelArray. It returns a new PixelArray with a black/white color mask
|
||||
that indicates the differences (black) of both arrays. Both PixelArray
|
||||
objects must have identical bit depths and dimensions.</p>
|
||||
<p>It uses a simple weighted Euclidean distance formula to calculate the
|
||||
distance between the colors. The distance space ranges from 0.0 to 1.0
|
||||
and is used as a threshold for the color detection. This causes the
|
||||
comparison to mark pixels with a similar, but not exactly identical
|
||||
color, as white.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.transpose">
|
||||
<span class="sig-name descname"><span class="pre">transpose</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.PixelArray.transpose" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Exchanges the x and y axis.</span></div>
|
||||
<div class="line"><span class="signature">transpose() -> PixelArray</span></div>
|
||||
</div>
|
||||
<p>This method returns a new view of the pixel array with the rows and
|
||||
columns swapped. So for a (w, h) sized array a (h, w) slice is returned.
|
||||
If an array is one dimensional, then a length 1 x dimension is added,
|
||||
resulting in a 2D pixel array.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.PixelArray.close">
|
||||
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.PixelArray.close" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Closes the PixelArray, and releases Surface lock.</span></div>
|
||||
<div class="line"><span class="signature">close() -> PixelArray</span></div>
|
||||
</div>
|
||||
<p>This method is for explicitly closing the PixelArray, and releasing
|
||||
a lock on the Surface.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.4.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/pixelarray.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="pixelcopy.html" title="pygame.pixelcopy"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="overlay.html" title="pygame.Overlay"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.PixelArray</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,253 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.pixelcopy — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame" href="pygame.html" />
|
||||
<link rel="prev" title="pygame.PixelArray" href="pixelarray.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.pixelcopy">
|
||||
<span id="pygame-pixelcopy"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.pixelcopy</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for general pixel array copying</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pixelcopy.html#pygame.pixelcopy.surface_to_array">pygame.pixelcopy.surface_to_array</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>copy surface pixels to an array object</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pixelcopy.html#pygame.pixelcopy.array_to_surface">pygame.pixelcopy.array_to_surface</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>copy an array object to a surface</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pixelcopy.html#pygame.pixelcopy.map_array">pygame.pixelcopy.map_array</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>copy an array to another array, using surface format</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pixelcopy.html#pygame.pixelcopy.make_surface">pygame.pixelcopy.make_surface</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy an array to a new surface</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">pygame.pixelcopy</span></code> module contains functions for copying between
|
||||
surfaces and objects exporting an array structure interface. It is a backend
|
||||
for <a class="tooltip reference internal" href="surfarray.html#module-pygame.surfarray" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.surfarray</span></code><span class="tooltip-content">pygame module for accessing surface pixel data using array interfaces</span></a>, adding NumPy support. But pixelcopy is more
|
||||
general, and intended for direct use.</p>
|
||||
<p>The array struct interface exposes an array's data in a standard way.
|
||||
It was introduced in NumPy. In Python 2.7 and above it is replaced by the
|
||||
new buffer protocol, though the buffer protocol is still a work in progress.
|
||||
The array struct interface, on the other hand, is stable and works with earlier
|
||||
Python versions. So for now the array struct interface is the predominate way
|
||||
pygame handles array introspection.</p>
|
||||
<p>For 2d arrays of integer pixel values, the values are mapped to the
|
||||
pixel format of the related surface. To get the actual color of a pixel
|
||||
value use <a class="tooltip reference internal" href="surface.html#pygame.Surface.unmap_rgb" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.unmap_rgb()</span></code><span class="tooltip-content">convert a mapped integer color value into a Color</span></a>. 2d arrays can only be used
|
||||
directly between surfaces having the same pixel layout.</p>
|
||||
<p>New in pygame 1.9.2.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.pixelcopy.surface_to_array">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.pixelcopy.</span></span><span class="sig-name descname"><span class="pre">surface_to_array</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.pixelcopy.surface_to_array" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">copy surface pixels to an array object</span></div>
|
||||
<div class="line"><span class="signature">surface_to_array(array, surface, kind='P', opaque=255, clear=0) -> None</span></div>
|
||||
</div>
|
||||
<p>The surface_to_array function copies pixels from a Surface object
|
||||
to a 2D or 3D array. Depending on argument <code class="docutils literal notranslate"><span class="pre">kind</span></code> and the target array
|
||||
dimension, a copy may be raw pixel value, RGB, a color component slice,
|
||||
or colorkey alpha transparency value. Recognized <code class="docutils literal notranslate"><span class="pre">kind</span></code> values are the
|
||||
single character codes 'P', 'R', 'G', 'B', 'A', and 'C'. Kind codes are case
|
||||
insensitive, so 'p' is equivalent to 'P'. The first two dimensions
|
||||
of the target must be the surface size (w, h).</p>
|
||||
<p>The default 'P' kind code does a direct raw integer pixel (mapped) value
|
||||
copy to a 2D array and a 'RGB' pixel component (unmapped) copy to a 3D array
|
||||
having shape (w, h, 3). For an 8 bit colormap surface this means the
|
||||
table index is copied to a 2D array, not the table value itself. A 2D
|
||||
array's item size must be at least as large as the surface's pixel
|
||||
byte size. The item size of a 3D array must be at least one byte.</p>
|
||||
<p>For the 'R', 'G', 'B', and 'A' copy kinds a single color component
|
||||
of the unmapped surface pixels are copied to the target 2D array.
|
||||
For kind 'A' and surfaces with source alpha (the surface was created with
|
||||
the SRCALPHA flag), has a colorkey
|
||||
(set with <a class="reference internal" href="surface.html#pygame.Surface.set_colorkey" title="pygame.Surface.set_colorkey"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Surface.set_colorkey()</span></code></a>),
|
||||
or has a blanket alpha
|
||||
(set with <a class="reference internal" href="surface.html#pygame.Surface.set_alpha" title="pygame.Surface.set_alpha"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Surface.set_alpha()</span></code></a>)
|
||||
then the alpha values are those expected for a SDL surface.
|
||||
If a surface has no explicit alpha value, then the target array
|
||||
is filled with the value of the optional <code class="docutils literal notranslate"><span class="pre">opaque</span></code> surface_to_array
|
||||
argument (default 255: not transparent).</p>
|
||||
<p>Copy kind 'C' is a special case for alpha copy of a source surface
|
||||
with colorkey. Unlike the 'A' color component copy, the <code class="docutils literal notranslate"><span class="pre">clear</span></code>
|
||||
argument value is used for colorkey matches, <code class="docutils literal notranslate"><span class="pre">opaque</span></code> otherwise.
|
||||
By default, a match has alpha 0 (totally transparent), while everything
|
||||
else is alpha 255 (totally opaque). It is a more general implementation
|
||||
of <a class="tooltip reference internal" href="surfarray.html#pygame.surfarray.array_colorkey" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.surfarray.array_colorkey()</span></code><span class="tooltip-content">Copy the colorkey values into a 2d array</span></a>.</p>
|
||||
<p>Specific to surface_to_array, a ValueError is raised for target arrays
|
||||
with incorrect shape or item size. A TypeError is raised for an incorrect
|
||||
kind code. Surface specific problems, such as locking, raise a pygame.error.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.pixelcopy.array_to_surface">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.pixelcopy.</span></span><span class="sig-name descname"><span class="pre">array_to_surface</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.pixelcopy.array_to_surface" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">copy an array object to a surface</span></div>
|
||||
<div class="line"><span class="signature">array_to_surface(<surface>, <array>) -> None</span></div>
|
||||
</div>
|
||||
<p>See <a class="tooltip reference internal" href="surfarray.html#pygame.surfarray.blit_array" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.surfarray.blit_array()</span></code><span class="tooltip-content">Blit directly from a array values</span></a>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.pixelcopy.map_array">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.pixelcopy.</span></span><span class="sig-name descname"><span class="pre">map_array</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.pixelcopy.map_array" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">copy an array to another array, using surface format</span></div>
|
||||
<div class="line"><span class="signature">map_array(<array>, <array>, <surface>) -> None</span></div>
|
||||
</div>
|
||||
<p>Map an array of color element values - (w, h, ..., 3) - to an array of
|
||||
pixels - (w, h) according to the format of <surface>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.pixelcopy.make_surface">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.pixelcopy.</span></span><span class="sig-name descname"><span class="pre">make_surface</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.pixelcopy.make_surface" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy an array to a new surface</span></div>
|
||||
<div class="line"><span class="signature">pygame.pixelcopy.make_surface(array) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Create a new Surface that best resembles the data and format of the array.
|
||||
The array can be 2D or 3D with any sized integer values.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/pixelcopy.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="pygame.html" title="pygame"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="pixelarray.html" title="pygame.PixelArray"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.pixelcopy</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,696 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.Rect" href="rect.html" />
|
||||
<link rel="prev" title="pygame.pixelcopy" href="pixelcopy.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame">
|
||||
<span id="pygame"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">the top level pygame package</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.init">pygame.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>initialize all imported pygame modules</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.quit">pygame.quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>uninitialize all pygame modules</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.get_init">pygame.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>returns True if pygame is currently initialized</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.error">pygame.error</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>standard pygame exception</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.get_error">pygame.get_error</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the current error message</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.set_error">pygame.set_error</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set the current error message</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.get_sdl_version">pygame.get_sdl_version</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the version number of SDL</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.get_sdl_byteorder">pygame.get_sdl_byteorder</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the byte order of SDL</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.register_quit">pygame.register_quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>register a function to be called when pygame quits</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.encode_string">pygame.encode_string</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Encode a Unicode or bytes object</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.encode_file_path">pygame.encode_file_path</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Encode a Unicode or bytes object as a file system path</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The pygame package represents the top-level package for others to use. Pygame
|
||||
itself is broken into many submodules, but this does not affect programs that
|
||||
use pygame.</p>
|
||||
<p>As a convenience, most of the top-level variables in pygame have been placed
|
||||
inside a module named <a class="tooltip reference internal" href="locals.html#module-pygame.locals" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.locals</span></code><span class="tooltip-content">pygame constants</span></a>. This is meant to be used with
|
||||
<code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">pygame.locals</span> <span class="pre">import</span> <span class="pre">*</span></code>, in addition to <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">pygame</span></code>.</p>
|
||||
<p>When you <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">pygame</span></code> all available pygame submodules are automatically
|
||||
imported. Be aware that some of the pygame modules are considered <em>optional</em>,
|
||||
and may not be available. In that case, pygame will provide a placeholder
|
||||
object instead of the module, which can be used to test for availability.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">initialize all imported pygame modules</span></div>
|
||||
<div class="line"><span class="signature">init() -> (numpass, numfail)</span></div>
|
||||
</div>
|
||||
<p>Initialize all imported pygame modules. No exceptions will be raised if a
|
||||
module fails, but the total number if successful and failed inits will be
|
||||
returned as a tuple. You can always initialize individual modules manually,
|
||||
but <a class="tooltip reference internal" href="#pygame.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.init()</span></code><span class="tooltip-content">initialize all imported pygame modules</span></a> is a convenient way to get everything started. The
|
||||
<code class="docutils literal notranslate"><span class="pre">init()</span></code> functions for individual modules will raise exceptions when they
|
||||
fail.</p>
|
||||
<p>You may want to initialize the different modules separately to speed up your
|
||||
program or to not use modules your game does not require.</p>
|
||||
<p>It is safe to call this <code class="docutils literal notranslate"><span class="pre">init()</span></code> more than once as repeated calls will have
|
||||
no effect. This is true even if you have <code class="docutils literal notranslate"><span class="pre">pygame.quit()</span></code> all the modules.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.quit">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">uninitialize all pygame modules</span></div>
|
||||
<div class="line"><span class="signature">quit() -> None</span></div>
|
||||
</div>
|
||||
<p>Uninitialize all pygame modules that have previously been initialized. When
|
||||
the Python interpreter shuts down, this method is called regardless, so your
|
||||
program should not need it, except when it wants to terminate its pygame
|
||||
resources and continue. It is safe to call this function more than once as
|
||||
repeated calls have no effect.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Calling <a class="tooltip reference internal" href="#pygame.quit" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.quit()</span></code><span class="tooltip-content">uninitialize all pygame modules</span></a> will not exit your program. Consider letting
|
||||
your program end in the same way a normal Python program will end.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.get_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">returns True if pygame is currently initialized</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if pygame is currently initialized.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.5.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py exception definition">
|
||||
<dt class="sig sig-object py title" id="pygame.error">
|
||||
<em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">error</span></span><a class="headerlink" href="#pygame.error" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">standard pygame exception</span></div>
|
||||
<div class="line"><span class="signature">raise pygame.error(message)</span></div>
|
||||
</div>
|
||||
<p>This exception is raised whenever a pygame or SDL operation fails. You
|
||||
can catch any anticipated problems and deal with the error. The exception is
|
||||
always raised with a descriptive message about the problem.</p>
|
||||
<p>Derived from the <code class="docutils literal notranslate"><span class="pre">RuntimeError</span></code> exception, which can also be used to catch
|
||||
these raised errors.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.get_error">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">get_error</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.get_error" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the current error message</span></div>
|
||||
<div class="line"><span class="signature">get_error() -> errorstr</span></div>
|
||||
</div>
|
||||
<p>SDL maintains an internal error message. This message will usually be
|
||||
given to you when <a class="tooltip reference internal" href="#pygame.error" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.error()</span></code><span class="tooltip-content">standard pygame exception</span></a> is raised, so this function will
|
||||
rarely be needed.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.set_error">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">set_error</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.set_error" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set the current error message</span></div>
|
||||
<div class="line"><span class="signature">set_error(error_msg) -> None</span></div>
|
||||
</div>
|
||||
<p>SDL maintains an internal error message. This message will usually be
|
||||
given to you when <a class="tooltip reference internal" href="#pygame.error" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.error()</span></code><span class="tooltip-content">standard pygame exception</span></a> is raised, so this function will
|
||||
rarely be needed.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.get_sdl_version">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">get_sdl_version</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.get_sdl_version" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the version number of SDL</span></div>
|
||||
<div class="line"><span class="signature">get_sdl_version(linked=True) -> major, minor, patch</span></div>
|
||||
</div>
|
||||
<p>Returns the three version numbers of the SDL library. <code class="docutils literal notranslate"><span class="pre">linked=True</span></code>
|
||||
will cause the function to return the version of the library that pygame
|
||||
is linked against while <code class="docutils literal notranslate"><span class="pre">linked=False</span></code> will cause the function to return
|
||||
the version of the library that pygame is compiled against.
|
||||
It can be used to detect which features may or may not be
|
||||
available through pygame.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.7.0.</span></p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.2.0: </span><code class="docutils literal notranslate"><span class="pre">linked</span></code> keyword argument added</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.get_sdl_byteorder">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">get_sdl_byteorder</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.get_sdl_byteorder" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the byte order of SDL</span></div>
|
||||
<div class="line"><span class="signature">get_sdl_byteorder() -> int</span></div>
|
||||
</div>
|
||||
<p>Returns the byte order of the SDL library. It returns <code class="docutils literal notranslate"><span class="pre">1234</span></code> for little
|
||||
endian byte order and <code class="docutils literal notranslate"><span class="pre">4321</span></code> for big endian byte order.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.register_quit">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">register_quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.register_quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">register a function to be called when pygame quits</span></div>
|
||||
<div class="line"><span class="signature">register_quit(callable) -> None</span></div>
|
||||
</div>
|
||||
<p>When <a class="tooltip reference internal" href="#pygame.quit" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.quit()</span></code><span class="tooltip-content">uninitialize all pygame modules</span></a> is called, all registered quit functions are
|
||||
called. Pygame modules do this automatically when they are initializing, so
|
||||
this function will rarely be needed.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.encode_string">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">encode_string</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.encode_string" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Encode a Unicode or bytes object</span></div>
|
||||
<div class="line"><span class="signature">encode_string([obj [, encoding [, errors [, etype]]]]) -> bytes or None</span></div>
|
||||
</div>
|
||||
<p>obj: If Unicode, encode; if bytes, return unaltered; if anything else,
|
||||
return <code class="docutils literal notranslate"><span class="pre">None</span></code>; if not given, raise <code class="docutils literal notranslate"><span class="pre">SyntaxError</span></code>.</p>
|
||||
<p>encoding (string): If present, encoding to use. The default is
|
||||
<code class="docutils literal notranslate"><span class="pre">'unicode_escape'</span></code>.</p>
|
||||
<p>errors (string): If given, how to handle unencodable characters. The default
|
||||
is <code class="docutils literal notranslate"><span class="pre">'backslashreplace'</span></code>.</p>
|
||||
<p>etype (exception type): If given, the exception type to raise for an
|
||||
encoding error. The default is <code class="docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code>, as returned by
|
||||
<code class="docutils literal notranslate"><span class="pre">PyUnicode_AsEncodedString()</span></code>. For the default encoding and errors values
|
||||
there should be no encoding errors.</p>
|
||||
<p>This function is used in encoding file paths. Keyword arguments are
|
||||
supported.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2: </span>(primarily for use in unit tests)</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.encode_file_path">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">encode_file_path</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.encode_file_path" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Encode a Unicode or bytes object as a file system path</span></div>
|
||||
<div class="line"><span class="signature">encode_file_path([obj [, etype]]) -> bytes or None</span></div>
|
||||
</div>
|
||||
<p>obj: If Unicode, encode; if bytes, return unaltered; if anything else,
|
||||
return <code class="docutils literal notranslate"><span class="pre">None</span></code>; if not given, raise <code class="docutils literal notranslate"><span class="pre">SyntaxError</span></code>.</p>
|
||||
<p>etype (exception type): If given, the exception type to raise for an
|
||||
encoding error. The default is <code class="docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code>, as returned by
|
||||
<code class="docutils literal notranslate"><span class="pre">PyUnicode_AsEncodedString()</span></code>.</p>
|
||||
<p>This function is used to encode file paths in pygame. Encoding is to the
|
||||
codec as returned by <code class="docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code>. Keyword arguments are
|
||||
supported.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2: </span>(primarily for use in unit tests)</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
<section id="module-pygame.version">
|
||||
<span id="pygame-version"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.version</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">small module containing version information</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.version.ver">pygame.version.ver</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>version number as a string</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.version.vernum">pygame.version.vernum</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>tupled integers of the version</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.version.rev">pygame.version.rev</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>repository revision of the build</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="pygame.html#pygame.version.SDL">pygame.version.SDL</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>tupled integers of the SDL library version</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>This module is automatically imported into the pygame package and can be used to
|
||||
check which version of pygame has been imported.</p>
|
||||
<dl class="py data definition">
|
||||
<dt class="sig sig-object py title" id="pygame.version.ver">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.version.</span></span><span class="sig-name descname"><span class="pre">ver</span></span><a class="headerlink" href="#pygame.version.ver" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">version number as a string</span></div>
|
||||
<div class="line"><span class="signature">ver = '1.2'</span></div>
|
||||
</div>
|
||||
<p>This is the version represented as a string. It can contain a micro release
|
||||
number as well, e.g. <code class="docutils literal notranslate"><span class="pre">'1.5.2'</span></code></p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py data definition">
|
||||
<dt class="sig sig-object py title" id="pygame.version.vernum">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.version.</span></span><span class="sig-name descname"><span class="pre">vernum</span></span><a class="headerlink" href="#pygame.version.vernum" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">tupled integers of the version</span></div>
|
||||
<div class="line"><span class="signature">vernum = (1, 5, 3)</span></div>
|
||||
</div>
|
||||
<p>This version information can easily be compared with other version
|
||||
numbers of the same format. An example of checking pygame version numbers
|
||||
would look like this:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Warning, older version of pygame (</span><span class="si">%s</span><span class="s1">)'</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><span class="p">)</span>
|
||||
<span class="n">disable_advanced_features</span> <span class="o">=</span> <span class="kc">True</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.6: </span>Attributes <code class="docutils literal notranslate"><span class="pre">major</span></code>, <code class="docutils literal notranslate"><span class="pre">minor</span></code>, and <code class="docutils literal notranslate"><span class="pre">patch</span></code>.</p>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vernum</span><span class="o">.</span><span class="n">major</span> <span class="o">==</span> <span class="n">vernum</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
|
||||
<span class="n">vernum</span><span class="o">.</span><span class="n">minor</span> <span class="o">==</span> <span class="n">vernum</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
|
||||
<span class="n">vernum</span><span class="o">.</span><span class="n">patch</span> <span class="o">==</span> <span class="n">vernum</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.6: </span><code class="docutils literal notranslate"><span class="pre">str(pygame.version.vernum)</span></code> returns a string like <code class="docutils literal notranslate"><span class="pre">"2.0.0"</span></code> instead
|
||||
of <code class="docutils literal notranslate"><span class="pre">"(2,</span> <span class="pre">0,</span> <span class="pre">0)"</span></code>.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.6: </span><code class="docutils literal notranslate"><span class="pre">repr(pygame.version.vernum)</span></code> returns a string like
|
||||
<code class="docutils literal notranslate"><span class="pre">"PygameVersion(major=2,</span> <span class="pre">minor=0,</span> <span class="pre">patch=0)"</span></code> instead of <code class="docutils literal notranslate"><span class="pre">"(2,</span> <span class="pre">0,</span> <span class="pre">0)"</span></code>.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py data definition">
|
||||
<dt class="sig sig-object py title" id="pygame.version.rev">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.version.</span></span><span class="sig-name descname"><span class="pre">rev</span></span><a class="headerlink" href="#pygame.version.rev" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">repository revision of the build</span></div>
|
||||
<div class="line"><span class="signature">rev = 'a6f89747b551+'</span></div>
|
||||
</div>
|
||||
<p>The Mercurial node identifier of the repository checkout from which this
|
||||
package was built. If the identifier ends with a plus sign '+' then the
|
||||
package contains uncommitted changes. Please include this revision number
|
||||
in bug reports, especially for non-release pygame builds.</p>
|
||||
<p>Important note: pygame development has moved to github, this variable is
|
||||
obsolete now. As soon as development shifted to github, this variable started
|
||||
returning an empty string <code class="docutils literal notranslate"><span class="pre">""</span></code>.
|
||||
It has always been returning an empty string since <code class="docutils literal notranslate"><span class="pre">v1.9.5</span></code>.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.5: </span>Always returns an empty string <code class="docutils literal notranslate"><span class="pre">""</span></code>.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py data definition">
|
||||
<dt class="sig sig-object py title" id="pygame.version.SDL">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.version.</span></span><span class="sig-name descname"><span class="pre">SDL</span></span><a class="headerlink" href="#pygame.version.SDL" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">tupled integers of the SDL library version</span></div>
|
||||
<div class="line"><span class="signature">SDL = '(2, 0, 12)'</span></div>
|
||||
</div>
|
||||
<p>This is the SDL library version represented as an extended tuple. It also has
|
||||
attributes 'major', 'minor' & 'patch' that can be accessed like this:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">version</span><span class="o">.</span><span class="n">SDL</span><span class="o">.</span><span class="n">major</span>
|
||||
<span class="go">2</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>printing the whole thing returns a string like this:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">pygame</span><span class="o">.</span><span class="n">version</span><span class="o">.</span><span class="n">SDL</span>
|
||||
<span class="go">SDLVersion(major=2, minor=0, patch=12)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<p id="environment-variables"><strong>Setting Environment Variables</strong></p>
|
||||
<p>Some aspects of pygame's behaviour can be controlled by setting environment variables, they cover a wide
|
||||
range of the library's functionality. Some of the variables are from pygame itself, while others come from
|
||||
the underlying C SDL library that pygame uses.</p>
|
||||
<p>In python, environment variables are usually set in code like this:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
|
||||
<span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s1">'NAME_OF_ENVIRONMENT_VARIABLE'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'value_to_set'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Or to preserve users ability to override the variable:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
|
||||
<span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s1">'ENV_VAR'</span><span class="p">]</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'ENV_VAR'</span><span class="p">,</span> <span class="s1">'value'</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If the variable is more useful for users of an app to set than the developer then they can set it like this:</p>
|
||||
<p><strong>Windows</strong>:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">set</span> <span class="n">NAME_OF_ENVIRONMENT_VARIABLE</span><span class="o">=</span><span class="n">value_to_set</span>
|
||||
<span class="n">python</span> <span class="n">my_application</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p><strong>Linux/Mac</strong>:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ENV_VAR</span><span class="o">=</span><span class="n">value</span> <span class="n">python</span> <span class="n">my_application</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For some variables they need to be set before initialising pygame, some must be set before even importing pygame,
|
||||
and others can simply be set right before the area of code they control is run.</p>
|
||||
<p>Below is a list of environment variables, their settable values, and a brief description of what they do.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<p><strong>Pygame Environment Variables</strong></p>
|
||||
<p>These variables are defined by pygame itself.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PYGAME_DISPLAY</span> <span class="o">-</span> <span class="n">Experimental</span> <span class="p">(</span><span class="n">subject</span> <span class="n">to</span> <span class="n">change</span><span class="p">)</span>
|
||||
<span class="n">Set</span> <span class="n">index</span> <span class="n">of</span> <span class="n">the</span> <span class="n">display</span> <span class="n">to</span> <span class="n">use</span><span class="p">,</span> <span class="s2">"0"</span> <span class="ow">is</span> <span class="n">the</span> <span class="n">default</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This sets the display where pygame will open its window
|
||||
or screen. The value set here will be used if set before
|
||||
calling <a class="tooltip reference internal" href="display.html#pygame.display.set_mode" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.display.set_mode()</span></code><span class="tooltip-content">Initialize a window or screen for display</span></a>, and as long as no
|
||||
'display' parameter is passed into <a class="tooltip reference internal" href="display.html#pygame.display.set_mode" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.display.set_mode()</span></code><span class="tooltip-content">Initialize a window or screen for display</span></a>.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PYGAME_FORCE_SCALE</span> <span class="o">-</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"photo"</span> <span class="ow">or</span> <span class="s2">"default"</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This forces set_mode() to use the SCALED display mode and,
|
||||
if "photo" is set, makes the scaling use the slowest, but
|
||||
highest quality anisotropic scaling algorithm, if it is
|
||||
available. Must be set before calling <a class="tooltip reference internal" href="display.html#pygame.display.set_mode" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.display.set_mode()</span></code><span class="tooltip-content">Initialize a window or screen for display</span></a>.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PYGAME_BLEND_ALPHA_SDL2</span> <span class="o">-</span> <span class="n">New</span> <span class="ow">in</span> <span class="n">pygame</span> <span class="mf">2.0.0</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"1"</span> <span class="n">to</span> <span class="n">enable</span> <span class="n">the</span> <span class="n">SDL2</span> <span class="n">blitter</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This makes pygame use the SDL2 blitter for all alpha
|
||||
blending. The SDL2 blitter is sometimes faster than
|
||||
the default blitter but uses a different formula so
|
||||
the final colours may differ. Must be set before
|
||||
<a class="tooltip reference internal" href="#pygame.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.init()</span></code><span class="tooltip-content">initialize all imported pygame modules</span></a> is called.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PYGAME_HIDE_SUPPORT_PROMPT</span> <span class="o">-</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"1"</span> <span class="n">to</span> <span class="n">hide</span> <span class="n">the</span> <span class="n">prompt</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This stops the welcome message popping up in the
|
||||
console that tells you which version of python,
|
||||
pygame & SDL you are using. Must be set before
|
||||
importing pygame.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PYGAME_FREETYPE</span> <span class="o">-</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"1"</span> <span class="n">to</span> <span class="n">enable</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This switches the pygame.font module to a pure
|
||||
freetype implementation that bypasses SDL_ttf.
|
||||
See the font module for why you might want to
|
||||
do this. Must be set before importing pygame.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PYGAME_CAMERA</span> <span class="o">-</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"opencv"</span> <span class="ow">or</span> <span class="s2">"vidcapture"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Forces the library backend used in the camera
|
||||
module, overriding the platform defaults. Must
|
||||
be set before calling <a class="tooltip reference internal" href="camera.html#pygame.camera.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.camera.init()</span></code><span class="tooltip-content">Module init</span></a>.</p>
|
||||
<p>In pygame 2.0.3, backends can be set programmatically instead, and the old
|
||||
OpenCV backend has been replaced with one on top of "opencv-python," rather
|
||||
than the old "highgui" OpenCV port. Also, there is a new native Windows
|
||||
backend available.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<p><strong>SDL Environment Variables</strong></p>
|
||||
<p>These variables are defined by SDL.</p>
|
||||
<p>For documentation on the environment variables available in
|
||||
pygame 1 try <a class="reference external" href="https://www.libsdl.org/release/SDL-1.2.15/docs/html/sdlenvvars.html">here</a>.
|
||||
For Pygame 2, some selected environment variables are listed below.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SDL_VIDEO_CENTERED</span> <span class="o">-</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"1"</span> <span class="n">to</span> <span class="n">enable</span> <span class="n">centering</span> <span class="n">the</span> <span class="n">window</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This will make the pygame window open in the centre of the display.
|
||||
Must be set before calling <a class="tooltip reference internal" href="display.html#pygame.display.set_mode" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.display.set_mode()</span></code><span class="tooltip-content">Initialize a window or screen for display</span></a>.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SDL_VIDEO_WINDOW_POS</span> <span class="o">-</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"x,y"</span> <span class="n">to</span> <span class="n">position</span> <span class="n">the</span> <span class="n">top</span> <span class="n">left</span> <span class="n">corner</span> <span class="n">of</span> <span class="n">the</span> <span class="n">window</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This allows control over the placement of the pygame window within
|
||||
the display. Must be set before calling <a class="tooltip reference internal" href="display.html#pygame.display.set_mode" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.display.set_mode()</span></code><span class="tooltip-content">Initialize a window or screen for display</span></a>.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SDL_VIDEODRIVER</span> <span class="o">-</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"drivername"</span> <span class="n">to</span> <span class="n">change</span> <span class="n">the</span> <span class="n">video</span> <span class="n">driver</span> <span class="n">used</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>On some platforms there are multiple video drivers available and
|
||||
this allows users to pick between them. More information is available
|
||||
<a class="reference external" href="https://wiki.libsdl.org/FAQUsingSDL">here</a>. Must be set before
|
||||
calling <a class="tooltip reference internal" href="#pygame.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.init()</span></code><span class="tooltip-content">initialize all imported pygame modules</span></a> or <a class="tooltip reference internal" href="display.html#pygame.display.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.display.init()</span></code><span class="tooltip-content">Initialize the display module</span></a>.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SDL_AUDIODRIVER</span> <span class="o">-</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"drivername"</span> <span class="n">to</span> <span class="n">change</span> <span class="n">the</span> <span class="n">audio</span> <span class="n">driver</span> <span class="n">used</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>On some platforms there are multiple audio drivers available and
|
||||
this allows users to pick between them. More information is available
|
||||
<a class="reference external" href="https://wiki.libsdl.org/FAQUsingSDL">here</a>. Must be set before
|
||||
calling <a class="tooltip reference internal" href="#pygame.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.init()</span></code><span class="tooltip-content">initialize all imported pygame modules</span></a> or <a class="tooltip reference internal" href="mixer.html#pygame.mixer.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.mixer.init()</span></code><span class="tooltip-content">initialize the mixer module</span></a>.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SDL_VIDEO_ALLOW_SCREENSAVER</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"1"</span> <span class="n">to</span> <span class="n">allow</span> <span class="n">screensavers</span> <span class="k">while</span> <span class="n">pygame</span> <span class="n">apps</span> <span class="n">are</span> <span class="n">running</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>By default pygame apps disable screensavers while
|
||||
they are running. Setting this environment variable allows users or
|
||||
developers to change that and make screensavers run again.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"0"</span> <span class="n">to</span> <span class="n">re</span><span class="o">-</span><span class="n">enable</span> <span class="n">the</span> <span class="n">compositor</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>By default SDL tries to disable the X11 compositor for all pygame
|
||||
apps. This is usually a good thing as it's faster, however if you
|
||||
have an app which <em>doesn't</em> update every frame and are using linux
|
||||
you may want to disable this bypass. The bypass has reported problems
|
||||
on KDE linux. This variable is only used on x11/linux platforms.</p>
|
||||
<div class="line-block">
|
||||
<div class="line"><br /></div>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS</span>
|
||||
<span class="n">Set</span> <span class="n">to</span> <span class="s2">"1"</span> <span class="n">to</span> <span class="n">allow</span> <span class="n">joysticks</span> <span class="n">to</span> <span class="n">be</span> <span class="n">updated</span> <span class="n">even</span> <span class="n">when</span> <span class="n">the</span> <span class="n">window</span> <span class="ow">is</span> <span class="n">out</span> <span class="n">of</span> <span class="n">focus</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>By default, when the window is not in focus, input devices do not get
|
||||
updated. However, using this environment variable it is possible to get
|
||||
joystick updates even when the window is in the background. Must be set
|
||||
before calling <a class="tooltip reference internal" href="#pygame.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.init()</span></code><span class="tooltip-content">initialize all imported pygame modules</span></a> or <a class="tooltip reference internal" href="joystick.html#pygame.joystick.init" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.joystick.init()</span></code><span class="tooltip-content">Initialize the joystick module.</span></a>.</p>
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/pygame.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="rect.html" title="pygame.Rect"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="pixelcopy.html" title="pygame.pixelcopy"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,901 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.Rect — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.scrap" href="scrap.html" />
|
||||
<link rel="prev" title="pygame" href="pygame.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="pygame-rect">
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.</span></span><span class="sig-name descname"><span class="pre">Rect</span></span><a class="headerlink" href="#pygame.Rect" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame object for storing rectangular coordinates</span></div>
|
||||
<div class="line"><span class="signature">Rect(left, top, width, height) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">Rect((left, top), (width, height)) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">Rect(object) -> Rect</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.copy">pygame.Rect.copy</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>copy the rectangle</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.move">pygame.Rect.move</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>moves the rectangle</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.move_ip">pygame.Rect.move_ip</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>moves the rectangle, in place</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.inflate">pygame.Rect.inflate</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>grow or shrink the rectangle size</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.inflate_ip">pygame.Rect.inflate_ip</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>grow or shrink the rectangle size, in place</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.scale_by">pygame.Rect.scale_by</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>scale the rectangle by given a multiplier</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.scale_by_ip">pygame.Rect.scale_by_ip</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>grow or shrink the rectangle size, in place</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.update">pygame.Rect.update</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>sets the position and size of the rectangle</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.clamp">pygame.Rect.clamp</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>moves the rectangle inside another</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.clamp_ip">pygame.Rect.clamp_ip</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>moves the rectangle inside another, in place</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.clip">pygame.Rect.clip</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>crops a rectangle inside another</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.clipline">pygame.Rect.clipline</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>crops a line inside a rectangle</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.union">pygame.Rect.union</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>joins two rectangles into one</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.union_ip">pygame.Rect.union_ip</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>joins two rectangles into one, in place</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.unionall">pygame.Rect.unionall</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>the union of many rectangles</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.unionall_ip">pygame.Rect.unionall_ip</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>the union of many rectangles, in place</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.fit">pygame.Rect.fit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>resize and move a rectangle with aspect ratio</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.normalize">pygame.Rect.normalize</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>correct negative sizes</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.contains">pygame.Rect.contains</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if one rectangle is inside another</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.collidepoint">pygame.Rect.collidepoint</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if a point is inside a rectangle</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.colliderect">pygame.Rect.colliderect</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if two rectangles overlap</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.collidelist">pygame.Rect.collidelist</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if one rectangle in a list intersects</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.collidelistall">pygame.Rect.collidelistall</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if all rectangles in a list intersect</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.collideobjects">pygame.Rect.collideobjects</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if any object in a list intersects</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.collideobjectsall">pygame.Rect.collideobjectsall</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if all objects in a list intersect</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.collidedict">pygame.Rect.collidedict</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if one rectangle in a dictionary intersects</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="rect.html#pygame.Rect.collidedictall">pygame.Rect.collidedictall</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>test if all rectangles in a dictionary intersect</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Pygame uses Rect objects to store and manipulate rectangular areas. A Rect
|
||||
can be created from a combination of left, top, width, and height values.
|
||||
Rects can also be created from python objects that are already a Rect or
|
||||
have an attribute named "rect".</p>
|
||||
<p>Any pygame function that requires a Rect argument also accepts any of these
|
||||
values to construct a Rect. This makes it easier to create Rects on the fly
|
||||
as arguments to functions.</p>
|
||||
<p>The Rect functions that change the position or size of a Rect return a new
|
||||
copy of the Rect with the affected changes. The original Rect is not
|
||||
modified. Some methods have an alternate "in-place" version that returns
|
||||
None but affects the original Rect. These "in-place" methods are denoted
|
||||
with the "ip" suffix.</p>
|
||||
<p>The Rect object has several virtual attributes which can be used to move and
|
||||
align the Rect:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">x</span><span class="p">,</span><span class="n">y</span>
|
||||
<span class="n">top</span><span class="p">,</span> <span class="n">left</span><span class="p">,</span> <span class="n">bottom</span><span class="p">,</span> <span class="n">right</span>
|
||||
<span class="n">topleft</span><span class="p">,</span> <span class="n">bottomleft</span><span class="p">,</span> <span class="n">topright</span><span class="p">,</span> <span class="n">bottomright</span>
|
||||
<span class="n">midtop</span><span class="p">,</span> <span class="n">midleft</span><span class="p">,</span> <span class="n">midbottom</span><span class="p">,</span> <span class="n">midright</span>
|
||||
<span class="n">center</span><span class="p">,</span> <span class="n">centerx</span><span class="p">,</span> <span class="n">centery</span>
|
||||
<span class="n">size</span><span class="p">,</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span>
|
||||
<span class="n">w</span><span class="p">,</span><span class="n">h</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>All of these attributes can be assigned to:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rect1</span><span class="o">.</span><span class="n">right</span> <span class="o">=</span> <span class="mi">10</span>
|
||||
<span class="n">rect2</span><span class="o">.</span><span class="n">center</span> <span class="o">=</span> <span class="p">(</span><span class="mi">20</span><span class="p">,</span><span class="mi">30</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Assigning to size, width or height changes the dimensions of the rectangle;
|
||||
all other assignments move the rectangle without resizing it. Notice that
|
||||
some attributes are integers and others are pairs of integers.</p>
|
||||
<p>If a Rect has a nonzero width or height, it will return <code class="docutils literal notranslate"><span class="pre">True</span></code> for a
|
||||
nonzero test. Some methods return a Rect with 0 size to represent an invalid
|
||||
rectangle. A Rect with a 0 size will not collide when using collision
|
||||
detection methods (e.g. <a class="reference internal" href="#pygame.Rect.collidepoint" title="pygame.Rect.collidepoint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">collidepoint()</span></code></a>, <a class="reference internal" href="#pygame.Rect.colliderect" title="pygame.Rect.colliderect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">colliderect()</span></code></a>, etc.).</p>
|
||||
<p>The coordinates for Rect objects are all integers. The size values can be
|
||||
programmed to have negative values, but these are considered illegal Rects
|
||||
for most operations.</p>
|
||||
<p>There are several collision tests between other rectangles. Most python
|
||||
containers can be searched for collisions against a single Rect.</p>
|
||||
<p>The area covered by a Rect does not include the right- and bottom-most edge
|
||||
of pixels. If one Rect's bottom border is another Rect's top border (i.e.,
|
||||
rect1.bottom=rect2.top), the two meet exactly on the screen but do not
|
||||
overlap, and <code class="docutils literal notranslate"><span class="pre">rect1.colliderect(rect2)</span></code> returns false.</p>
|
||||
<p>The Rect object is also iterable:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">r</span> <span class="o">=</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
|
||||
<span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">w</span><span class="p">,</span> <span class="n">h</span> <span class="o">=</span> <span class="n">r</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.2: </span>The Rect class can be subclassed. Methods such as <code class="docutils literal notranslate"><span class="pre">copy()</span></code> and <code class="docutils literal notranslate"><span class="pre">move()</span></code>
|
||||
will recognize this and return instances of the subclass.
|
||||
However, the subclass's <code class="docutils literal notranslate"><span class="pre">__init__()</span></code> method is not called,
|
||||
and <code class="docutils literal notranslate"><span class="pre">__new__()</span></code> is assumed to take no arguments. So these methods should be
|
||||
overridden if any extra attributes need to be copied.</p>
|
||||
</div>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.copy">
|
||||
<span class="sig-name descname"><span class="pre">copy</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.copy" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">copy the rectangle</span></div>
|
||||
<div class="line"><span class="signature">copy() -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns a new rectangle having the same position and size as the original.</p>
|
||||
<p>New in pygame 1.9</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.move">
|
||||
<span class="sig-name descname"><span class="pre">move</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.move" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">moves the rectangle</span></div>
|
||||
<div class="line"><span class="signature">move(x, y) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns a new rectangle that is moved by the given offset. The x and y
|
||||
arguments can be any integer value, positive or negative.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.move_ip">
|
||||
<span class="sig-name descname"><span class="pre">move_ip</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.move_ip" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">moves the rectangle, in place</span></div>
|
||||
<div class="line"><span class="signature">move_ip(x, y) -> None</span></div>
|
||||
</div>
|
||||
<p>Same as the <code class="docutils literal notranslate"><span class="pre">Rect.move()</span></code> method, but operates in place.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.inflate">
|
||||
<span class="sig-name descname"><span class="pre">inflate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.inflate" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">grow or shrink the rectangle size</span></div>
|
||||
<div class="line"><span class="signature">inflate(x, y) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns a new rectangle with the size changed by the given offset. The
|
||||
rectangle remains centered around its current center. Negative values
|
||||
will shrink the rectangle. Note, uses integers, if the offset given is
|
||||
too small(< 2 > -2), center will be off.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.inflate_ip">
|
||||
<span class="sig-name descname"><span class="pre">inflate_ip</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.inflate_ip" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">grow or shrink the rectangle size, in place</span></div>
|
||||
<div class="line"><span class="signature">inflate_ip(x, y) -> None</span></div>
|
||||
</div>
|
||||
<p>Same as the <code class="docutils literal notranslate"><span class="pre">Rect.inflate()</span></code> method, but operates in place.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.scale_by">
|
||||
<span class="sig-name descname"><span class="pre">scale_by</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.scale_by" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">scale the rectangle by given a multiplier</span></div>
|
||||
<div class="line"><span class="signature">scale_by(scalar) -> Rect</span></div>
|
||||
<div class="line"><span class="signature">scale_by(scalex, scaley) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns a new rectangle with the size scaled by the given multipliers.
|
||||
The rectangle remains centered around its current center. A single
|
||||
scalar or separate width and height scalars are allowed. Values above
|
||||
one will increase the size of the rectangle, whereas values between
|
||||
zero and one will decrease the size of the rectangle.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.scale_by_ip">
|
||||
<span class="sig-name descname"><span class="pre">scale_by_ip</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.scale_by_ip" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">grow or shrink the rectangle size, in place</span></div>
|
||||
<div class="line"><span class="signature">scale_by_ip(scalar) -> None</span></div>
|
||||
<div class="line"><span class="signature">scale_by_ip(scalex, scaley) -> None</span></div>
|
||||
</div>
|
||||
<p>Same as the <code class="docutils literal notranslate"><span class="pre">Rect.scale_by()</span></code> method, but operates in place.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.update">
|
||||
<span class="sig-name descname"><span class="pre">update</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.update" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">sets the position and size of the rectangle</span></div>
|
||||
<div class="line"><span class="signature">update(left, top, width, height) -> None</span></div>
|
||||
<div class="line"><span class="signature">update((left, top), (width, height)) -> None</span></div>
|
||||
<div class="line"><span class="signature">update(object) -> None</span></div>
|
||||
</div>
|
||||
<p>Sets the position and size of the rectangle, in place. See
|
||||
parameters for <a class="tooltip reference internal" href="#pygame.Rect" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Rect()</span></code><span class="tooltip-content">pygame object for storing rectangular coordinates</span></a> for the parameters of this function.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.clamp">
|
||||
<span class="sig-name descname"><span class="pre">clamp</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.clamp" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">moves the rectangle inside another</span></div>
|
||||
<div class="line"><span class="signature">clamp(Rect) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns a new rectangle that is moved to be completely inside the
|
||||
argument Rect. If the rectangle is too large to fit inside, it is
|
||||
centered inside the argument Rect, but its size is not changed.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.clamp_ip">
|
||||
<span class="sig-name descname"><span class="pre">clamp_ip</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.clamp_ip" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">moves the rectangle inside another, in place</span></div>
|
||||
<div class="line"><span class="signature">clamp_ip(Rect) -> None</span></div>
|
||||
</div>
|
||||
<p>Same as the <code class="docutils literal notranslate"><span class="pre">Rect.clamp()</span></code> method, but operates in place.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.clip">
|
||||
<span class="sig-name descname"><span class="pre">clip</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.clip" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">crops a rectangle inside another</span></div>
|
||||
<div class="line"><span class="signature">clip(Rect) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns a new rectangle that is cropped to be completely inside the
|
||||
argument Rect. If the two rectangles do not overlap to begin with, a Rect
|
||||
with 0 size is returned.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.clipline">
|
||||
<span class="sig-name descname"><span class="pre">clipline</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.clipline" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">crops a line inside a rectangle</span></div>
|
||||
<div class="line"><span class="signature">clipline(x1, y1, x2, y2) -> ((cx1, cy1), (cx2, cy2))</span></div>
|
||||
<div class="line"><span class="signature">clipline(x1, y1, x2, y2) -> ()</span></div>
|
||||
<div class="line"><span class="signature">clipline((x1, y1), (x2, y2)) -> ((cx1, cy1), (cx2, cy2))</span></div>
|
||||
<div class="line"><span class="signature">clipline((x1, y1), (x2, y2)) -> ()</span></div>
|
||||
<div class="line"><span class="signature">clipline((x1, y1, x2, y2)) -> ((cx1, cy1), (cx2, cy2))</span></div>
|
||||
<div class="line"><span class="signature">clipline((x1, y1, x2, y2)) -> ()</span></div>
|
||||
<div class="line"><span class="signature">clipline(((x1, y1), (x2, y2))) -> ((cx1, cy1), (cx2, cy2))</span></div>
|
||||
<div class="line"><span class="signature">clipline(((x1, y1), (x2, y2))) -> ()</span></div>
|
||||
</div>
|
||||
<p>Returns the coordinates of a line that is cropped to be completely inside
|
||||
the rectangle. If the line does not overlap the rectangle, then an empty
|
||||
tuple is returned.</p>
|
||||
<p>The line to crop can be any of the following formats (floats can be used
|
||||
in place of ints, but they will be truncated):</p>
|
||||
<blockquote>
|
||||
<div><ul class="simple">
|
||||
<li><p>four ints</p></li>
|
||||
<li><p>2 lists/tuples/Vector2s of 2 ints</p></li>
|
||||
<li><p>a list/tuple of four ints</p></li>
|
||||
<li><p>a list/tuple of 2 lists/tuples/Vector2s of 2 ints</p></li>
|
||||
</ul>
|
||||
</div></blockquote>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>a tuple with the coordinates of the given line cropped to be
|
||||
completely inside the rectangle is returned, if the given line does
|
||||
not overlap the rectangle, an empty tuple is returned</p>
|
||||
</dd>
|
||||
<dt class="field-even">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>tuple(tuple(int, int), tuple(int, int)) or ()</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>TypeError</strong> -- if the line coordinates are not given as one of the
|
||||
above described line formats</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This method can be used for collision detection between a rect and a
|
||||
line. See example code below.</p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">rect.bottom</span></code> and <code class="docutils literal notranslate"><span class="pre">rect.right</span></code> attributes of a
|
||||
<a class="tooltip reference internal" href="#pygame.Rect" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.Rect</span></code><span class="tooltip-content">pygame object for storing rectangular coordinates</span></a> always lie one pixel outside of its actual border.</p>
|
||||
</div>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Example using clipline().</span>
|
||||
<span class="n">clipped_line</span> <span class="o">=</span> <span class="n">rect</span><span class="o">.</span><span class="n">clipline</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>
|
||||
|
||||
<span class="k">if</span> <span class="n">clipped_line</span><span class="p">:</span>
|
||||
<span class="c1"># If clipped_line is not an empty tuple then the line</span>
|
||||
<span class="c1"># collides/overlaps with the rect. The returned value contains</span>
|
||||
<span class="c1"># the endpoints of the clipped line.</span>
|
||||
<span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">clipped_line</span>
|
||||
<span class="n">x1</span><span class="p">,</span> <span class="n">y1</span> <span class="o">=</span> <span class="n">start</span>
|
||||
<span class="n">x2</span><span class="p">,</span> <span class="n">y2</span> <span class="o">=</span> <span class="n">end</span>
|
||||
<span class="k">else</span><span class="p">:</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s2">"No clipping. The line is fully outside the rect."</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.union">
|
||||
<span class="sig-name descname"><span class="pre">union</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.union" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">joins two rectangles into one</span></div>
|
||||
<div class="line"><span class="signature">union(Rect) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns a new rectangle that completely covers the area of the two
|
||||
provided rectangles. There may be area inside the new Rect that is not
|
||||
covered by the originals.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.union_ip">
|
||||
<span class="sig-name descname"><span class="pre">union_ip</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.union_ip" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">joins two rectangles into one, in place</span></div>
|
||||
<div class="line"><span class="signature">union_ip(Rect) -> None</span></div>
|
||||
</div>
|
||||
<p>Same as the <code class="docutils literal notranslate"><span class="pre">Rect.union()</span></code> method, but operates in place.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.unionall">
|
||||
<span class="sig-name descname"><span class="pre">unionall</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.unionall" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">the union of many rectangles</span></div>
|
||||
<div class="line"><span class="signature">unionall(Rect_sequence) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns the union of one rectangle with a sequence of many rectangles.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.unionall_ip">
|
||||
<span class="sig-name descname"><span class="pre">unionall_ip</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.unionall_ip" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">the union of many rectangles, in place</span></div>
|
||||
<div class="line"><span class="signature">unionall_ip(Rect_sequence) -> None</span></div>
|
||||
</div>
|
||||
<p>The same as the <code class="docutils literal notranslate"><span class="pre">Rect.unionall()</span></code> method, but operates in place.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.fit">
|
||||
<span class="sig-name descname"><span class="pre">fit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.fit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">resize and move a rectangle with aspect ratio</span></div>
|
||||
<div class="line"><span class="signature">fit(Rect) -> Rect</span></div>
|
||||
</div>
|
||||
<p>Returns a new rectangle that is moved and resized to fit another. The
|
||||
aspect ratio of the original Rect is preserved, so the new rectangle may
|
||||
be smaller than the target in either width or height.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.normalize">
|
||||
<span class="sig-name descname"><span class="pre">normalize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.normalize" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">correct negative sizes</span></div>
|
||||
<div class="line"><span class="signature">normalize() -> None</span></div>
|
||||
</div>
|
||||
<p>This will flip the width or height of a rectangle if it has a negative
|
||||
size. The rectangle will remain in the same place, with only the sides
|
||||
swapped.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.contains">
|
||||
<span class="sig-name descname"><span class="pre">contains</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.contains" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if one rectangle is inside another</span></div>
|
||||
<div class="line"><span class="signature">contains(Rect) -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns true when the argument is completely inside the Rect.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.collidepoint">
|
||||
<span class="sig-name descname"><span class="pre">collidepoint</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.collidepoint" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if a point is inside a rectangle</span></div>
|
||||
<div class="line"><span class="signature">collidepoint(x, y) -> bool</span></div>
|
||||
<div class="line"><span class="signature">collidepoint((x,y)) -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns true if the given point is inside the rectangle. A point along
|
||||
the right or bottom edge is not considered to be inside the rectangle.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>For collision detection between a rect and a line the <a class="reference internal" href="#pygame.Rect.clipline" title="pygame.Rect.clipline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">clipline()</span></code></a>
|
||||
method can be used.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.colliderect">
|
||||
<span class="sig-name descname"><span class="pre">colliderect</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.colliderect" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if two rectangles overlap</span></div>
|
||||
<div class="line"><span class="signature">colliderect(Rect) -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns true if any portion of either rectangle overlap (except the
|
||||
top+bottom or left+right edges).</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>For collision detection between a rect and a line the <a class="reference internal" href="#pygame.Rect.clipline" title="pygame.Rect.clipline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">clipline()</span></code></a>
|
||||
method can be used.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.collidelist">
|
||||
<span class="sig-name descname"><span class="pre">collidelist</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.collidelist" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if one rectangle in a list intersects</span></div>
|
||||
<div class="line"><span class="signature">collidelist(list) -> index</span></div>
|
||||
</div>
|
||||
<p>Test whether the rectangle collides with any in a sequence of rectangles.
|
||||
The index of the first collision found is returned. If no collisions are
|
||||
found an index of -1 is returned.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.collidelistall">
|
||||
<span class="sig-name descname"><span class="pre">collidelistall</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.collidelistall" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if all rectangles in a list intersect</span></div>
|
||||
<div class="line"><span class="signature">collidelistall(list) -> indices</span></div>
|
||||
</div>
|
||||
<p>Returns a list of all the indices that contain rectangles that collide
|
||||
with the Rect. If no intersecting rectangles are found, an empty list is
|
||||
returned.</p>
|
||||
<p>Not only Rects are valid arguments, but these are all valid calls:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">Rect</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">Rect</span>
|
||||
<span class="n">r</span> <span class="o">=</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
|
||||
|
||||
<span class="n">list_of_rects</span> <span class="o">=</span> <span class="p">[</span><span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">)]</span>
|
||||
<span class="n">indices0</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collidelistall</span><span class="p">(</span><span class="n">list_of_rects</span><span class="p">)</span>
|
||||
|
||||
<span class="n">list_of_lists</span> <span class="o">=</span> <span class="p">[[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">]]</span>
|
||||
<span class="n">indices1</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collidelistall</span><span class="p">(</span><span class="n">list_of_lists</span><span class="p">)</span>
|
||||
|
||||
<span class="n">list_of_tuples</span> <span class="o">=</span> <span class="p">[(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">)]</span>
|
||||
<span class="n">indices2</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collidelistall</span><span class="p">(</span><span class="n">list_of_tuples</span><span class="p">)</span>
|
||||
|
||||
<span class="n">list_of_double_tuples</span> <span class="o">=</span> <span class="p">[((</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)),</span> <span class="p">((</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">))]</span>
|
||||
<span class="n">indices3</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collidelistall</span><span class="p">(</span><span class="n">list_of_double_tuples</span><span class="p">)</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">ObjectWithRectAttribute</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
|
||||
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">rect</span> <span class="o">=</span> <span class="n">r</span>
|
||||
|
||||
<span class="n">list_of_object_with_rect_attribute</span> <span class="o">=</span> <span class="p">[</span>
|
||||
<span class="n">ObjectWithRectAttribute</span><span class="p">(</span><span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)),</span>
|
||||
<span class="n">ObjectWithRectAttribute</span><span class="p">(</span><span class="n">Rect</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">)),</span>
|
||||
<span class="p">]</span>
|
||||
<span class="n">indices4</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collidelistall</span><span class="p">(</span><span class="n">list_of_object_with_rect_attribute</span><span class="p">)</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">ObjectWithCallableRectAttribute</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
|
||||
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">_rect</span> <span class="o">=</span> <span class="n">r</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">rect</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||||
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_rect</span>
|
||||
|
||||
<span class="n">list_of_object_with_callable_rect</span> <span class="o">=</span> <span class="p">[</span>
|
||||
<span class="n">ObjectWithCallableRectAttribute</span><span class="p">(</span><span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)),</span>
|
||||
<span class="n">ObjectWithCallableRectAttribute</span><span class="p">(</span><span class="n">Rect</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">)),</span>
|
||||
<span class="p">]</span>
|
||||
<span class="n">indices5</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collidelistall</span><span class="p">(</span><span class="n">list_of_object_with_callable_rect</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.collideobjects">
|
||||
<span class="sig-name descname"><span class="pre">collideobjects</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.collideobjects" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if any object in a list intersects</span></div>
|
||||
<div class="line"><span class="signature">collideobjects(rect_list) -> object</span></div>
|
||||
<div class="line"><span class="signature">collideobjects(obj_list, key=func) -> object</span></div>
|
||||
</div>
|
||||
<p><strong>Experimental:</strong> feature still in development available for testing and feedback. It may change.
|
||||
<a class="reference external" href="https://github.com/pygame/pygame/pull/3026">Please leave collideobjects feedback with authors</a></p>
|
||||
<p>Test whether the rectangle collides with any object in the sequence.
|
||||
The object of the first collision found is returned. If no collisions are
|
||||
found then <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned</p>
|
||||
<p>If key is given, then it should be a method taking an object from the list
|
||||
as input and returning a rect like object e.g. <code class="docutils literal notranslate"><span class="pre">lambda</span> <span class="pre">obj:</span> <span class="pre">obj.rectangle</span></code>.
|
||||
If an object has multiple attributes of type Rect then key could return one
|
||||
of them.</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">r</span> <span class="o">=</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
|
||||
|
||||
<span class="n">rects</span> <span class="o">=</span> <span class="p">[</span>
|
||||
<span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span>
|
||||
<span class="n">Rect</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span>
|
||||
<span class="n">Rect</span><span class="p">(</span><span class="mi">15</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
|
||||
<span class="n">Rect</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
|
||||
<span class="p">]</span>
|
||||
|
||||
<span class="n">result</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collideobjects</span><span class="p">(</span><span class="n">rects</span><span class="p">)</span> <span class="c1"># -> <rect(1, 1, 10, 10)></span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">ObjectWithSomRectAttribute</span><span class="p">:</span>
|
||||
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">collision_box</span><span class="p">,</span> <span class="n">draw_rect</span><span class="p">):</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">draw_rect</span> <span class="o">=</span> <span class="n">draw_rect</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">collision_box</span> <span class="o">=</span> <span class="n">collision_box</span>
|
||||
|
||||
<span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||||
<span class="k">return</span> <span class="sa">f</span><span class="s1">'<</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s1">("</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s1">", </span><span class="si">{</span><span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">collision_box</span><span class="p">)</span><span class="si">}</span><span class="s1">, </span><span class="si">{</span><span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">draw_rect</span><span class="p">)</span><span class="si">}</span><span class="s1">)>'</span>
|
||||
|
||||
<span class="n">objects</span> <span class="o">=</span> <span class="p">[</span>
|
||||
<span class="n">ObjectWithSomRectAttribute</span><span class="p">(</span><span class="s2">"A"</span><span class="p">,</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">15</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">150</span><span class="p">,</span> <span class="mi">150</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">)),</span>
|
||||
<span class="n">ObjectWithSomRectAttribute</span><span class="p">(</span><span class="s2">"B"</span><span class="p">,</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">300</span><span class="p">,</span> <span class="mi">300</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">)),</span>
|
||||
<span class="n">ObjectWithSomRectAttribute</span><span class="p">(</span><span class="s2">"C"</span><span class="p">,</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="mi">500</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">)),</span>
|
||||
<span class="p">]</span>
|
||||
|
||||
<span class="c1"># collision = r.collideobjects(objects) # this does not work because the items in the list are no Rect like object</span>
|
||||
<span class="n">collision</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collideobjects</span><span class="p">(</span>
|
||||
<span class="n">objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">o</span><span class="p">:</span> <span class="n">o</span><span class="o">.</span><span class="n">collision_box</span>
|
||||
<span class="p">)</span> <span class="c1"># -> <ObjectWithSomRectAttribute("B", [1, 1, 10, 10], [300, 300, 50, 50])></span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">collision</span><span class="p">)</span>
|
||||
|
||||
<span class="n">screen_rect</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collideobjects</span><span class="p">(</span><span class="n">objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">o</span><span class="p">:</span> <span class="n">o</span><span class="o">.</span><span class="n">draw_rect</span><span class="p">)</span> <span class="c1"># -> None</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">screen_rect</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.collideobjectsall">
|
||||
<span class="sig-name descname"><span class="pre">collideobjectsall</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.collideobjectsall" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if all objects in a list intersect</span></div>
|
||||
<div class="line"><span class="signature">collideobjectsall(rect_list) -> objects</span></div>
|
||||
<div class="line"><span class="signature">collideobjectsall(obj_list, key=func) -> objects</span></div>
|
||||
</div>
|
||||
<p><strong>Experimental:</strong> feature still in development available for testing and feedback. It may change.
|
||||
<a class="reference external" href="https://github.com/pygame/pygame/pull/3026">Please leave collideobjectsall feedback with authors</a></p>
|
||||
<p>Returns a list of all the objects that contain rectangles that collide
|
||||
with the Rect. If no intersecting objects are found, an empty list is
|
||||
returned.</p>
|
||||
<p>If key is given, then it should be a method taking an object from the list
|
||||
as input and returning a rect like object e.g. <code class="docutils literal notranslate"><span class="pre">lambda</span> <span class="pre">obj:</span> <span class="pre">obj.rectangle</span></code>.
|
||||
If an object has multiple attributes of type Rect then key could return one
|
||||
of them.</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">r</span> <span class="o">=</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
|
||||
|
||||
<span class="n">rects</span> <span class="o">=</span> <span class="p">[</span>
|
||||
<span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span>
|
||||
<span class="n">Rect</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span>
|
||||
<span class="n">Rect</span><span class="p">(</span><span class="mi">15</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
|
||||
<span class="n">Rect</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
|
||||
<span class="p">]</span>
|
||||
|
||||
<span class="n">result</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collideobjectsall</span><span class="p">(</span>
|
||||
<span class="n">rects</span>
|
||||
<span class="p">)</span> <span class="c1"># -> [<rect(1, 1, 10, 10)>, <rect(5, 5, 10, 10)>, <rect(2, 2, 1, 1)>]</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">ObjectWithSomRectAttribute</span><span class="p">:</span>
|
||||
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">collision_box</span><span class="p">,</span> <span class="n">draw_rect</span><span class="p">):</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">draw_rect</span> <span class="o">=</span> <span class="n">draw_rect</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">collision_box</span> <span class="o">=</span> <span class="n">collision_box</span>
|
||||
|
||||
<span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||||
<span class="k">return</span> <span class="sa">f</span><span class="s1">'<</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="si">}</span><span class="s1">("</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="si">}</span><span class="s1">", </span><span class="si">{</span><span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">collision_box</span><span class="p">)</span><span class="si">}</span><span class="s1">, </span><span class="si">{</span><span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">draw_rect</span><span class="p">)</span><span class="si">}</span><span class="s1">)>'</span>
|
||||
|
||||
<span class="n">objects</span> <span class="o">=</span> <span class="p">[</span>
|
||||
<span class="n">ObjectWithSomRectAttribute</span><span class="p">(</span><span class="s2">"A"</span><span class="p">,</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">300</span><span class="p">,</span> <span class="mi">300</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">)),</span>
|
||||
<span class="n">ObjectWithSomRectAttribute</span><span class="p">(</span><span class="s2">"B"</span><span class="p">,</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">),</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="mi">500</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">)),</span>
|
||||
<span class="n">ObjectWithSomRectAttribute</span><span class="p">(</span><span class="s2">"C"</span><span class="p">,</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">15</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="n">Rect</span><span class="p">(</span><span class="mi">150</span><span class="p">,</span> <span class="mi">150</span><span class="p">,</span> <span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">)),</span>
|
||||
<span class="p">]</span>
|
||||
|
||||
<span class="c1"># collisions = r.collideobjectsall(objects) # this does not work because ObjectWithSomRectAttribute is not a Rect like object</span>
|
||||
<span class="n">collisions</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collideobjectsall</span><span class="p">(</span>
|
||||
<span class="n">objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">o</span><span class="p">:</span> <span class="n">o</span><span class="o">.</span><span class="n">collision_box</span>
|
||||
<span class="p">)</span> <span class="c1"># -> [<ObjectWithSomRectAttribute("A", [1, 1, 10, 10], [300, 300, 50, 50])>, <ObjectWithSomRectAttribute("B", [5, 5, 10, 10], [200, 500, 50, 50])>]</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">collisions</span><span class="p">)</span>
|
||||
|
||||
<span class="n">screen_rects</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">collideobjectsall</span><span class="p">(</span><span class="n">objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">o</span><span class="p">:</span> <span class="n">o</span><span class="o">.</span><span class="n">draw_rect</span><span class="p">)</span> <span class="c1"># -> []</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">screen_rects</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.collidedict">
|
||||
<span class="sig-name descname"><span class="pre">collidedict</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.collidedict" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if one rectangle in a dictionary intersects</span></div>
|
||||
<div class="line"><span class="signature">collidedict(dict) -> (key, value)</span></div>
|
||||
<div class="line"><span class="signature">collidedict(dict) -> None</span></div>
|
||||
<div class="line"><span class="signature">collidedict(dict, use_values=0) -> (key, value)</span></div>
|
||||
<div class="line"><span class="signature">collidedict(dict, use_values=0) -> None</span></div>
|
||||
</div>
|
||||
<p>Returns the first key and value pair that intersects with the calling
|
||||
Rect object. If no collisions are found, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned. If
|
||||
<code class="docutils literal notranslate"><span class="pre">use_values</span></code> is 0 (default) then the dict's keys will be used in the
|
||||
collision detection, otherwise the dict's values will be used.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Rect objects cannot be used as keys in a dictionary (they are not
|
||||
hashable), so they must be converted to a tuple.
|
||||
e.g. <code class="docutils literal notranslate"><span class="pre">rect.collidedict({tuple(key_rect)</span> <span class="pre">:</span> <span class="pre">value})</span></code></p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.Rect.collidedictall">
|
||||
<span class="sig-name descname"><span class="pre">collidedictall</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.Rect.collidedictall" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">test if all rectangles in a dictionary intersect</span></div>
|
||||
<div class="line"><span class="signature">collidedictall(dict) -> [(key, value), ...]</span></div>
|
||||
<div class="line"><span class="signature">collidedictall(dict, use_values=0) -> [(key, value), ...]</span></div>
|
||||
</div>
|
||||
<p>Returns a list of all the key and value pairs that intersect with the
|
||||
calling Rect object. If no collisions are found an empty list is returned.
|
||||
If <code class="docutils literal notranslate"><span class="pre">use_values</span></code> is 0 (default) then the dict's keys will be used in the
|
||||
collision detection, otherwise the dict's values will be used.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Rect objects cannot be used as keys in a dictionary (they are not
|
||||
hashable), so they must be converted to a tuple.
|
||||
e.g. <code class="docutils literal notranslate"><span class="pre">rect.collidedictall({tuple(key_rect)</span> <span class="pre">:</span> <span class="pre">value})</span></code></p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.5.0: </span>Added support for keyword arguments.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/rect.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="scrap.html" title="pygame.scrap"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="pygame.html" title="pygame"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.Rect</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,449 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.scrap — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame._sdl2.controller" href="sdl2_controller.html" />
|
||||
<link rel="prev" title="pygame.Rect" href="rect.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.scrap">
|
||||
<span id="pygame-scrap"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.scrap</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for clipboard support.</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="scrap.html#pygame.scrap.init">pygame.scrap.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Initializes the scrap module.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="scrap.html#pygame.scrap.get_init">pygame.scrap.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns True if the scrap module is currently initialized.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="scrap.html#pygame.scrap.get">pygame.scrap.get</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the data for the specified type from the clipboard.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="scrap.html#pygame.scrap.get_types">pygame.scrap.get_types</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets a list of the available clipboard types.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="scrap.html#pygame.scrap.put">pygame.scrap.put</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Places data into the clipboard.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="scrap.html#pygame.scrap.contains">pygame.scrap.contains</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Checks whether data for a given type is available in the clipboard.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="scrap.html#pygame.scrap.lost">pygame.scrap.lost</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Indicates if the clipboard ownership has been lost by the pygame application.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="scrap.html#pygame.scrap.set_mode">pygame.scrap.set_mode</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Sets the clipboard access mode.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p><strong>EXPERIMENTAL!</strong>: This API may change or disappear in later pygame releases. If
|
||||
you use this, your code may break with the next pygame release.</p>
|
||||
<p>The scrap module is for transferring data to/from the clipboard. This allows
|
||||
for cutting and pasting data between pygame and other applications. Some basic
|
||||
data (MIME) types are defined and registered:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">pygame</span> <span class="n">string</span>
|
||||
<span class="n">constant</span> <span class="n">value</span> <span class="n">description</span>
|
||||
<span class="o">--------------------------------------------------</span>
|
||||
<span class="n">SCRAP_TEXT</span> <span class="s2">"text/plain"</span> <span class="n">plain</span> <span class="n">text</span>
|
||||
<span class="n">SCRAP_BMP</span> <span class="s2">"image/bmp"</span> <span class="n">BMP</span> <span class="n">encoded</span> <span class="n">image</span> <span class="n">data</span>
|
||||
<span class="n">SCRAP_PBM</span> <span class="s2">"image/pbm"</span> <span class="n">PBM</span> <span class="n">encoded</span> <span class="n">image</span> <span class="n">data</span>
|
||||
<span class="n">SCRAP_PPM</span> <span class="s2">"image/ppm"</span> <span class="n">PPM</span> <span class="n">encoded</span> <span class="n">image</span> <span class="n">data</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_PPM</span></code>, <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_PBM</span></code> and <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_BMP</span></code> are
|
||||
suitable for surface buffers to be shared with other applications.
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_TEXT</span></code> is an alias for the plain text clipboard type.</p>
|
||||
<p>Depending on the platform, additional types are automatically registered when
|
||||
data is placed into the clipboard to guarantee a consistent sharing behaviour
|
||||
with other applications. The following listed types can be used as strings to
|
||||
be passed to the respective <a class="tooltip reference internal" href="#module-pygame.scrap" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.scrap</span></code><span class="tooltip-content">pygame module for clipboard support.</span></a> module functions.</p>
|
||||
<p>For <strong>Windows</strong> platforms, these additional types are supported automatically
|
||||
and resolve to their internal definitions:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"text/plain;charset=utf-8"</span> <span class="n">UTF</span><span class="o">-</span><span class="mi">8</span> <span class="n">encoded</span> <span class="n">text</span>
|
||||
<span class="s2">"audio/wav"</span> <span class="n">WAV</span> <span class="n">encoded</span> <span class="n">audio</span>
|
||||
<span class="s2">"image/tiff"</span> <span class="n">TIFF</span> <span class="n">encoded</span> <span class="n">image</span> <span class="n">data</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For <strong>X11</strong> platforms, these additional types are supported automatically and
|
||||
resolve to their internal definitions:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"text/plain;charset=utf-8"</span> <span class="n">UTF</span><span class="o">-</span><span class="mi">8</span> <span class="n">encoded</span> <span class="n">text</span>
|
||||
<span class="s2">"UTF8_STRING"</span> <span class="n">UTF</span><span class="o">-</span><span class="mi">8</span> <span class="n">encoded</span> <span class="n">text</span>
|
||||
<span class="s2">"COMPOUND_TEXT"</span> <span class="n">COMPOUND</span> <span class="n">text</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>User defined types can be used, but the data might not be accessible by other
|
||||
applications unless they know what data type to look for.
|
||||
Example: Data placed into the clipboard by
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.scrap.put("my_data_type",</span> <span class="pre">byte_data)</span></code> can only be accessed by
|
||||
applications which query the clipboard for the <code class="docutils literal notranslate"><span class="pre">"my_data_type"</span></code> data type.</p>
|
||||
<p>For an example of how the scrap module works refer to the examples page
|
||||
(<a class="tooltip reference internal" href="examples.html#pygame.examples.scrap_clipboard.main" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.examples.scrap_clipboard.main()</span></code><span class="tooltip-content">access the clipboard</span></a>) or the code directly in GitHub
|
||||
(<a class="reference external" href="https://github.com/pygame/pygame/blob/main/examples/scrap_clipboard.py">pygame/examples/scrap_clipboard.py</a>).</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The scrap module is currently only supported for Windows, X11 and Mac OS X.
|
||||
On Mac OS X only text works at the moment - other types may be supported in
|
||||
future releases.</p>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.scrap.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.scrap.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.scrap.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Initializes the scrap module.</span></div>
|
||||
<div class="line"><span class="signature">init() -> None</span></div>
|
||||
</div>
|
||||
<p>Initialize the scrap module.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><a class="tooltip reference internal" href="pygame.html#pygame.error" title=""><strong>pygame.error</strong><span class="tooltip-content">standard pygame exception</span></a> -- if unable to initialize scrap module</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The scrap module requires <a class="tooltip reference internal" href="display.html#pygame.display.set_mode" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.display.set_mode()</span></code><span class="tooltip-content">Initialize a window or screen for display</span></a> be
|
||||
called before being initialized.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.scrap.get_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.scrap.</span></span><span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.scrap.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns True if the scrap module is currently initialized.</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Gets the scrap module's initialization state.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the <a class="tooltip reference internal" href="#module-pygame.scrap" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.scrap</span></code><span class="tooltip-content">pygame module for clipboard support.</span></a> module is currently
|
||||
initialized, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise</p>
|
||||
</dd>
|
||||
<dt class="field-even">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>bool</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9.5.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.scrap.get">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.scrap.</span></span><span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.scrap.get" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the data for the specified type from the clipboard.</span></div>
|
||||
<div class="line"><span class="signature">get(type) -> bytes | None</span></div>
|
||||
</div>
|
||||
<p>Retrieves the data for the specified type from the clipboard. The data is
|
||||
returned as a byte string and might need further processing (such as
|
||||
decoding to Unicode).</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>type</strong> (<em>string</em>) -- data type to retrieve from the clipboard</p>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>data (bytes object) for the given type identifier or <code class="docutils literal notranslate"><span class="pre">None</span></code> if
|
||||
no data for the given type is available</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>bytes | None</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">text</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">pygame</span><span class="o">.</span><span class="n">SCRAP_TEXT</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">text</span><span class="p">:</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s2">"There is text in the clipboard."</span><span class="p">)</span>
|
||||
<span class="k">else</span><span class="p">:</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s2">"There does not seem to be text in the clipboard."</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.scrap.get_types">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.scrap.</span></span><span class="sig-name descname"><span class="pre">get_types</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.scrap.get_types" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets a list of the available clipboard types.</span></div>
|
||||
<div class="line"><span class="signature">get_types() -> list</span></div>
|
||||
</div>
|
||||
<p>Gets a list of data type string identifiers for the data currently
|
||||
available on the clipboard. Each identifier can be used in the
|
||||
<a class="tooltip reference internal" href="#pygame.scrap.get" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.scrap.get()</span></code><span class="tooltip-content">Gets the data for the specified type from the clipboard.</span></a> method to get the clipboard content of the
|
||||
specific type.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>list of strings of the available clipboard data types, if there
|
||||
is no data in the clipboard an empty list is returned</p>
|
||||
</dd>
|
||||
<dt class="field-even">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>list</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">get_types</span><span class="p">():</span>
|
||||
<span class="k">if</span> <span class="s2">"text"</span> <span class="ow">in</span> <span class="n">t</span><span class="p">:</span>
|
||||
<span class="c1"># There is some content with the word "text" in its type string.</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">t</span><span class="p">))</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.scrap.put">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.scrap.</span></span><span class="sig-name descname"><span class="pre">put</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.scrap.put" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Places data into the clipboard.</span></div>
|
||||
<div class="line"><span class="signature">put(type, data) -> None</span></div>
|
||||
</div>
|
||||
<p>Places data for a given clipboard type into the clipboard. The data must
|
||||
be a string buffer. The type is a string identifying the type of data to be
|
||||
placed into the clipboard. This can be one of the predefined
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_PBM</span></code>, <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_PPM</span></code>, <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_BMP</span></code> or
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_TEXT</span></code> values or a user defined string identifier.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>type</strong> (<em>string</em>) -- type identifier of the data to be placed into the
|
||||
clipboard</p></li>
|
||||
<li><p><strong>data</strong> (<em>bytes</em>) -- data to be place into the clipboard, a bytes object</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p><a class="tooltip reference internal" href="pygame.html#pygame.error" title=""><strong>pygame.error</strong><span class="tooltip-content">standard pygame exception</span></a> -- if unable to put the data into the clipboard</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"example.bmp"</span><span class="p">,</span> <span class="s2">"rb"</span><span class="p">)</span> <span class="k">as</span> <span class="n">fp</span><span class="p">:</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">pygame</span><span class="o">.</span><span class="n">SCRAP_BMP</span><span class="p">,</span> <span class="n">fp</span><span class="o">.</span><span class="n">read</span><span class="p">())</span>
|
||||
<span class="c1"># The image data is now on the clipboard for other applications to access</span>
|
||||
<span class="c1"># it.</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">pygame</span><span class="o">.</span><span class="n">SCRAP_TEXT</span><span class="p">,</span> <span class="sa">b</span><span class="s2">"A text to copy"</span><span class="p">)</span>
|
||||
<span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s2">"Plain text"</span><span class="p">,</span> <span class="sa">b</span><span class="s2">"Data for user defined type 'Plain text'"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.scrap.contains">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.scrap.</span></span><span class="sig-name descname"><span class="pre">contains</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.scrap.contains" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Checks whether data for a given type is available in the clipboard.</span></div>
|
||||
<div class="line"><span class="signature">contains(type) -> bool</span></div>
|
||||
</div>
|
||||
<p>Checks whether data for the given type is currently available in the
|
||||
clipboard.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>type</strong> (<em>string</em>) -- data type to check availability of</p>
|
||||
</dd>
|
||||
<dt class="field-even">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if data for the passed type is available in the
|
||||
clipboard, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>bool</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">contains</span><span class="p">(</span><span class="n">pygame</span><span class="o">.</span><span class="n">SCRAP_TEXT</span><span class="p">):</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s2">"There is text in the clipboard."</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">contains</span><span class="p">(</span><span class="s2">"own_data_type"</span><span class="p">):</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s2">"There is stuff in the clipboard."</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.scrap.lost">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.scrap.</span></span><span class="sig-name descname"><span class="pre">lost</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.scrap.lost" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Indicates if the clipboard ownership has been lost by the pygame application.</span></div>
|
||||
<div class="line"><span class="signature">lost() -> bool</span></div>
|
||||
</div>
|
||||
<p>Indicates if the clipboard ownership has been lost by the pygame
|
||||
application.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">True</span></code>, if the clipboard ownership has been lost by the pygame
|
||||
application, <code class="docutils literal notranslate"><span class="pre">False</span></code> if the pygame application still owns the clipboard</p>
|
||||
</dd>
|
||||
<dt class="field-even">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>bool</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">pygame</span><span class="o">.</span><span class="n">scrap</span><span class="o">.</span><span class="n">lost</span><span class="p">():</span>
|
||||
<span class="nb">print</span><span class="p">(</span><span class="s2">"The clipboard is in use by another application."</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.scrap.set_mode">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.scrap.</span></span><span class="sig-name descname"><span class="pre">set_mode</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.scrap.set_mode" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Sets the clipboard access mode.</span></div>
|
||||
<div class="line"><span class="signature">set_mode(mode) -> None</span></div>
|
||||
</div>
|
||||
<p>Sets the access mode for the clipboard. This is only of interest for X11
|
||||
environments where clipboard modes <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_SELECTION</span></code> (for mouse
|
||||
selections) and <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_CLIPBOARD</span></code> (for the clipboard) are
|
||||
available. Setting the mode to <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_SELECTION</span></code> in other
|
||||
environments will not change the mode from <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_CLIPBOARD</span></code>.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>mode</strong> -- access mode, supported values are <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_CLIPBOARD</span></code>
|
||||
and <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_SELECTION</span></code> (<code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_SELECTION</span></code> only has an
|
||||
effect when used on X11 platforms)</p>
|
||||
</dd>
|
||||
<dt class="field-even">Raises<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p><strong>ValueError</strong> -- if the <code class="docutils literal notranslate"><span class="pre">mode</span></code> parameter is not
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_CLIPBOARD</span></code> or <code class="docutils literal notranslate"><span class="pre">pygame.SCRAP_SELECTION</span></code></p>
|
||||
</dd>
|
||||
</dl>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/scrap.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="sdl2_controller.html" title="pygame._sdl2.controller"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="rect.html" title="pygame.Rect"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.scrap</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,555 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame._sdl2.controller — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.sdl2_video" href="sdl2_video.html" />
|
||||
<link rel="prev" title="pygame.scrap" href="scrap.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame._sdl2.controller">
|
||||
<span id="pygame-sdl2-controller"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame._sdl2.controller</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Pygame module to work with controllers.</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.init">pygame._sdl2.controller.init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>initialize the controller module</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.quit">pygame._sdl2.controller.quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Uninitialize the controller module.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.get_init">pygame._sdl2.controller.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns True if the controller module is initialized.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.set_eventstate">pygame._sdl2.controller.set_eventstate</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Sets the current state of events related to controllers</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.get_eventstate">pygame._sdl2.controller.get_eventstate</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the current state of events related to controllers</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.get_count">pygame._sdl2.controller.get_count</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Get the number of joysticks connected</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.is_controller">pygame._sdl2.controller.is_controller</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Check if the given joystick is supported by the game controller interface</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.name_forindex">pygame._sdl2.controller.name_forindex</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Get the name of the controller</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller">pygame._sdl2.controller.Controller</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Create a new Controller object.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>This module offers control over common controller types like the dualshock 4 or
|
||||
the xbox 360 controllers: They have two analog sticks, two triggers, two shoulder buttons,
|
||||
a dpad, 4 buttons on the side, 2 (or 3) buttons in the middle.</p>
|
||||
<p>Pygame uses xbox controllers naming conventions (like a, b, x, y for buttons) but
|
||||
they always refer to the same buttons. For example <code class="docutils literal notranslate"><span class="pre">CONTROLLER_BUTTON_X</span></code> is
|
||||
always the leftmost button of the 4 buttons on the right.</p>
|
||||
<p>Controllers can generate the following events:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">CONTROLLERAXISMOTION</span><span class="p">,</span> <span class="n">CONTROLLERBUTTONDOWN</span><span class="p">,</span> <span class="n">CONTROLLERBUTTONUP</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLERDEVICEREMAPPED</span><span class="p">,</span> <span class="n">CONTROLLERDEVICEADDED</span><span class="p">,</span> <span class="n">CONTROLLERDEVICEREMOVED</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Additionally if pygame is built with SDL 2.0.14 or higher the following events can also be generated
|
||||
(to get the version of sdl pygame is built with use <a class="tooltip reference internal" href="pygame.html#pygame.version.SDL" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.version.SDL()</span></code><span class="tooltip-content">tupled integers of the SDL library version</span></a>):</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">CONTROLLERTOUCHPADDOWN</span><span class="p">,</span> <span class="n">CONTROLLERTOUCHPADMOTION</span><span class="p">,</span> <span class="n">CONTROLLERTOUCHPADUP</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>These events can be enabled/disabled by <a class="tooltip reference internal" href="#pygame._sdl2.controller.set_eventstate" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame._sdl2.controller.set_eventstate()</span></code><span class="tooltip-content">Sets the current state of events related to controllers</span></a>
|
||||
Note that controllers can generate joystick events as well. This function only toggles
|
||||
events related to controllers.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>See the <a class="tooltip reference internal" href="joystick.html#module-pygame.joystick" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.joystick</span></code><span class="tooltip-content">Pygame module for interacting with joysticks, gamepads, and trackballs.</span></a> for a more versatile but more advanced api.</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2: </span>This module requires SDL2.</p>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">initialize the controller module</span></div>
|
||||
<div class="line"><span class="signature">init() -> None</span></div>
|
||||
</div>
|
||||
<p>Initialize the controller module.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.quit">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Uninitialize the controller module.</span></div>
|
||||
<div class="line"><span class="signature">quit() -> None</span></div>
|
||||
</div>
|
||||
<p>Uninitialize the controller module.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.get_init">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns True if the controller module is initialized.</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Test if <code class="docutils literal notranslate"><span class="pre">pygame._sdl2.controller.init()</span></code> was called.</p>
|
||||
<blockquote>
|
||||
<div></div></blockquote>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.set_eventstate">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">set_eventstate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.set_eventstate" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Sets the current state of events related to controllers</span></div>
|
||||
<div class="line"><span class="signature">set_eventstate(state) -> None</span></div>
|
||||
</div>
|
||||
<p>Enable or disable events connected to controllers.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Controllers can still generate joystick events, which will not be toggled by this function.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2:: </span>Changed return type from int to None</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.get_eventstate">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">get_eventstate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.get_eventstate" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the current state of events related to controllers</span></div>
|
||||
<div class="line"><span class="signature">get_eventstate() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns the current state of events related to controllers, True meaning
|
||||
events will be posted.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.get_count">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">get_count</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.get_count" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Get the number of joysticks connected</span></div>
|
||||
<div class="line"><span class="signature">get_count() -> int</span></div>
|
||||
</div>
|
||||
<p>Get the number of joysticks connected.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.is_controller">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">is_controller</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.is_controller" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Check if the given joystick is supported by the game controller interface</span></div>
|
||||
<div class="line"><span class="signature">is_controller(index) -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns True if the index given can be used to create a controller object.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.name_forindex">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">name_forindex</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.name_forindex" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Get the name of the controller</span></div>
|
||||
<div class="line"><span class="signature">name_forindex(index) -> name or None</span></div>
|
||||
</div>
|
||||
<p>Returns the name of controller, or None if there's no name or the
|
||||
index is invalid.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.controller.</span></span><span class="sig-name descname"><span class="pre">Controller</span></span><a class="headerlink" href="#pygame._sdl2.controller.Controller" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><blockquote>
|
||||
<div><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Create a new Controller object.</span></div>
|
||||
<div class="line"><span class="signature">Controller(index) -> Controller</span></div>
|
||||
</div>
|
||||
<p>Create a new Controller object. Index should be integer between
|
||||
0 and <code class="docutils literal notranslate"><span class="pre">pygame._sdl2.controller.get_count()</span></code>. Controllers also
|
||||
can be created from a <code class="docutils literal notranslate"><span class="pre">pygame.joystick.Joystick</span></code> using
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame._sdl2.controller.from_joystick</span></code>. Controllers are
|
||||
initialized on creation.</p>
|
||||
</div></blockquote>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.quit">pygame._sdl2.controller.Controller.quit</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>uninitialize the Controller</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.get_init">pygame._sdl2.controller.Controller.get_init</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>check if the Controller is initialized</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.from_joystick">pygame._sdl2.controller.Controller.from_joystick</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Create a Controller from a pygame.joystick.Joystick object</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.attached">pygame._sdl2.controller.Controller.attached</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Check if the Controller has been opened and is currently connected.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.as_joystick">pygame._sdl2.controller.Controller.as_joystick</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Returns a pygame.joystick.Joystick() object</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.get_axis">pygame._sdl2.controller.Controller.get_axis</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Get the current state of a joystick axis</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.get_button">pygame._sdl2.controller.Controller.get_button</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Get the current state of a button</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.get_mapping">pygame._sdl2.controller.Controller.get_mapping</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Get the mapping assigned to the controller</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.set_mapping">pygame._sdl2.controller.Controller.set_mapping</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Assign a mapping to the controller</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.rumble">pygame._sdl2.controller.Controller.rumble</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Start a rumbling effect</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sdl2_controller.html#pygame._sdl2.controller.Controller.stop_rumble">pygame._sdl2.controller.Controller.stop_rumble</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Stop any rumble effect playing</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.quit">
|
||||
<span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.quit" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">uninitialize the Controller</span></div>
|
||||
<div class="line"><span class="signature">quit() -> None</span></div>
|
||||
</div>
|
||||
<p>Close a Controller object. After this the pygame event queue will no longer
|
||||
receive events from the device.</p>
|
||||
<p>It is safe to call this more than once.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.get_init">
|
||||
<span class="sig-name descname"><span class="pre">get_init</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.get_init" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">check if the Controller is initialized</span></div>
|
||||
<div class="line"><span class="signature">get_init() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns True if the Controller object is currently initialised.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.from_joystick">
|
||||
<em class="property"><span class="pre">static</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_joystick</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.from_joystick" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Create a Controller from a pygame.joystick.Joystick object</span></div>
|
||||
<div class="line"><span class="signature">from_joystick(joystick) -> Controller</span></div>
|
||||
</div>
|
||||
<p>Create a Controller object from a <code class="docutils literal notranslate"><span class="pre">pygame.joystick.Joystick</span></code> object</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.attached">
|
||||
<span class="sig-name descname"><span class="pre">attached</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.attached" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Check if the Controller has been opened and is currently connected.</span></div>
|
||||
<div class="line"><span class="signature">attached() -> bool</span></div>
|
||||
</div>
|
||||
<p>Returns True if the Controller object is opened and connected.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.as_joystick">
|
||||
<span class="sig-name descname"><span class="pre">as_joystick</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.as_joystick" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Returns a pygame.joystick.Joystick() object</span></div>
|
||||
<div class="line"><span class="signature">as_joystick() -> Joystick object</span></div>
|
||||
</div>
|
||||
<p>Returns a pygame.joystick.Joystick() object created from this controller's index</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.get_axis">
|
||||
<span class="sig-name descname"><span class="pre">get_axis</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.get_axis" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Get the current state of a joystick axis</span></div>
|
||||
<div class="line"><span class="signature">get_axis(axis) -> int</span></div>
|
||||
</div>
|
||||
<p>Get the current state of a trigger or joystick axis.
|
||||
The axis argument must be one of the following constants:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">CONTROLLER_AXIS_LEFTX</span><span class="p">,</span> <span class="n">CONTROLLER_AXIS_LEFTY</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLER_AXIS_RIGHTX</span><span class="p">,</span> <span class="n">CONTROLLER_AXIS_RIGHTY</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLER_AXIS_TRIGGERLEFT</span><span class="p">,</span> <span class="n">CONTROLLER_AXIS_TRIGGERRIGHT</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Joysticks can return a value between -32768 and 32767. Triggers however
|
||||
can only return a value between 0 and 32768.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.get_button">
|
||||
<span class="sig-name descname"><span class="pre">get_button</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.get_button" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Get the current state of a button</span></div>
|
||||
<div class="line"><span class="signature">get_button(button) -> bool</span></div>
|
||||
</div>
|
||||
<p>Get the current state of a button, True meaning it is pressed down.
|
||||
The button argument must be one of the following constants:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">CONTROLLER_BUTTON_A</span><span class="p">,</span> <span class="n">CONTROLLER_BUTTON_B</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLER_BUTTON_X</span><span class="p">,</span> <span class="n">CONTROLLER_BUTTON_Y</span>
|
||||
<span class="n">CONTROLLER_BUTTON_DPAD_UP</span><span class="p">,</span> <span class="n">CONTROLLER_BUTTON_DPAD_DOWN</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLER_BUTTON_DPAD_LEFT</span><span class="p">,</span> <span class="n">CONTROLLER_BUTTON_DPAD_RIGHT</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLER_BUTTON_LEFTSHOULDER</span><span class="p">,</span> <span class="n">CONTROLLER_BUTTON_RIGHTSHOULDER</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLER_BUTTON_LEFTSTICK</span><span class="p">,</span> <span class="n">CONTROLLER_BUTTON_RIGHTSTICK</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLER_BUTTON_BACK</span><span class="p">,</span> <span class="n">CONTROLLER_BUTTON_GUIDE</span><span class="p">,</span>
|
||||
<span class="n">CONTROLLER_BUTTON_START</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.get_mapping">
|
||||
<span class="sig-name descname"><span class="pre">get_mapping</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.get_mapping" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Get the mapping assigned to the controller</span></div>
|
||||
<div class="line"><span class="signature">get_mapping() -> mapping</span></div>
|
||||
</div>
|
||||
<p>Returns a dict containing the mapping of the Controller. For more
|
||||
information see <a class="reference internal" href="#pygame._sdl2.controller.Controller.set_mapping" title="pygame._sdl2.controller.Controller.set_mapping"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Controller.set_mapping()</span></code></a></p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2:: </span>Return type changed from <code class="docutils literal notranslate"><span class="pre">str</span></code> to <code class="docutils literal notranslate"><span class="pre">dict</span></code></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.set_mapping">
|
||||
<span class="sig-name descname"><span class="pre">set_mapping</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.set_mapping" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Assign a mapping to the controller</span></div>
|
||||
<div class="line"><span class="signature">set_mapping(mapping) -> int</span></div>
|
||||
</div>
|
||||
<p>Rebind buttons, axes, triggers and dpads. The mapping should be a
|
||||
dict containing all buttons, hats and axes. The easiest way to get this
|
||||
is to use the dict returned by <a class="reference internal" href="#pygame._sdl2.controller.Controller.get_mapping" title="pygame._sdl2.controller.Controller.get_mapping"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Controller.get_mapping()</span></code></a>. To edit
|
||||
this mapping assign a value to the original button. The value of the
|
||||
dictionary must be a button, hat or axis represented in the following way:</p>
|
||||
<ul class="simple">
|
||||
<li><p>For a button use: bX where X is the index of the button.</p></li>
|
||||
<li><p>For a hat use: hX.Y where X is the index and the Y is the direction (up: 1, right: 2, down: 3, left: 4).</p></li>
|
||||
<li><p>For an axis use: aX where x is the index of the axis.</p></li>
|
||||
</ul>
|
||||
<p>An example of mapping:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mapping</span> <span class="o">=</span> <span class="n">controller</span><span class="o">.</span><span class="n">get_mapping</span><span class="p">()</span> <span class="c1"># Get current mapping</span>
|
||||
<span class="n">mapping</span><span class="p">[</span><span class="s2">"a"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"b3"</span> <span class="c1"># Remap button a to y</span>
|
||||
<span class="n">mapping</span><span class="p">[</span><span class="s2">"y"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"b0"</span> <span class="c1"># Remap button y to a</span>
|
||||
<span class="n">controller</span><span class="o">.</span><span class="n">set_mapping</span><span class="p">(</span><span class="n">mapping</span><span class="p">)</span> <span class="c1"># Set the mapping</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The function will return 1 if a new mapping is added or 0 if an existing one is updated.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2:: </span>Renamed from <code class="docutils literal notranslate"><span class="pre">add_mapping</span></code> to <code class="docutils literal notranslate"><span class="pre">set_mapping</span></code></p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2:: </span>Argument type changed from <code class="docutils literal notranslate"><span class="pre">str</span></code> to <code class="docutils literal notranslate"><span class="pre">dict</span></code></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.rumble">
|
||||
<span class="sig-name descname"><span class="pre">rumble</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.rumble" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Start a rumbling effect</span></div>
|
||||
<div class="line"><span class="signature">rumble(low_frequency, high_frequency, duration) -> bool</span></div>
|
||||
</div>
|
||||
<p>Start a rumble effect on the controller, with the specified strength ranging
|
||||
from 0 to 1. Duration is length of the effect, in ms. Setting the duration
|
||||
to 0 will play the effect until another one overwrites it or
|
||||
<a class="reference internal" href="#pygame._sdl2.controller.Controller.stop_rumble" title="pygame._sdl2.controller.Controller.stop_rumble"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Controller.stop_rumble()</span></code></a> is called. If an effect is already
|
||||
playing, then it will be overwritten.</p>
|
||||
<p>Returns True if the rumble was played successfully or False if the
|
||||
controller does not support it or <a class="tooltip reference internal" href="pygame.html#pygame.version.SDL" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.version.SDL()</span></code><span class="tooltip-content">tupled integers of the SDL library version</span></a> is below 2.0.9.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.controller.Controller.stop_rumble">
|
||||
<span class="sig-name descname"><span class="pre">stop_rumble</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.controller.Controller.stop_rumble" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Stop any rumble effect playing</span></div>
|
||||
<div class="line"><span class="signature">stop_rumble() -> None</span></div>
|
||||
</div>
|
||||
<p>Stops any rumble effect playing on the controller. See
|
||||
<a class="reference internal" href="#pygame._sdl2.controller.Controller.rumble" title="pygame._sdl2.controller.Controller.rumble"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Controller.rumble()</span></code></a> for more information.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/sdl2_controller.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="sdl2_video.html" title="pygame.sdl2_video"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="scrap.html" title="pygame.scrap"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame._sdl2.controller</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,265 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.sndarray — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.sprite" href="sprite.html" />
|
||||
<link rel="prev" title="pygame.sdl2_video" href="sdl2_video.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.sndarray">
|
||||
<span id="pygame-sndarray"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.sndarray</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for accessing sound sample data</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sndarray.html#pygame.sndarray.array">pygame.sndarray.array</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>copy Sound samples into an array</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sndarray.html#pygame.sndarray.samples">pygame.sndarray.samples</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>reference Sound samples into an array</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sndarray.html#pygame.sndarray.make_sound">pygame.sndarray.make_sound</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>convert an array into a Sound object</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sndarray.html#pygame.sndarray.use_arraytype">pygame.sndarray.use_arraytype</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Sets the array system to be used for sound arrays</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="sndarray.html#pygame.sndarray.get_arraytype">pygame.sndarray.get_arraytype</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the currently active array type.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="sndarray.html#pygame.sndarray.get_arraytypes">pygame.sndarray.get_arraytypes</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the array system types currently supported.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Functions to convert between NumPy arrays and Sound objects. This
|
||||
module will only be functional when pygame can use the external NumPy
|
||||
package. If NumPy can't be imported, <code class="docutils literal notranslate"><span class="pre">surfarray</span></code> becomes a <code class="docutils literal notranslate"><span class="pre">MissingModule</span></code>
|
||||
object.</p>
|
||||
<p>Sound data is made of thousands of samples per second, and each sample is the
|
||||
amplitude of the wave at a particular moment in time. For example, in 22-kHz
|
||||
format, element number 5 of the array is the amplitude of the wave after
|
||||
5/22000 seconds.</p>
|
||||
<p>The arrays are indexed by the <code class="docutils literal notranslate"><span class="pre">X</span></code> axis first, followed by the <code class="docutils literal notranslate"><span class="pre">Y</span></code> axis.
|
||||
Each sample is an 8-bit or 16-bit integer, depending on the data format. A
|
||||
stereo sound file has two values per sample, while a mono sound file only has
|
||||
one.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.sndarray.array">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.sndarray.</span></span><span class="sig-name descname"><span class="pre">array</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.sndarray.array" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">copy Sound samples into an array</span></div>
|
||||
<div class="line"><span class="signature">array(Sound) -> array</span></div>
|
||||
</div>
|
||||
<p>Creates a new array for the sound data and copies the samples. The array
|
||||
will always be in the format returned from <code class="docutils literal notranslate"><span class="pre">pygame.mixer.get_init()</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.sndarray.samples">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.sndarray.</span></span><span class="sig-name descname"><span class="pre">samples</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.sndarray.samples" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">reference Sound samples into an array</span></div>
|
||||
<div class="line"><span class="signature">samples(Sound) -> array</span></div>
|
||||
</div>
|
||||
<p>Creates a new array that directly references the samples in a Sound object.
|
||||
Modifying the array will change the Sound. The array will always be in the
|
||||
format returned from <code class="docutils literal notranslate"><span class="pre">pygame.mixer.get_init()</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.sndarray.make_sound">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.sndarray.</span></span><span class="sig-name descname"><span class="pre">make_sound</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.sndarray.make_sound" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">convert an array into a Sound object</span></div>
|
||||
<div class="line"><span class="signature">make_sound(array) -> Sound</span></div>
|
||||
</div>
|
||||
<p>Create a new playable Sound object from an array. The mixer module must be
|
||||
initialized and the array format must be similar to the mixer audio format.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.sndarray.use_arraytype">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.sndarray.</span></span><span class="sig-name descname"><span class="pre">use_arraytype</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.sndarray.use_arraytype" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Sets the array system to be used for sound arrays</span></div>
|
||||
<div class="line"><span class="signature">use_arraytype (arraytype) -> None</span></div>
|
||||
</div>
|
||||
<p>DEPRECATED: Uses the requested array type for the module functions. The
|
||||
only supported arraytype is <code class="docutils literal notranslate"><span class="pre">'numpy'</span></code>. Other values will raise ValueError.
|
||||
Using this function will raise a <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code>.
|
||||
.. ## pygame.sndarray.use_arraytype ##</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.sndarray.get_arraytype">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.sndarray.</span></span><span class="sig-name descname"><span class="pre">get_arraytype</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.sndarray.get_arraytype" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the currently active array type.</span></div>
|
||||
<div class="line"><span class="signature">get_arraytype () -> str</span></div>
|
||||
</div>
|
||||
<p>DEPRECATED: Returns the currently active array type. This will be a value of the
|
||||
<code class="docutils literal notranslate"><span class="pre">get_arraytypes()</span></code> tuple and indicates which type of array module is used
|
||||
for the array creation. Using this function will raise a <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code>.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.sndarray.get_arraytypes">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.sndarray.</span></span><span class="sig-name descname"><span class="pre">get_arraytypes</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.sndarray.get_arraytypes" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the array system types currently supported.</span></div>
|
||||
<div class="line"><span class="signature">get_arraytypes () -> tuple</span></div>
|
||||
</div>
|
||||
<p>DEPRECATED: Checks, which array systems are available and returns them as a tuple of
|
||||
strings. The values of the tuple can be used directly in the
|
||||
<a class="tooltip reference internal" href="#pygame.sndarray.use_arraytype" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.sndarray.use_arraytype()</span></code><span class="tooltip-content">Sets the array system to be used for sound arrays</span></a> () method. If no supported array
|
||||
system could be found, None will be returned. Using this function will raise a
|
||||
<code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code>.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/sndarray.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="sprite.html" title="pygame.sprite"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="sdl2_video.html" title="pygame.sdl2_video"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.sndarray</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,562 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.surfarray — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.tests" href="tests.html" />
|
||||
<link rel="prev" title="pygame.Surface" href="surface.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.surfarray">
|
||||
<span id="pygame-surfarray"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.surfarray</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for accessing surface pixel data using array interfaces</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.array2d">pygame.surfarray.array2d</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy pixels into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.pixels2d">pygame.surfarray.pixels2d</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Reference pixels into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.array3d">pygame.surfarray.array3d</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy pixels into a 3d array</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.pixels3d">pygame.surfarray.pixels3d</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Reference pixels into a 3d array</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.array_alpha">pygame.surfarray.array_alpha</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy pixel alphas into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.pixels_alpha">pygame.surfarray.pixels_alpha</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Reference pixel alphas into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.array_red">pygame.surfarray.array_red</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy red pixels into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.pixels_red">pygame.surfarray.pixels_red</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Reference pixel red into a 2d array.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.array_green">pygame.surfarray.array_green</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy green pixels into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.pixels_green">pygame.surfarray.pixels_green</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Reference pixel green into a 2d array.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.array_blue">pygame.surfarray.array_blue</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy blue pixels into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.pixels_blue">pygame.surfarray.pixels_blue</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Reference pixel blue into a 2d array.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.array_colorkey">pygame.surfarray.array_colorkey</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy the colorkey values into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.make_surface">pygame.surfarray.make_surface</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Copy an array to a new surface</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.blit_array">pygame.surfarray.blit_array</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Blit directly from a array values</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.map_array">pygame.surfarray.map_array</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Map a 3d array into a 2d array</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.use_arraytype">pygame.surfarray.use_arraytype</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Sets the array system to be used for surface arrays</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.get_arraytype">pygame.surfarray.get_arraytype</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the currently active array type.</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="surfarray.html#pygame.surfarray.get_arraytypes">pygame.surfarray.get_arraytypes</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Gets the array system types currently supported.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Functions to convert between NumPy arrays and Surface objects. This module
|
||||
will only be functional when pygame can use the external NumPy package.
|
||||
If NumPy can't be imported, <code class="docutils literal notranslate"><span class="pre">surfarray</span></code> becomes a <code class="docutils literal notranslate"><span class="pre">MissingModule</span></code> object.</p>
|
||||
<p>Every pixel is stored as a single integer value to represent the red, green,
|
||||
and blue colors. The 8-bit images use a value that looks into a colormap. Pixels
|
||||
with higher depth use a bit packing process to place three or four values into
|
||||
a single number.</p>
|
||||
<p>The arrays are indexed by the <code class="docutils literal notranslate"><span class="pre">X</span></code> axis first, followed by the <code class="docutils literal notranslate"><span class="pre">Y</span></code> axis.
|
||||
Arrays that treat the pixels as a single integer are referred to as 2D arrays.
|
||||
This module can also separate the red, green, and blue color values into
|
||||
separate indices. These types of arrays are referred to as 3D arrays, and the
|
||||
last index is 0 for red, 1 for green, and 2 for blue.</p>
|
||||
<p>The pixels of a 2D array as returned by <a class="reference internal" href="#pygame.surfarray.array2d" title="pygame.surfarray.array2d"><code class="xref py py-func docutils literal notranslate"><span class="pre">array2d()</span></code></a> and <a class="reference internal" href="#pygame.surfarray.pixels2d" title="pygame.surfarray.pixels2d"><code class="xref py py-func docutils literal notranslate"><span class="pre">pixels2d()</span></code></a>
|
||||
are mapped to the specific surface. Use <a class="tooltip reference internal" href="surface.html#pygame.Surface.unmap_rgb" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.unmap_rgb()</span></code><span class="tooltip-content">convert a mapped integer color value into a Color</span></a>
|
||||
to convert to a color, and <a class="tooltip reference internal" href="surface.html#pygame.Surface.map_rgb" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.map_rgb()</span></code><span class="tooltip-content">convert a color into a mapped color value</span></a> to get the surface
|
||||
specific pixel value of a color. Integer pixel values can only be used directly
|
||||
between surfaces with matching pixel layouts (see <a class="tooltip reference internal" href="surface.html#pygame.Surface" title=""><code class="xref py py-class docutils literal notranslate"><span class="pre">pygame.Surface</span></code><span class="tooltip-content">pygame object for representing images</span></a>).</p>
|
||||
<p>All functions that refer to "array" will copy the surface information to a new
|
||||
numpy array. All functions that refer to "pixels" will directly reference the
|
||||
pixels from the surface and any changes performed to the array will make changes
|
||||
in the surface. As this last functions share memory with the surface, this one
|
||||
will be locked during the lifetime of the array.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.array2d">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">array2d</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.array2d" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy pixels into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">array2d(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Copy the <a class="reference internal" href="surface.html#pygame.Surface.map_rgb" title="pygame.Surface.map_rgb"><code class="xref py py-meth docutils literal notranslate"><span class="pre">mapped</span></code></a> (raw) pixels from a Surface
|
||||
into a 2D array.
|
||||
The bit depth of the surface will control the size of the integer values,
|
||||
and will work for any type of pixel format.</p>
|
||||
<p>This function will temporarily lock the Surface as pixels are copied
|
||||
(see the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method).</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.pixels2d">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">pixels2d</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.pixels2d" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Reference pixels into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">pixels2d(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Create a new 2D array that directly references the pixel values in a
|
||||
Surface. Any changes to the array will affect the pixels in the Surface.
|
||||
This is a fast operation since no data is copied.</p>
|
||||
<p>Pixels from a 24-bit Surface cannot be referenced, but all other Surface bit
|
||||
depths can.</p>
|
||||
<p>The Surface this references will remain locked for the lifetime of the array,
|
||||
since the array generated by this function shares memory with the surface.
|
||||
See the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.array3d">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">array3d</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.array3d" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy pixels into a 3d array</span></div>
|
||||
<div class="line"><span class="signature">array3d(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Copy the pixels from a Surface into a 3D array. The bit depth of the surface
|
||||
will control the size of the integer values, and will work for any type of
|
||||
pixel format.</p>
|
||||
<p>This function will temporarily lock the Surface as pixels are copied (see
|
||||
the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method).</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.pixels3d">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">pixels3d</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.pixels3d" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Reference pixels into a 3d array</span></div>
|
||||
<div class="line"><span class="signature">pixels3d(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Create a new 3D array that directly references the pixel values in a
|
||||
Surface. Any changes to the array will affect the pixels in the Surface.
|
||||
This is a fast operation since no data is copied.</p>
|
||||
<p>This will only work on Surfaces that have 24-bit or 32-bit formats. Lower
|
||||
pixel formats cannot be referenced.</p>
|
||||
<p>The Surface this references will remain locked for the lifetime of the array,
|
||||
since the array generated by this function shares memory with the surface.
|
||||
See the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.array_alpha">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">array_alpha</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.array_alpha" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy pixel alphas into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">array_alpha(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Copy the pixel alpha values (degree of transparency) from a Surface into a
|
||||
2D array. This will work for any type of Surface format. Surfaces without a
|
||||
pixel alpha will return an array with all opaque values.</p>
|
||||
<p>This function will temporarily lock the Surface as pixels are copied (see
|
||||
the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method).</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.pixels_alpha">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">pixels_alpha</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.pixels_alpha" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Reference pixel alphas into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">pixels_alpha(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Create a new 2D array that directly references the alpha values (degree of
|
||||
transparency) in a Surface. Any changes to the array will affect the pixels
|
||||
in the Surface. This is a fast operation since no data is copied.</p>
|
||||
<p>This can only work on 32-bit Surfaces with a per-pixel alpha value.</p>
|
||||
<p>The Surface this references will remain locked for the lifetime of the array,
|
||||
since the array generated by this function shares memory with the surface.
|
||||
See the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.array_red">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">array_red</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.array_red" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy red pixels into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">array_red(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Copy the pixel red values from a Surface into a 2D array. This will work
|
||||
for any type of Surface format.</p>
|
||||
<p>This function will temporarily lock the Surface as pixels are copied (see
|
||||
the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method).</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.pixels_red">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">pixels_red</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.pixels_red" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Reference pixel red into a 2d array.</span></div>
|
||||
<div class="line"><span class="signature">pixels_red (Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Create a new 2D array that directly references the red values in a Surface.
|
||||
Any changes to the array will affect the pixels in the Surface. This is a
|
||||
fast operation since no data is copied.</p>
|
||||
<p>This can only work on 24-bit or 32-bit Surfaces.</p>
|
||||
<p>The Surface this references will remain locked for the lifetime of the array,
|
||||
since the array generated by this function shares memory with the surface.
|
||||
See the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.array_green">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">array_green</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.array_green" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy green pixels into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">array_green(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Copy the pixel green values from a Surface into a 2D array. This will work
|
||||
for any type of Surface format.</p>
|
||||
<p>This function will temporarily lock the Surface as pixels are copied (see
|
||||
the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method).</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.pixels_green">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">pixels_green</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.pixels_green" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Reference pixel green into a 2d array.</span></div>
|
||||
<div class="line"><span class="signature">pixels_green (Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Create a new 2D array that directly references the green values in a
|
||||
Surface. Any changes to the array will affect the pixels in the Surface.
|
||||
This is a fast operation since no data is copied.</p>
|
||||
<p>This can only work on 24-bit or 32-bit Surfaces.</p>
|
||||
<p>The Surface this references will remain locked for the lifetime of the array,
|
||||
since the array generated by this function shares memory with the surface.
|
||||
See the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.array_blue">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">array_blue</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.array_blue" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy blue pixels into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">array_blue(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Copy the pixel blue values from a Surface into a 2D array. This will work
|
||||
for any type of Surface format.</p>
|
||||
<p>This function will temporarily lock the Surface as pixels are copied (see
|
||||
the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method).</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.2.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.pixels_blue">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">pixels_blue</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.pixels_blue" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Reference pixel blue into a 2d array.</span></div>
|
||||
<div class="line"><span class="signature">pixels_blue (Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Create a new 2D array that directly references the blue values in a Surface.
|
||||
Any changes to the array will affect the pixels in the Surface. This is a
|
||||
fast operation since no data is copied.</p>
|
||||
<p>This can only work on 24-bit or 32-bit Surfaces.</p>
|
||||
<p>The Surface this references will remain locked for the lifetime of the array,
|
||||
since the array generated by this function shares memory with the surface.
|
||||
See the <a class="tooltip reference internal" href="surface.html#pygame.Surface.lock" title=""><code class="xref py py-meth docutils literal notranslate"><span class="pre">pygame.Surface.lock()</span></code><span class="tooltip-content">lock the Surface memory for pixel access</span></a> - lock the Surface memory for pixel
|
||||
access method.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.array_colorkey">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">array_colorkey</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.array_colorkey" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy the colorkey values into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">array_colorkey(Surface) -> array</span></div>
|
||||
</div>
|
||||
<p>Create a new array with the colorkey transparency value from each pixel. If
|
||||
the pixel matches the colorkey it will be fully transparent; otherwise it
|
||||
will be fully opaque.</p>
|
||||
<p>This will work on any type of Surface format. If the image has no colorkey a
|
||||
solid opaque array will be returned.</p>
|
||||
<p>This function will temporarily lock the Surface as pixels are copied.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.make_surface">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">make_surface</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.make_surface" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Copy an array to a new surface</span></div>
|
||||
<div class="line"><span class="signature">make_surface(array) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Create a new Surface that best resembles the data and format on the array.
|
||||
The array can be 2D or 3D with any sized integer values. Function
|
||||
make_surface uses the array struct interface to acquire array properties,
|
||||
so is not limited to just NumPy arrays. See <a class="tooltip reference internal" href="pixelcopy.html#module-pygame.pixelcopy" title=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.pixelcopy</span></code><span class="tooltip-content">pygame module for general pixel array copying</span></a>.</p>
|
||||
<p>New in pygame 1.9.2: array struct interface support.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.blit_array">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">blit_array</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.blit_array" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Blit directly from a array values</span></div>
|
||||
<div class="line"><span class="signature">blit_array(Surface, array) -> None</span></div>
|
||||
</div>
|
||||
<p>Directly copy values from an array into a Surface. This is faster than
|
||||
converting the array into a Surface and blitting. The array must be the same
|
||||
dimensions as the Surface and will completely replace all pixel values. Only
|
||||
integer, ASCII character and record arrays are accepted.</p>
|
||||
<p>This function will temporarily lock the Surface as the new values are
|
||||
copied.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.map_array">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">map_array</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.map_array" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Map a 3d array into a 2d array</span></div>
|
||||
<div class="line"><span class="signature">map_array(Surface, array3d) -> array2d</span></div>
|
||||
</div>
|
||||
<p>Convert a 3D array into a 2D array. This will use the given Surface format
|
||||
to control the conversion. Palette surface formats are supported for NumPy
|
||||
arrays.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.use_arraytype">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">use_arraytype</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.use_arraytype" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Sets the array system to be used for surface arrays</span></div>
|
||||
<div class="line"><span class="signature">use_arraytype (arraytype) -> None</span></div>
|
||||
</div>
|
||||
<p>DEPRECATED: Uses the requested array type for the module functions.
|
||||
The only supported arraytype is <code class="docutils literal notranslate"><span class="pre">'numpy'</span></code>. Other values will raise
|
||||
ValueError. Using this function will raise a <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.get_arraytype">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">get_arraytype</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.get_arraytype" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the currently active array type.</span></div>
|
||||
<div class="line"><span class="signature">get_arraytype () -> str</span></div>
|
||||
</div>
|
||||
<p>DEPRECATED: Returns the currently active array type. This will be a value of the
|
||||
<code class="docutils literal notranslate"><span class="pre">get_arraytypes()</span></code> tuple and indicates which type of array module is used
|
||||
for the array creation. Using this function will raise a <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code>.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.surfarray.get_arraytypes">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.surfarray.</span></span><span class="sig-name descname"><span class="pre">get_arraytypes</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.surfarray.get_arraytypes" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Gets the array system types currently supported.</span></div>
|
||||
<div class="line"><span class="signature">get_arraytypes () -> tuple</span></div>
|
||||
</div>
|
||||
<p>DEPRECATED: Checks, which array systems are available and returns them as a tuple of
|
||||
strings. The values of the tuple can be used directly in the
|
||||
<a class="tooltip reference internal" href="#pygame.surfarray.use_arraytype" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.surfarray.use_arraytype()</span></code><span class="tooltip-content">Sets the array system to be used for surface arrays</span></a> () method. If no supported array
|
||||
system could be found, None will be returned. Using this function will raise a
|
||||
<code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code>.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/surfarray.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="tests.html" title="pygame.tests"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="surface.html" title="pygame.Surface"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.surfarray</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,232 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.tests — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.time" href="time.html" />
|
||||
<link rel="prev" title="pygame.surfarray" href="surfarray.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.tests">
|
||||
<span id="pygame-tests"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.tests</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Pygame unit test suite package</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="tests.html#pygame.tests.run">pygame.tests.run</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>Run the pygame unit test suite</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>A quick way to run the test suite package from the command line is to import
|
||||
the go submodule with the Python -m option:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pygame</span><span class="o">.</span><span class="n">tests</span> <span class="p">[</span><span class="o"><</span><span class="n">test</span> <span class="n">options</span><span class="o">></span><span class="p">]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Command line option --help displays a usage message. Available options
|
||||
correspond to the <a class="tooltip reference internal" href="#pygame.tests.run" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.tests.run()</span></code><span class="tooltip-content">Run the pygame unit test suite</span></a> arguments.</p>
|
||||
<p>The xxxx_test submodules of the tests package are unit test suites for
|
||||
individual parts of pygame. Each can also be run as a main program. This is
|
||||
useful if the test, such as cdrom_test, is interactive.</p>
|
||||
<p>For pygame development the test suite can be run from a pygame distribution
|
||||
root directory. Program <code class="docutils literal notranslate"><span class="pre">run_tests.py</span></code> is provided for convenience, though
|
||||
test/go.py can be run directly.</p>
|
||||
<p>Module level tags control which modules are included in a unit test run. Tags
|
||||
are assigned to a unit test module with a corresponding <name>_tags.py module.
|
||||
The tags module has the global __tags__, a list of tag names. For example,
|
||||
<code class="docutils literal notranslate"><span class="pre">cdrom_test.py</span></code> has a tag file <code class="docutils literal notranslate"><span class="pre">cdrom_tags.py</span></code> containing a tags list that
|
||||
has the 'interactive' string. The 'interactive' tag indicates <code class="docutils literal notranslate"><span class="pre">cdrom_test.py</span></code>
|
||||
expects user input. It is excluded from a <code class="docutils literal notranslate"><span class="pre">run_tests.py</span></code> or
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.tests.go</span></code> run. Two other tags that are excluded are 'ignore' and
|
||||
'subprocess_ignore'. These two tags indicate unit tests that will not run on a
|
||||
particular platform, or for which no corresponding pygame module is available.
|
||||
The test runner will list each excluded module along with the tag responsible.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.tests.run">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.tests.</span></span><span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.tests.run" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">Run the pygame unit test suite</span></div>
|
||||
<div class="line"><span class="signature">run(*args, **kwds) -> tuple</span></div>
|
||||
</div>
|
||||
<p>Positional arguments (optional):</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">The</span> <span class="n">names</span> <span class="n">of</span> <span class="n">tests</span> <span class="n">to</span> <span class="n">include</span><span class="o">.</span> <span class="n">If</span> <span class="n">omitted</span> <span class="n">then</span> <span class="nb">all</span> <span class="n">tests</span> <span class="n">are</span> <span class="n">run</span><span class="o">.</span> <span class="n">Test</span> <span class="n">names</span>
|
||||
<span class="n">need</span> <span class="ow">not</span> <span class="n">include</span> <span class="n">the</span> <span class="n">trailing</span> <span class="s1">'_test'</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Keyword arguments:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">incomplete</span> <span class="o">-</span> <span class="n">fail</span> <span class="n">incomplete</span> <span class="n">tests</span> <span class="p">(</span><span class="n">default</span> <span class="kc">False</span><span class="p">)</span>
|
||||
<span class="n">nosubprocess</span> <span class="o">-</span> <span class="n">run</span> <span class="nb">all</span> <span class="n">test</span> <span class="n">suites</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">current</span> <span class="n">process</span>
|
||||
<span class="p">(</span><span class="n">default</span> <span class="kc">False</span><span class="p">,</span> <span class="n">use</span> <span class="n">separate</span> <span class="n">subprocesses</span><span class="p">)</span>
|
||||
<span class="n">dump</span> <span class="o">-</span> <span class="n">dump</span> <span class="n">failures</span><span class="o">/</span><span class="n">errors</span> <span class="k">as</span> <span class="nb">dict</span> <span class="n">ready</span> <span class="n">to</span> <span class="nb">eval</span> <span class="p">(</span><span class="n">default</span> <span class="kc">False</span><span class="p">)</span>
|
||||
<span class="n">file</span> <span class="o">-</span> <span class="k">if</span> <span class="n">provided</span><span class="p">,</span> <span class="n">the</span> <span class="n">name</span> <span class="n">of</span> <span class="n">a</span> <span class="n">file</span> <span class="n">into</span> <span class="n">which</span> <span class="n">to</span> <span class="n">dump</span> <span class="n">failures</span><span class="o">/</span><span class="n">errors</span>
|
||||
<span class="n">timings</span> <span class="o">-</span> <span class="k">if</span> <span class="n">provided</span><span class="p">,</span> <span class="n">the</span> <span class="n">number</span> <span class="n">of</span> <span class="n">times</span> <span class="n">to</span> <span class="n">run</span> <span class="n">each</span> <span class="n">individual</span> <span class="n">test</span> <span class="n">to</span>
|
||||
<span class="n">get</span> <span class="n">an</span> <span class="n">average</span> <span class="n">run</span> <span class="n">time</span> <span class="p">(</span><span class="n">default</span> <span class="ow">is</span> <span class="n">run</span> <span class="n">each</span> <span class="n">test</span> <span class="n">once</span><span class="p">)</span>
|
||||
<span class="n">exclude</span> <span class="o">-</span> <span class="n">A</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">TAG</span> <span class="n">names</span> <span class="n">to</span> <span class="n">exclude</span> <span class="kn">from</span> <span class="nn">the</span> <span class="n">run</span>
|
||||
<span class="n">show_output</span> <span class="o">-</span> <span class="n">show</span> <span class="n">silenced</span> <span class="n">stderr</span><span class="o">/</span><span class="n">stdout</span> <span class="n">on</span> <span class="n">errors</span> <span class="p">(</span><span class="n">default</span> <span class="kc">False</span><span class="p">)</span>
|
||||
<span class="nb">all</span> <span class="o">-</span> <span class="n">dump</span> <span class="nb">all</span> <span class="n">results</span><span class="p">,</span> <span class="ow">not</span> <span class="n">just</span> <span class="n">errors</span> <span class="p">(</span><span class="n">default</span> <span class="kc">False</span><span class="p">)</span>
|
||||
<span class="n">randomize</span> <span class="o">-</span> <span class="n">randomize</span> <span class="n">order</span> <span class="n">of</span> <span class="n">tests</span> <span class="p">(</span><span class="n">default</span> <span class="kc">False</span><span class="p">)</span>
|
||||
<span class="n">seed</span> <span class="o">-</span> <span class="k">if</span> <span class="n">provided</span><span class="p">,</span> <span class="n">a</span> <span class="n">seed</span> <span class="n">randomizer</span> <span class="n">integer</span>
|
||||
<span class="n">multi_thread</span> <span class="o">-</span> <span class="k">if</span> <span class="n">provided</span><span class="p">,</span> <span class="n">the</span> <span class="n">number</span> <span class="n">of</span> <span class="n">THREADS</span> <span class="ow">in</span> <span class="n">which</span> <span class="n">to</span> <span class="n">run</span>
|
||||
<span class="n">subprocessed</span> <span class="n">tests</span>
|
||||
<span class="n">time_out</span> <span class="o">-</span> <span class="k">if</span> <span class="n">subprocess</span> <span class="ow">is</span> <span class="kc">True</span> <span class="n">then</span> <span class="n">the</span> <span class="n">time</span> <span class="n">limit</span> <span class="ow">in</span> <span class="n">seconds</span> <span class="n">before</span>
|
||||
<span class="n">killing</span> <span class="n">a</span> <span class="n">test</span> <span class="p">(</span><span class="n">default</span> <span class="mi">30</span><span class="p">)</span>
|
||||
<span class="n">fake</span> <span class="o">-</span> <span class="k">if</span> <span class="n">provided</span><span class="p">,</span> <span class="n">the</span> <span class="n">name</span> <span class="n">of</span> <span class="n">the</span> <span class="n">fake</span> <span class="n">tests</span> <span class="n">package</span> <span class="ow">in</span> <span class="n">the</span>
|
||||
<span class="n">run_tests__tests</span> <span class="n">subpackage</span> <span class="n">to</span> <span class="n">run</span> <span class="n">instead</span> <span class="n">of</span> <span class="n">the</span> <span class="n">normal</span>
|
||||
<span class="n">pygame</span> <span class="n">tests</span>
|
||||
<span class="n">python</span> <span class="o">-</span> <span class="n">the</span> <span class="n">path</span> <span class="n">to</span> <span class="n">a</span> <span class="n">python</span> <span class="n">executable</span> <span class="n">to</span> <span class="n">run</span> <span class="n">subprocessed</span> <span class="n">tests</span>
|
||||
<span class="p">(</span><span class="n">default</span> <span class="n">sys</span><span class="o">.</span><span class="n">executable</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Return value:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">A</span> <span class="nb">tuple</span> <span class="n">of</span> <span class="n">total</span> <span class="n">number</span> <span class="n">of</span> <span class="n">tests</span> <span class="n">run</span><span class="p">,</span> <span class="n">dictionary</span> <span class="n">of</span> <span class="n">error</span> <span class="n">information</span><span class="o">.</span>
|
||||
<span class="n">The</span> <span class="n">dictionary</span> <span class="ow">is</span> <span class="n">empty</span> <span class="k">if</span> <span class="n">no</span> <span class="n">errors</span> <span class="n">were</span> <span class="n">recorded</span><span class="o">.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>By default individual test modules are run in separate subprocesses. This
|
||||
recreates normal pygame usage where <code class="docutils literal notranslate"><span class="pre">pygame.init()</span></code> and <code class="docutils literal notranslate"><span class="pre">pygame.quit()</span></code>
|
||||
are called only once per program execution, and avoids unfortunate
|
||||
interactions between test modules. Also, a time limit is placed on test
|
||||
execution, so frozen tests are killed when their time allotment expired. Use
|
||||
the single process option if threading is not working properly or if tests
|
||||
are taking too long. It is not guaranteed that all tests will pass in single
|
||||
process mode.</p>
|
||||
<p>Tests are run in a randomized order if the randomize argument is True or a
|
||||
seed argument is provided. If no seed integer is provided then the system
|
||||
time is used.</p>
|
||||
<p>Individual test modules may have a __tags__ attribute, a list of tag strings
|
||||
used to selectively omit modules from a run. By default only 'interactive'
|
||||
modules such as cdrom_test are ignored. An interactive module must be run
|
||||
from the console as a Python program.</p>
|
||||
<p>This function can only be called once per Python session. It is not
|
||||
reentrant.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/tests.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="time.html" title="pygame.time"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="surfarray.html" title="pygame.surfarray"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.tests</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,356 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.time — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame._sdl2.touch" href="touch.html" />
|
||||
<link rel="prev" title="pygame.tests" href="tests.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.time">
|
||||
<span id="pygame-time"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.time</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module for monitoring time</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.get_ticks">pygame.time.get_ticks</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the time in milliseconds</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.wait">pygame.time.wait</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>pause the program for an amount of time</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.delay">pygame.time.delay</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>pause the program for an amount of time</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.set_timer">pygame.time.set_timer</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>repeatedly create an event on the event queue</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.Clock">pygame.time.Clock</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>create an object to help track time</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Times in pygame are represented in milliseconds (1/1000 seconds). Most
|
||||
platforms have a limited time resolution of around 10 milliseconds. This
|
||||
resolution, in milliseconds, is given in the <code class="docutils literal notranslate"><span class="pre">TIMER_RESOLUTION</span></code> constant.</p>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.get_ticks">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.time.</span></span><span class="sig-name descname"><span class="pre">get_ticks</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.get_ticks" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the time in milliseconds</span></div>
|
||||
<div class="line"><span class="signature">get_ticks() -> milliseconds</span></div>
|
||||
</div>
|
||||
<p>Return the number of milliseconds since <code class="docutils literal notranslate"><span class="pre">pygame.init()</span></code> was called. Before
|
||||
pygame is initialized this will always be 0.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.wait">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.time.</span></span><span class="sig-name descname"><span class="pre">wait</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.wait" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pause the program for an amount of time</span></div>
|
||||
<div class="line"><span class="signature">wait(milliseconds) -> time</span></div>
|
||||
</div>
|
||||
<p>Will pause for a given number of milliseconds. This function sleeps the
|
||||
process to share the processor with other programs. A program that waits for
|
||||
even a few milliseconds will consume very little processor time. It is
|
||||
slightly less accurate than the <code class="docutils literal notranslate"><span class="pre">pygame.time.delay()</span></code> function.</p>
|
||||
<p>This returns the actual number of milliseconds used.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.delay">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.time.</span></span><span class="sig-name descname"><span class="pre">delay</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.delay" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pause the program for an amount of time</span></div>
|
||||
<div class="line"><span class="signature">delay(milliseconds) -> time</span></div>
|
||||
</div>
|
||||
<p>Will pause for a given number of milliseconds. This function will use the
|
||||
processor (rather than sleeping) in order to make the delay more accurate
|
||||
than <code class="docutils literal notranslate"><span class="pre">pygame.time.wait()</span></code>.</p>
|
||||
<p>This returns the actual number of milliseconds used.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.set_timer">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.time.</span></span><span class="sig-name descname"><span class="pre">set_timer</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.set_timer" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">repeatedly create an event on the event queue</span></div>
|
||||
<div class="line"><span class="signature">set_timer(event, millis) -> None</span></div>
|
||||
<div class="line"><span class="signature">set_timer(event, millis, loops=0) -> None</span></div>
|
||||
</div>
|
||||
<p>Set an event to appear on the event queue every given number of milliseconds.
|
||||
The first event will not appear until the amount of time has passed.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">event</span></code> attribute can be a <code class="docutils literal notranslate"><span class="pre">pygame.event.Event</span></code> object or an integer
|
||||
type that denotes an event.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">loops</span></code> is an integer that denotes the number of events posted. If 0 (default)
|
||||
then the events will keep getting posted, unless explicitly stopped.</p>
|
||||
<p>To disable the timer for such an event, call the function again with the same
|
||||
event argument with <code class="docutils literal notranslate"><span class="pre">millis</span></code> argument set to 0.</p>
|
||||
<p>It is also worth mentioning that a particular event type can only be put on a
|
||||
timer once. In other words, there cannot be two timers for the same event type.
|
||||
Setting an event timer for a particular event discards the old one for that
|
||||
event type.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">loops</span></code> replaces the <code class="docutils literal notranslate"><span class="pre">once</span></code> argument, and this does not break backward
|
||||
compatibility</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.0.dev3: </span>once argument added.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.1: </span>event argument supports <code class="docutils literal notranslate"><span class="pre">pygame.event.Event</span></code> object</p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.0.1: </span>added loops argument to replace once argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py class definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.Clock">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.time.</span></span><span class="sig-name descname"><span class="pre">Clock</span></span><a class="headerlink" href="#pygame.time.Clock" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">create an object to help track time</span></div>
|
||||
<div class="line"><span class="signature">Clock() -> Clock</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.Clock.tick">pygame.time.Clock.tick</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>update the clock</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.Clock.tick_busy_loop">pygame.time.Clock.tick_busy_loop</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>update the clock</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.Clock.get_time">pygame.time.Clock.get_time</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>time used in the previous tick</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.Clock.get_rawtime">pygame.time.Clock.get_rawtime</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>actual time used in the previous tick</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="time.html#pygame.time.Clock.get_fps">pygame.time.Clock.get_fps</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>compute the clock framerate</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Creates a new Clock object that can be used to track an amount of time. The
|
||||
clock also provides several functions to help control a game's framerate.</p>
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.Clock.tick">
|
||||
<span class="sig-name descname"><span class="pre">tick</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.Clock.tick" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">update the clock</span></div>
|
||||
<div class="line"><span class="signature">tick(framerate=0) -> milliseconds</span></div>
|
||||
</div>
|
||||
<p>This method should be called once per frame. It will compute how many
|
||||
milliseconds have passed since the previous call.</p>
|
||||
<p>If you pass the optional framerate argument the function will delay to
|
||||
keep the game running slower than the given ticks per second. This can be
|
||||
used to help limit the runtime speed of a game. By calling
|
||||
<code class="docutils literal notranslate"><span class="pre">Clock.tick(40)</span></code> once per frame, the program will never run at more
|
||||
than 40 frames per second.</p>
|
||||
<p>Note that this function uses SDL_Delay function which is not accurate on
|
||||
every platform, but does not use much CPU. Use tick_busy_loop if you want
|
||||
an accurate timer, and don't mind chewing CPU.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.Clock.tick_busy_loop">
|
||||
<span class="sig-name descname"><span class="pre">tick_busy_loop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.Clock.tick_busy_loop" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">update the clock</span></div>
|
||||
<div class="line"><span class="signature">tick_busy_loop(framerate=0) -> milliseconds</span></div>
|
||||
</div>
|
||||
<p>This method should be called once per frame. It will compute how many
|
||||
milliseconds have passed since the previous call.</p>
|
||||
<p>If you pass the optional framerate argument the function will delay to
|
||||
keep the game running slower than the given ticks per second. This can be
|
||||
used to help limit the runtime speed of a game. By calling
|
||||
<code class="docutils literal notranslate"><span class="pre">Clock.tick_busy_loop(40)</span></code> once per frame, the program will never run at
|
||||
more than 40 frames per second.</p>
|
||||
<p>Note that this function uses <a class="tooltip reference internal" href="#pygame.time.delay" title=""><code class="xref py py-func docutils literal notranslate"><span class="pre">pygame.time.delay()</span></code><span class="tooltip-content">pause the program for an amount of time</span></a>, which uses lots
|
||||
of CPU in a busy loop to make sure that timing is more accurate.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.Clock.get_time">
|
||||
<span class="sig-name descname"><span class="pre">get_time</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.Clock.get_time" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">time used in the previous tick</span></div>
|
||||
<div class="line"><span class="signature">get_time() -> milliseconds</span></div>
|
||||
</div>
|
||||
<p>The number of milliseconds that passed between the previous two calls to
|
||||
<code class="docutils literal notranslate"><span class="pre">Clock.tick()</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.Clock.get_rawtime">
|
||||
<span class="sig-name descname"><span class="pre">get_rawtime</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.Clock.get_rawtime" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">actual time used in the previous tick</span></div>
|
||||
<div class="line"><span class="signature">get_rawtime() -> milliseconds</span></div>
|
||||
</div>
|
||||
<p>Similar to <code class="docutils literal notranslate"><span class="pre">Clock.get_time()</span></code>, but does not include any time used
|
||||
while <code class="docutils literal notranslate"><span class="pre">Clock.tick()</span></code> was delaying to limit the framerate.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method definition">
|
||||
<dt class="sig sig-object py title" id="pygame.time.Clock.get_fps">
|
||||
<span class="sig-name descname"><span class="pre">get_fps</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.time.Clock.get_fps" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">compute the clock framerate</span></div>
|
||||
<div class="line"><span class="signature">get_fps() -> float</span></div>
|
||||
</div>
|
||||
<p>Compute your game's framerate (in frames per second). It is computed by
|
||||
averaging the last ten calls to <code class="docutils literal notranslate"><span class="pre">Clock.tick()</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/time.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="touch.html" title="pygame._sdl2.touch"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="tests.html" title="pygame.tests"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.time</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,231 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame._sdl2.touch — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="pygame.transform" href="transform.html" />
|
||||
<link rel="prev" title="pygame.time" href="time.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame._sdl2.touch">
|
||||
<span id="pygame-sdl2-touch"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame._sdl2.touch</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module to work with touch input</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="touch.html#pygame._sdl2.touch.get_num_devices">pygame._sdl2.touch.get_num_devices</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the number of touch devices</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="touch.html#pygame._sdl2.touch.get_device">pygame._sdl2.touch.get_device</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get the a touch device id for a given index</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="touch.html#pygame._sdl2.touch.get_num_fingers">pygame._sdl2.touch.get_num_fingers</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>the number of active fingers for a given touch device</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="touch.html#pygame._sdl2.touch.get_finger">pygame._sdl2.touch.get_finger</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>get information about an active finger</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2: </span>This module requires SDL2.</p>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.touch.get_num_devices">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.touch.</span></span><span class="sig-name descname"><span class="pre">get_num_devices</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.touch.get_num_devices" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the number of touch devices</span></div>
|
||||
<div class="line"><span class="signature">get_num_devices() -> int</span></div>
|
||||
</div>
|
||||
<p>Return the number of available touch devices.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.touch.get_device">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.touch.</span></span><span class="sig-name descname"><span class="pre">get_device</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.touch.get_device" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get the a touch device id for a given index</span></div>
|
||||
<div class="line"><span class="signature">get_device(index) -> touchid</span></div>
|
||||
</div>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p><strong>index</strong> (<em>int</em>) -- This number is at least 0 and less than the
|
||||
<a class="reference internal" href="#pygame._sdl2.touch.get_num_devices" title="pygame._sdl2.touch.get_num_devices"><code class="xref py py-func docutils literal notranslate"><span class="pre">number</span> <span class="pre">of</span> <span class="pre">devices</span></code></a>.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<p>Return an integer id associated with the given <code class="docutils literal notranslate"><span class="pre">index</span></code>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.touch.get_num_fingers">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.touch.</span></span><span class="sig-name descname"><span class="pre">get_num_fingers</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.touch.get_num_fingers" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">the number of active fingers for a given touch device</span></div>
|
||||
<div class="line"><span class="signature">get_num_fingers(touchid) -> int</span></div>
|
||||
</div>
|
||||
<p>Return the number of fingers active for the touch device
|
||||
whose id is <cite>touchid</cite>.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame._sdl2.touch.get_finger">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame._sdl2.touch.</span></span><span class="sig-name descname"><span class="pre">get_finger</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame._sdl2.touch.get_finger" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">get information about an active finger</span></div>
|
||||
<div class="line"><span class="signature">get_finger(touchid, index) -> int</span></div>
|
||||
</div>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>touchid</strong> (<em>int</em>) -- The touch device id.</p></li>
|
||||
<li><p><strong>index</strong> (<em>int</em>) -- The index of the finger to return
|
||||
information about, between 0 and the
|
||||
<a class="reference internal" href="#pygame._sdl2.touch.get_num_fingers" title="pygame._sdl2.touch.get_num_fingers"><code class="xref py py-func docutils literal notranslate"><span class="pre">number</span> <span class="pre">of</span> <span class="pre">active</span> <span class="pre">fingers</span></code></a>.</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<p>Return a dict for the finger <code class="docutils literal notranslate"><span class="pre">index</span></code> active on <code class="docutils literal notranslate"><span class="pre">touchid</span></code>.
|
||||
The dict contains these keys:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">id</span> <span class="n">the</span> <span class="nb">id</span> <span class="n">of</span> <span class="n">the</span> <span class="n">finger</span> <span class="p">(</span><span class="n">an</span> <span class="n">integer</span><span class="p">)</span><span class="o">.</span>
|
||||
<span class="n">x</span> <span class="n">the</span> <span class="n">normalized</span> <span class="n">x</span> <span class="n">position</span> <span class="n">of</span> <span class="n">the</span> <span class="n">finger</span><span class="p">,</span> <span class="n">between</span> <span class="mi">0</span> <span class="ow">and</span> <span class="mf">1.</span>
|
||||
<span class="n">y</span> <span class="n">the</span> <span class="n">normalized</span> <span class="n">y</span> <span class="n">position</span> <span class="n">of</span> <span class="n">the</span> <span class="n">finger</span><span class="p">,</span> <span class="n">between</span> <span class="mi">0</span> <span class="ow">and</span> <span class="mf">1.</span>
|
||||
<span class="n">pressure</span> <span class="n">the</span> <span class="n">amount</span> <span class="n">of</span> <span class="n">pressure</span> <span class="n">applied</span> <span class="n">by</span> <span class="n">the</span> <span class="n">finger</span><span class="p">,</span> <span class="n">between</span> <span class="mi">0</span> <span class="ow">and</span> <span class="mf">1.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/touch.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="transform.html" title="pygame.transform"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="time.html" title="pygame.time"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame._sdl2.touch</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,598 @@
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
|
||||
<title>pygame.transform — pygame v2.5.0 documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
|
||||
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
|
||||
<script src="../_static/doctools.js"></script>
|
||||
<script src="../_static/sphinx_highlight.js"></script>
|
||||
<link rel="icon" href="../_static/pygame.ico"/>
|
||||
<link rel="index" title="Index" href="../genindex.html" />
|
||||
<link rel="search" title="Search" href="../search.html" />
|
||||
<link rel="next" title="Pygame Tutorials - Camera Module Introduction" href="../tut/CameraIntro.html" />
|
||||
<link rel="prev" title="pygame._sdl2.touch" href="touch.html" />
|
||||
</head><body>
|
||||
|
||||
<div class="document">
|
||||
|
||||
<div class="header">
|
||||
<div class="flex-container">
|
||||
<div class="logo">
|
||||
<a href="https://www.pygame.org/">
|
||||
<img src="../_static/pygame_tiny.png"/>
|
||||
</a>
|
||||
<h5>pygame documentation</h5>
|
||||
</div>
|
||||
<div class="pagelinks">
|
||||
<div class="top">
|
||||
<a href="https://www.pygame.org/">Pygame Home</a> ||
|
||||
<a href="../index.html">Help Contents</a> ||
|
||||
<a href="../genindex.html">Reference Index</a>
|
||||
|
||||
<form action="../search.html" method="get" style="display:inline;float:right;">
|
||||
<input name="q" value="" type="text">
|
||||
<input value="search" type="submit">
|
||||
</form>
|
||||
</div>
|
||||
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
|
||||
<p class="bottom"><b>Most useful stuff</b>:
|
||||
<a href="color.html">Color</a> |
|
||||
<a href="display.html">display</a> |
|
||||
<a href="draw.html">draw</a> |
|
||||
<a href="event.html">event</a> |
|
||||
<a href="font.html">font</a> |
|
||||
<a href="image.html">image</a> |
|
||||
<a href="key.html">key</a> |
|
||||
<a href="locals.html">locals</a> |
|
||||
<a href="mixer.html">mixer</a> |
|
||||
<a href="mouse.html">mouse</a> |
|
||||
<a href="rect.html">Rect</a> |
|
||||
<a href="surface.html">Surface</a> |
|
||||
<a href="time.html">time</a> |
|
||||
<a href="music.html">music</a> |
|
||||
<a href="pygame.html">pygame</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Advanced stuff</b>:
|
||||
<a href="cursors.html">cursors</a> |
|
||||
<a href="joystick.html">joystick</a> |
|
||||
<a href="mask.html">mask</a> |
|
||||
<a href="sprite.html">sprite</a> |
|
||||
<a href="transform.html">transform</a> |
|
||||
<a href="bufferproxy.html">BufferProxy</a> |
|
||||
<a href="freetype.html">freetype</a> |
|
||||
<a href="gfxdraw.html">gfxdraw</a> |
|
||||
<a href="midi.html">midi</a> |
|
||||
<a href="pixelarray.html">PixelArray</a> |
|
||||
<a href="pixelcopy.html">pixelcopy</a> |
|
||||
<a href="sndarray.html">sndarray</a> |
|
||||
<a href="surfarray.html">surfarray</a> |
|
||||
<a href="math.html">math</a>
|
||||
</p>
|
||||
|
||||
<p class="bottom"><b>Other</b>:
|
||||
<a href="camera.html">camera</a> |
|
||||
<a href="sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
|
||||
<a href="examples.html">examples</a> |
|
||||
<a href="fastevent.html">fastevent</a> |
|
||||
<a href="scrap.html">scrap</a> |
|
||||
<a href="tests.html">tests</a> |
|
||||
<a href="touch.html">touch</a> |
|
||||
<a href="pygame.html#module-pygame.version">version</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="documentwrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<section id="module-pygame.transform">
|
||||
<span id="pygame-transform"></span><dl class="definition">
|
||||
<dt class="title module sig sig-object">
|
||||
<code class="docutils literal notranslate"><span class="pre">pygame.transform</span></code></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">pygame module to transform surfaces</span></div>
|
||||
</div>
|
||||
<table class="toc docutils align-default">
|
||||
<tbody>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.flip">pygame.transform.flip</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>flip vertically and horizontally</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.scale">pygame.transform.scale</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>resize to new resolution</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.scale_by">pygame.transform.scale_by</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>resize to new resolution, using scalar(s)</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.rotate">pygame.transform.rotate</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>rotate an image</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.rotozoom">pygame.transform.rotozoom</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>filtered scale and rotation</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.scale2x">pygame.transform.scale2x</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>specialized image doubler</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.smoothscale">pygame.transform.smoothscale</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>scale a surface to an arbitrary size smoothly</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.smoothscale_by">pygame.transform.smoothscale_by</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>resize to new resolution, using scalar(s)</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.get_smoothscale_backend">pygame.transform.get_smoothscale_backend</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>return smoothscale filter version in use: 'GENERIC', 'MMX', or 'SSE'</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.set_smoothscale_backend">pygame.transform.set_smoothscale_backend</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>set smoothscale filter version to one of: 'GENERIC', 'MMX', or 'SSE'</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.chop">pygame.transform.chop</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>gets a copy of an image with an interior area removed</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.laplacian">pygame.transform.laplacian</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>find edges in a surface</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.average_surfaces">pygame.transform.average_surfaces</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>find the average surface from many surfaces.</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.average_color">pygame.transform.average_color</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>finds the average color of a surface</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.grayscale">pygame.transform.grayscale</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>grayscale a surface</td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><div class="line"><a class="toc reference external" href="transform.html#pygame.transform.threshold">pygame.transform.threshold</a></div>
|
||||
</td>
|
||||
<td>—</td>
|
||||
<td>finds which, and how many pixels in a surface are within a threshold of a 'search_color' or a 'search_surf'.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>A Surface transform is an operation that moves or resizes the pixels. All these
|
||||
functions take a Surface to operate on and return a new Surface with the
|
||||
results.</p>
|
||||
<p>Some of the transforms are considered destructive. These means every time they
|
||||
are performed they lose pixel data. Common examples of this are resizing and
|
||||
rotating. For this reason, it is better to re-transform the original surface
|
||||
than to keep transforming an image multiple times. (For example, suppose you
|
||||
are animating a bouncing spring which expands and contracts. If you applied the
|
||||
size changes incrementally to the previous images, you would lose detail.
|
||||
Instead, always begin with the original image and scale to the desired size.)</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 2.0.2: </span>transform functions now support keyword arguments.</p>
|
||||
</div>
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.flip">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">flip</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.flip" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">flip vertically and horizontally</span></div>
|
||||
<div class="line"><span class="signature">flip(surface, flip_x, flip_y) -> Surface</span></div>
|
||||
</div>
|
||||
<p>This can flip a Surface either vertically, horizontally, or both.
|
||||
The arguments <code class="docutils literal notranslate"><span class="pre">flip_x</span></code> and <code class="docutils literal notranslate"><span class="pre">flip_y</span></code> are booleans that control whether
|
||||
to flip each axis. Flipping a Surface is non-destructive and returns a new
|
||||
Surface with the same dimensions.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.scale">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">scale</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.scale" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">resize to new resolution</span></div>
|
||||
<div class="line"><span class="signature">scale(surface, size, dest_surface=None) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Resizes the Surface to a new size, given as (width, height).
|
||||
This is a fast scale operation that does not sample the results.</p>
|
||||
<p>An optional destination surface can be used, rather than have it create a
|
||||
new one. This is quicker if you want to repeatedly scale something. However
|
||||
the destination must be the same size as the size (width, height) passed in. Also
|
||||
the destination surface must be the same format.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.scale_by">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">scale_by</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.scale_by" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">resize to new resolution, using scalar(s)</span></div>
|
||||
<div class="line"><span class="signature">scale_by(surface, factor, dest_surface=None) -> Surface</span></div>
|
||||
</div>
|
||||
<p><strong>Experimental:</strong> feature still in development available for testing and feedback. It may change.
|
||||
<a class="reference external" href="https://github.com/pygame/pygame/pull/2723">Please leave scale_by feedback with authors</a></p>
|
||||
<p>Same as <a class="reference internal" href="#pygame.transform.scale" title="pygame.transform.scale"><code class="xref py py-func docutils literal notranslate"><span class="pre">scale()</span></code></a>, but scales by some factor, rather than taking
|
||||
the new size explicitly. For example, <code class="code docutils literal notranslate"><span class="pre">transform.scale_by(surf,</span> <span class="pre">3)</span></code>
|
||||
will triple the size of the surface in both dimensions. Optionally, the
|
||||
scale factor can be a sequence of two numbers, controlling x and y scaling
|
||||
separately. For example, <code class="code docutils literal notranslate"><span class="pre">transform.scale_by(surf,</span> <span class="pre">(2,</span> <span class="pre">1))</span></code> doubles
|
||||
the image width but keeps the height the same.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.rotate">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">rotate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.rotate" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">rotate an image</span></div>
|
||||
<div class="line"><span class="signature">rotate(surface, angle) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Unfiltered counterclockwise rotation. The angle argument represents degrees
|
||||
and can be any floating point value. Negative angle amounts will rotate
|
||||
clockwise.</p>
|
||||
<p>Unless rotating by 90 degree increments, the image will be padded larger to
|
||||
hold the new size. If the image has pixel alphas, the padded area will be
|
||||
transparent. Otherwise pygame will pick a color that matches the Surface
|
||||
colorkey or the topleft pixel value.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.rotozoom">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">rotozoom</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.rotozoom" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">filtered scale and rotation</span></div>
|
||||
<div class="line"><span class="signature">rotozoom(surface, angle, scale) -> Surface</span></div>
|
||||
</div>
|
||||
<p>This is a combined scale and rotation transform. The resulting Surface will
|
||||
be a filtered 32-bit Surface. The scale argument is a floating point value
|
||||
that will be multiplied by the current resolution. The angle argument is a
|
||||
floating point value that represents the counterclockwise degrees to rotate.
|
||||
A negative rotation angle will rotate clockwise.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.scale2x">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">scale2x</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.scale2x" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">specialized image doubler</span></div>
|
||||
<div class="line"><span class="signature">scale2x(surface, dest_surface=None) -> Surface</span></div>
|
||||
</div>
|
||||
<p>This will return a new image that is double the size of the original. It
|
||||
uses the AdvanceMAME Scale2X algorithm which does a 'jaggie-less' scale of
|
||||
bitmap graphics.</p>
|
||||
<p>This really only has an effect on simple images with solid colors. On
|
||||
photographic and antialiased images it will look like a regular unfiltered
|
||||
scale.</p>
|
||||
<p>An optional destination surface can be used, rather than have it create a
|
||||
new one. This is quicker if you want to repeatedly scale something. However
|
||||
the destination must be twice the size of the source surface passed in. Also
|
||||
the destination surface must be the same format.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.smoothscale">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">smoothscale</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.smoothscale" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">scale a surface to an arbitrary size smoothly</span></div>
|
||||
<div class="line"><span class="signature">smoothscale(surface, size, dest_surface=None) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Uses one of two different algorithms for scaling each dimension of the input
|
||||
surface as required. For shrinkage, the output pixels are area averages of
|
||||
the colors they cover. For expansion, a bilinear filter is used. For the
|
||||
x86-64 and i686 architectures, optimized <code class="docutils literal notranslate"><span class="pre">MMX</span></code> routines are included and
|
||||
will run much faster than other machine types. The size is a 2 number
|
||||
sequence for (width, height). This function only works for 24-bit or 32-bit
|
||||
surfaces. An exception will be thrown if the input surface bit depth is less
|
||||
than 24.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.smoothscale_by">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">smoothscale_by</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.smoothscale_by" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">resize to new resolution, using scalar(s)</span></div>
|
||||
<div class="line"><span class="signature">smoothscale_by(surface, factor, dest_surface=None) -> Surface</span></div>
|
||||
</div>
|
||||
<p><strong>Experimental:</strong> feature still in development available for testing and feedback. It may change.
|
||||
<a class="reference external" href="https://github.com/pygame/pygame/pull/2723">Please leave smoothscale_by feedback with authors</a></p>
|
||||
<p>Same as <a class="reference internal" href="#pygame.transform.smoothscale" title="pygame.transform.smoothscale"><code class="xref py py-func docutils literal notranslate"><span class="pre">smoothscale()</span></code></a>, but scales by some factor, rather than
|
||||
taking the new size explicitly. For example,
|
||||
<code class="code docutils literal notranslate"><span class="pre">transform.smoothscale_by(surf,</span> <span class="pre">3)</span></code> will triple the size of the
|
||||
surface in both dimensions. Optionally, the scale factor can be a sequence
|
||||
of two numbers, controlling x and y scaling separately. For example,
|
||||
<code class="code docutils literal notranslate"><span class="pre">transform.smoothscale_by(surf,</span> <span class="pre">(2,</span> <span class="pre">1))</span></code> doubles the image width but
|
||||
keeps the height the same.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.3.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.get_smoothscale_backend">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">get_smoothscale_backend</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.get_smoothscale_backend" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">return smoothscale filter version in use: 'GENERIC', 'MMX', or 'SSE'</span></div>
|
||||
<div class="line"><span class="signature">get_smoothscale_backend() -> string</span></div>
|
||||
</div>
|
||||
<p>Shows whether or not smoothscale is using <code class="docutils literal notranslate"><span class="pre">MMX</span></code> or <code class="docutils literal notranslate"><span class="pre">SSE</span></code> acceleration.
|
||||
If no acceleration is available then "GENERIC" is returned. For a x86
|
||||
processor the level of acceleration to use is determined at runtime.</p>
|
||||
<p>This function is provided for pygame testing and debugging.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.set_smoothscale_backend">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">set_smoothscale_backend</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.set_smoothscale_backend" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">set smoothscale filter version to one of: 'GENERIC', 'MMX', or 'SSE'</span></div>
|
||||
<div class="line"><span class="signature">set_smoothscale_backend(backend) -> None</span></div>
|
||||
</div>
|
||||
<p>Sets smoothscale acceleration. Takes a string argument. A value of 'GENERIC'
|
||||
turns off acceleration. 'MMX' uses <code class="docutils literal notranslate"><span class="pre">MMX</span></code> instructions only. 'SSE' allows
|
||||
<code class="docutils literal notranslate"><span class="pre">SSE</span></code> extensions as well. A value error is raised if type is not
|
||||
recognized or not supported by the current processor.</p>
|
||||
<p>This function is provided for pygame testing and debugging. If smoothscale
|
||||
causes an invalid instruction error then it is a pygame/SDL bug that should
|
||||
be reported. Use this function as a temporary fix only.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.chop">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">chop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.chop" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">gets a copy of an image with an interior area removed</span></div>
|
||||
<div class="line"><span class="signature">chop(surface, rect) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Extracts a portion of an image. All vertical and horizontal pixels
|
||||
surrounding the given rectangle area are removed. The corner areas (diagonal
|
||||
to the rect) are then brought together. (The original image is not altered
|
||||
by this operation.)</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">NOTE</span></code>: If you want a "crop" that returns the part of an image within a
|
||||
rect, you can blit with a rect to a new surface or copy a subsurface.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.laplacian">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">laplacian</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.laplacian" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">find edges in a surface</span></div>
|
||||
<div class="line"><span class="signature">laplacian(surface, dest_surface=None) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Finds the edges in a surface using the laplacian algorithm.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.average_surfaces">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">average_surfaces</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.average_surfaces" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">find the average surface from many surfaces.</span></div>
|
||||
<div class="line"><span class="signature">average_surfaces(surfaces, dest_surface=None, palette_colors=1) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Takes a sequence of surfaces and returns a surface with average colors from
|
||||
each of the surfaces.</p>
|
||||
<p>palette_colors - if true we average the colors in palette, otherwise we
|
||||
average the pixel values. This is useful if the surface is actually
|
||||
greyscale colors, and not palette colors.</p>
|
||||
<p>Note, this function currently does not handle palette using surfaces
|
||||
correctly.</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.9: </span><code class="docutils literal notranslate"><span class="pre">palette_colors</span></code> argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.average_color">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">average_color</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.average_color" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">finds the average color of a surface</span></div>
|
||||
<div class="line"><span class="signature">average_color(surface, rect=None, consider_alpha=False) -> Color</span></div>
|
||||
</div>
|
||||
<p>Finds the average color of a Surface or a region of a surface specified by a
|
||||
Rect, and returns it as a Color. If consider_alpha is set to True, then alpha is
|
||||
taken into account (removing the black artifacts).</p>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 2.1.2: </span><code class="docutils literal notranslate"><span class="pre">consider_alpha</span></code> argument</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.grayscale">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">grayscale</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.grayscale" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">grayscale a surface</span></div>
|
||||
<div class="line"><span class="signature">grayscale(surface, dest_surface=None) -> Surface</span></div>
|
||||
</div>
|
||||
<p>Returns a grayscaled version of the original surface using the luminosity formula which weights red, green and blue according to their wavelengths.</p>
|
||||
<p>An optional destination surface can be passed which is faster than creating a new Surface.
|
||||
This destination surface must have the same dimensions (width, height) and depth as the source Surface.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py function definition">
|
||||
<dt class="sig sig-object py title" id="pygame.transform.threshold">
|
||||
<span class="sig-prename descclassname"><span class="pre">pygame.transform.</span></span><span class="sig-name descname"><span class="pre">threshold</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pygame.transform.threshold" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><div class="line-block">
|
||||
<div class="line"><span class="summaryline">finds which, and how many pixels in a surface are within a threshold of a 'search_color' or a 'search_surf'.</span></div>
|
||||
<div class="line"><span class="signature">threshold(dest_surface, surface, search_color, threshold=(0,0,0,0), set_color=(0,0,0,0), set_behavior=1, search_surf=None, inverse_set=False) -> num_threshold_pixels</span></div>
|
||||
</div>
|
||||
<p>This versatile function can be used for find colors in a 'surf' close to a 'search_color'
|
||||
or close to colors in a separate 'search_surf'.</p>
|
||||
<p>It can also be used to transfer pixels into a 'dest_surf' that match or don't match.</p>
|
||||
<p>By default it sets pixels in the 'dest_surf' where all of the pixels NOT within the
|
||||
threshold are changed to set_color. If inverse_set is optionally set to True,
|
||||
the pixels that ARE within the threshold are changed to set_color.</p>
|
||||
<p>If the optional 'search_surf' surface is given, it is used to threshold against
|
||||
rather than the specified 'set_color'. That is, it will find each pixel in the
|
||||
'surf' that is within the 'threshold' of the pixel at the same coordinates
|
||||
of the 'search_surf'.</p>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><ul class="simple">
|
||||
<li><p><strong>dest_surf</strong> (<a class="tooltip reference internal" href="surface.html#pygame.Surface" title=""><em>pygame.Surface</em><span class="tooltip-content">pygame object for representing images</span></a><em> or </em><em>None</em>) -- Surface we are changing. See 'set_behavior'.
|
||||
Should be None if counting (set_behavior is 0).</p></li>
|
||||
<li><p><strong>surf</strong> (<a class="tooltip reference internal" href="surface.html#pygame.Surface" title=""><em>pygame.Surface</em><span class="tooltip-content">pygame object for representing images</span></a>) -- Surface we are looking at.</p></li>
|
||||
<li><p><strong>search_color</strong> (<a class="tooltip reference internal" href="color.html#pygame.Color" title=""><em>pygame.Color</em><span class="tooltip-content">pygame object for color representations</span></a>) -- Color we are searching for.</p></li>
|
||||
<li><p><strong>threshold</strong> (<a class="tooltip reference internal" href="color.html#pygame.Color" title=""><em>pygame.Color</em><span class="tooltip-content">pygame object for color representations</span></a>) -- Within this distance from search_color (or search_surf).
|
||||
You can use a threshold of (r,g,b,a) where the r,g,b can have different
|
||||
thresholds. So you could use an r threshold of 40 and a blue threshold of 2
|
||||
if you like.</p></li>
|
||||
<li><p><strong>set_color</strong> (<a class="tooltip reference internal" href="color.html#pygame.Color" title=""><em>pygame.Color</em><span class="tooltip-content">pygame object for color representations</span></a><em> or </em><em>None</em>) -- Color we set in dest_surf.</p></li>
|
||||
<li><p><strong>set_behavior</strong> (<em>int</em>) -- <ul>
|
||||
<li><p>set_behavior=1 (default). Pixels in dest_surface will be changed to 'set_color'.</p></li>
|
||||
<li><p>set_behavior=0 we do not change 'dest_surf', just count. Make dest_surf=None.</p></li>
|
||||
<li><p>set_behavior=2 pixels set in 'dest_surf' will be from 'surf'.</p></li>
|
||||
</ul>
|
||||
</p></li>
|
||||
<li><p><strong>search_surf</strong> (<a class="tooltip reference internal" href="surface.html#pygame.Surface" title=""><em>pygame.Surface</em><span class="tooltip-content">pygame object for representing images</span></a><em> or </em><em>None</em>) -- <ul>
|
||||
<li><p>search_surf=None (default). Search against 'search_color' instead.</p></li>
|
||||
<li><p>search_surf=Surface. Look at the color in 'search_surf' rather than using 'search_color'.</p></li>
|
||||
</ul>
|
||||
</p></li>
|
||||
<li><p><strong>inverse_set</strong> (<em>bool</em>) -- <ul>
|
||||
<li><p>False, default. Pixels outside of threshold are changed.</p></li>
|
||||
<li><p>True, Pixels within threshold are changed.</p></li>
|
||||
</ul>
|
||||
</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
<dt class="field-even">Return type<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p>int</p>
|
||||
</dd>
|
||||
<dt class="field-odd">Returns<span class="colon">:</span></dt>
|
||||
<dd class="field-odd"><p>The number of pixels that are within the 'threshold' in 'surf'
|
||||
compared to either 'search_color' or <cite>search_surf</cite>.</p>
|
||||
</dd>
|
||||
<dt class="field-even">Examples<span class="colon">:</span></dt>
|
||||
<dd class="field-even"><p></p></dd>
|
||||
</dl>
|
||||
<p>See the threshold tests for a full of examples: <a class="reference external" href="https://github.com/pygame/pygame/blob/main/test/transform_test.py">https://github.com/pygame/pygame/blob/main/test/transform_test.py</a></p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="k">def</span> <span class="nf">test_threshold_dest_surf_not_change</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||||
<span class="w"> </span><span class="sd">"""the pixels within the threshold.</span>
|
||||
|
||||
<span class="sd"> All pixels not within threshold are changed to set_color.</span>
|
||||
<span class="sd"> So there should be none changed in this test.</span>
|
||||
<span class="sd"> """</span>
|
||||
<span class="p">(</span><span class="n">w</span><span class="p">,</span> <span class="n">h</span><span class="p">)</span> <span class="o">=</span> <span class="n">size</span> <span class="o">=</span> <span class="p">(</span><span class="mi">32</span><span class="p">,</span> <span class="mi">32</span><span class="p">)</span>
|
||||
<span class="n">threshold</span> <span class="o">=</span> <span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">20</span><span class="p">,</span> <span class="mi">20</span><span class="p">)</span>
|
||||
<span class="n">original_color</span> <span class="o">=</span> <span class="p">(</span><span class="mi">25</span><span class="p">,</span> <span class="mi">25</span><span class="p">,</span> <span class="mi">25</span><span class="p">,</span> <span class="mi">25</span><span class="p">)</span>
|
||||
<span class="n">original_dest_color</span> <span class="o">=</span> <span class="p">(</span><span class="mi">65</span><span class="p">,</span> <span class="mi">65</span><span class="p">,</span> <span class="mi">65</span><span class="p">,</span> <span class="mi">55</span><span class="p">)</span>
|
||||
<span class="n">threshold_color</span> <span class="o">=</span> <span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
|
||||
<span class="n">set_color</span> <span class="o">=</span> <span class="p">(</span><span class="mi">255</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
|
||||
|
||||
<span class="n">surf</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">Surface</span><span class="p">(</span><span class="n">size</span><span class="p">,</span> <span class="n">pygame</span><span class="o">.</span><span class="n">SRCALPHA</span><span class="p">,</span> <span class="mi">32</span><span class="p">)</span>
|
||||
<span class="n">dest_surf</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">Surface</span><span class="p">(</span><span class="n">size</span><span class="p">,</span> <span class="n">pygame</span><span class="o">.</span><span class="n">SRCALPHA</span><span class="p">,</span> <span class="mi">32</span><span class="p">)</span>
|
||||
<span class="n">search_surf</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">Surface</span><span class="p">(</span><span class="n">size</span><span class="p">,</span> <span class="n">pygame</span><span class="o">.</span><span class="n">SRCALPHA</span><span class="p">,</span> <span class="mi">32</span><span class="p">)</span>
|
||||
|
||||
<span class="n">surf</span><span class="o">.</span><span class="n">fill</span><span class="p">(</span><span class="n">original_color</span><span class="p">)</span>
|
||||
<span class="n">search_surf</span><span class="o">.</span><span class="n">fill</span><span class="p">(</span><span class="n">threshold_color</span><span class="p">)</span>
|
||||
<span class="n">dest_surf</span><span class="o">.</span><span class="n">fill</span><span class="p">(</span><span class="n">original_dest_color</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># set_behavior=1, set dest_surface from set_color.</span>
|
||||
<span class="c1"># all within threshold of third_surface, so no color is set.</span>
|
||||
|
||||
<span class="n">THRESHOLD_BEHAVIOR_FROM_SEARCH_COLOR</span> <span class="o">=</span> <span class="mi">1</span>
|
||||
<span class="n">pixels_within_threshold</span> <span class="o">=</span> <span class="n">pygame</span><span class="o">.</span><span class="n">transform</span><span class="o">.</span><span class="n">threshold</span><span class="p">(</span>
|
||||
<span class="n">dest_surface</span><span class="o">=</span><span class="n">dest_surf</span><span class="p">,</span>
|
||||
<span class="n">surface</span><span class="o">=</span><span class="n">surf</span><span class="p">,</span>
|
||||
<span class="n">search_color</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
|
||||
<span class="n">threshold</span><span class="o">=</span><span class="n">threshold</span><span class="p">,</span>
|
||||
<span class="n">set_color</span><span class="o">=</span><span class="n">set_color</span><span class="p">,</span>
|
||||
<span class="n">set_behavior</span><span class="o">=</span><span class="n">THRESHOLD_BEHAVIOR_FROM_SEARCH_COLOR</span><span class="p">,</span>
|
||||
<span class="n">search_surf</span><span class="o">=</span><span class="n">search_surf</span><span class="p">,</span>
|
||||
<span class="p">)</span>
|
||||
|
||||
<span class="c1"># # Return, of pixels within threshold is correct</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">w</span> <span class="o">*</span> <span class="n">h</span><span class="p">,</span> <span class="n">pixels_within_threshold</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># # Size of dest surface is correct</span>
|
||||
<span class="n">dest_rect</span> <span class="o">=</span> <span class="n">dest_surf</span><span class="o">.</span><span class="n">get_rect</span><span class="p">()</span>
|
||||
<span class="n">dest_size</span> <span class="o">=</span> <span class="n">dest_rect</span><span class="o">.</span><span class="n">size</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">size</span><span class="p">,</span> <span class="n">dest_size</span><span class="p">)</span>
|
||||
|
||||
<span class="c1"># The color is not the change_color specified for every pixel As all</span>
|
||||
<span class="c1"># pixels are within threshold</span>
|
||||
|
||||
<span class="k">for</span> <span class="n">pt</span> <span class="ow">in</span> <span class="n">test_utils</span><span class="o">.</span><span class="n">rect_area_pts</span><span class="p">(</span><span class="n">dest_rect</span><span class="p">):</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">assertNotEqual</span><span class="p">(</span><span class="n">dest_surf</span><span class="o">.</span><span class="n">get_at</span><span class="p">(</span><span class="n">pt</span><span class="p">),</span> <span class="n">set_color</span><span class="p">)</span>
|
||||
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">dest_surf</span><span class="o">.</span><span class="n">get_at</span><span class="p">(</span><span class="n">pt</span><span class="p">),</span> <span class="n">original_dest_color</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in pygame 1.8.</span></p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in pygame 1.9.4: </span>Fixed a lot of bugs and added keyword arguments. Test your code.</p>
|
||||
</div>
|
||||
</dd></dl>
|
||||
|
||||
</dd></dl>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<br /><br />
|
||||
<hr />
|
||||
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/ref/transform.rst" rel="nofollow">Edit on GitHub</a>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="clearer"></div>
|
||||
</div>
|
||||
<div class="related" role="navigation" aria-label="related navigation">
|
||||
<h3>Navigation</h3>
|
||||
<ul>
|
||||
<li class="right" style="margin-right: 10px">
|
||||
<a href="../genindex.html" title="General Index"
|
||||
accesskey="I">index</a></li>
|
||||
<li class="right" >
|
||||
<a href="../py-modindex.html" title="Python Module Index"
|
||||
>modules</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="../tut/CameraIntro.html" title="Pygame Tutorials - Camera Module Introduction"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="touch.html" title="pygame._sdl2.touch"
|
||||
accesskey="P">previous</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.0 documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pygame.transform</span></code></a></li>
|
||||
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
© Copyright 2000-2023, pygame developers.
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user