Anonymous avatar Anonymous committed 0bc75c9

Started documenting the OpenAL interfaces.

Comments (0)

Files changed (7)

 * add pgcompat.h to *mod.h internal headers.
 * >8 bpp surfaces with palettes - it is supported (although it might be
   pointless) by SDL and so should we.
+* add OpenMP support where useful (looped operations, etc.)
 
 * freetype: render to buffer buffer support (like new bytearray, but
   write to a buffer instead)

doc/src/examples.rst

 +------------------------------------+----------------------------------------+
 | pygame2.examples.freetype.sdlfont  | Simple freetype example                |
 +------------------------------------+----------------------------------------+
+| pygame2.examples.openal.player     | Simple OpenAL WAV file playback        |
+|                                    | example.                               |
++------------------------------------+----------------------------------------+
 | pygame2.examples.sdl.cdrom         | Demonstrates the features of the       |
 |                                    | :mod:`pygame2.sdl.cdrom` module.       |
 +------------------------------------+----------------------------------------+

doc/src/mathbase.xml

   <alias>pygame2.math</alias>
   <short>Vector math module for Pygame2</short>
   <desc>
-    TODO
+    Vector math module for Pygame2
   </desc>
   <func name="vector_from_polar">
     <call>vector_from_polar (p1, p2) -> Vector2</call>

doc/src/modules.rst

    pygame2_math.rst
    pygame2_mask.rst
    pygame2_midi.rst
+   pygame2_openal_base.rst
+   pygame2_openal_constants.rst
    pygame2_resources.rst
    pygame2_sdl.rst
    pygame2_sdl_audio.rst

doc/src/openal_constants.rst

+:mod:`pygame2.openal.constants` -- Constants for OpenAL
+=======================================================
+
+This module contains the constants used throughout the
+:mod:`pygame2.openal` module.
+
+.. module:: pygame2.openal.constants
+   :synopsis: Constants used throughout the :mod:`pygame2.openal` module.
+
+Format Constants
+----------------
+
+Those constants are used by the :meth:`pygame2.openal.Buffers.buffer_data`,
+and :meth:`pygame2.openal.CaptureDevice.get_samples` methods.
+
+.. todo::
+
+   Provide a detailled description about how the data will be streamed
+   to the sound system.
+
+
+.. data:: AL_FORMAT_MONO8
+
+   Mono (1 channel) 8-bit data.
+
+.. data:: AL_FORMAT_MONO16
+
+   Mono (1 channel) 16-bit data.
+
+.. data:: AL_FORMAT_MONO_FLOAT32
+
+   Mono (1 channel) 32-bit floating point data.
+
+.. data:: AL_FORMAT_STEREO8
+
+   Stereo (2 channel) 8-bit data.
+
+.. data:: AL_FORMAT_STEREO16
+
+   Stereo (2 channel) 16-bit data.
+
+.. data:: AL_FORMAT_STEREO_FLOAT32
+
+   Stereo (2 channel) 32-bit floating point data.
+
+.. data:: AL_FORMAT_QUAD8
+
+   4 channel (4.0 Quad) 8-bit data.
+
+.. data:: AL_FORMAT_QUAD8_LOKI
+
+   4 channel (4.0 Quad) 8-bit data.
+
+.. data:: AL_FORMAT_QUAD16
+
+   4 channel (4.0 Quad) 16-bit data.
+
+.. data:: AL_FORMAT_QUAD16_LOKI
+
+   4 channel (4.0 Quad) 16-bit data.
+
+.. data:: AL_FORMAT_QUAD32
+
+   4 channel (4.0 Quad) 32-bit data.
+
+.. data:: AL_FORMAT_51CHN8
+
+   6 channel (5.1 Surround Sound) 8-bit data.
+
+.. data:: AL_FORMAT_51CHN16
+
+   6 channel (5.1 Surround Sound) 16-bit data.
+
+.. data:: AL_FORMAT_51CHN32
+
+   6 channel (5.1 Surround Sound) 32-bit data.
+
+.. data:: AL_FORMAT_61CHN8
+
+   7 channel (6.1 Surround Sound) 8-bit data.
+
+.. data:: AL_FORMAT_61CHN16
+
+   7 channel (6.1 Surround Sound) 16-bit data.
+
+.. data:: AL_FORMAT_61CHN32
+
+   7 channel (6.1 Surround Sound) 32-bit data.
+
+.. data:: AL_FORMAT_71CHN8
+
+   8 channel (7.1 Surround Sound) 8-bit data.
+
+.. data:: AL_FORMAT_71CHN16
+
+   8 channel (7.1 Surround Sound) 16-bit data.
+
+.. data:: AL_FORMAT_71CHN32
+
+   8 channel (7.1 Surround Sound) 32-bit data.
+
+Buffer Constants
+----------------
+
+Those constants are used by the :meth:`pygame2.openal.Buffers.set_prop`
+and :meth:`pygame2.openal.Buffers.get_prop` methods.
+
+.. data:: AL_FREQUENCY
+
+   The frequency of the buffer (and its data) in Hz. The provided value
+   must be an integer.
+
+.. data:: AL_BITS
+
+   The bit depth of the buffer. The provided value must be an integer.
+
+.. data:: AL_CHANNELS
+
+   The number of channels for the buffered data. The provided value
+   must be an integer greater than 0.
+
+.. data:: AL_SIZE
+
+   The size of the buffered data in bytes.
+
+.. data:: AL_DATA
+
+   The original location the buffered data came from. This is generally
+   useless, as the original data location was probably freed after the
+   data was buffered.
+
+Source Constants
+----------------
+
+Those constants are used by the :meth:`pygame2.openal.Sources.set_prop`
+and :meth:`pygame2.openal.Sources.get_prop` methods.
+
+.. data:: AL_PITCH
+
+   The pitch multiplier. The provided value must be a positive floating
+   point value.
+
+.. data:: AL_GAIN
+
+   The source gain. The provided value should be a positive floating
+   point value.
+
+.. data:: AL_MAX_DISTANCE
+
+   Used with the Inverse Clamped Distance Model to set the distance
+   where there will no longer be any attenuation of the source. The
+   provided value must be an integer or floating point value.
+
+.. data:: AL_ROLLOFF_FACTOR
+
+   The rolloff ratge for the source. The provided value should be an
+   integer or floating point value.
+
+.. data:: AL_REFERENCE_DISTANCE
+
+   The distance under which the volume for the source would normally
+   drop by half. The provided value should be an integer or floating
+   point value.
+
+.. data:: AL_MIN_GAIN
+
+   The minimum source gain. The provided value must be a postive
+   floating point value.
+
+.. data:: AL_MAX_GAIN
+
+   The maximum source gain. The provided value must be a postive
+   floating point value.
+
+.. data:: AL_CONE_OUTER_GAIN
+
+   The gain when outside the oriented cone. The provided value must be a
+   postive floating point value.
+
+.. data:: AL_CONE_INNER_ANGLE
+
+   The gain when inside the oriented cone. The provided value must be a
+   postive floating point value.
+
+.. data:: AL_CONE_OUTER_ANGLE
+
+   The outer angle of the sound cone in degrees. The provided value must
+   be a integer or floating point value.
+
+.. data:: AL_POSITION
+
+   The X, Y, Z position of the source. The provided value must be a
+   triplet of floating point values.
+
+.. data:: AL_VELOCITY
+
+   The X, Y, Z velocity of the source. The provided value must be a
+   triplet of floating point values.
+
+.. data:: AL_DIRECTION
+
+   The X, Y, Z direction of the source. The provided value must be a
+   triplet of integer or floating point values.
+
+.. data:: AL_SOURCE_RELATIVE
+
+   Determines if the positions of the source are relative to the
+   listener. The provided value must be an integer.
+
+.. data:: AL_SOURCE_TYPE
+
+   The type of the source. This will be a value of
+
+     * AL_UNDETERMINED
+     * AL_STATIC
+     * AL_STREAMING
+
+.. data:: AL_LOOPING
+
+   Turns looping on (AL_TRUE) or off (AL_FALSE).
+
+.. data:: AL_BUFFER
+
+   The ID of the attached buffer
+
+.. data:: AL_SOURCE_STATE
+
+   The state of the source. This will be a value of
+
+     * AL_STOPPED
+     * AL_PLAYING
+     * AL_PAUSED
+
+.. data:: AL_BUFFERS_QUEUED
+
+   The number of buffers queued on this source.
+
+.. data:: AL_BUFFERS_PROCESSED
+
+   The number of buffers in the queue that have been processed.
+
+.. data:: AL_SEC_OFFSET
+
+   The source playback position, in seconds.
+
+.. data:: AL_SAMPLE_OFFSET
+
+   The source playback position, in samples.
+
+.. data:: AL_BYTE_OFFSET
+
+   The source playback position, in bytes.
+
+Listener Constants
+------------------
+
+Those constants are used by the :meth:`pygame2.openal.Listener.set_prop`
+and :meth:`pygame2.openal.Listener.get_prop` methods.
+
+.. data:: AL_GAIN
+
+   The master gain. The provided value should be a positive floating
+   point value.
+
+.. data:: AL_POSITION
+
+   The X, Y, Z position of the listener. The provided value must be a
+   triplet of floating point values.
+
+.. data:: AL_VELOCITY
+
+   The X, Y, Z velocity of the listener. The provided value must be a
+   triplet of floating point values.
+
+.. data:: AL_ORIENTATION
+
+   The orientation of the listener, expressed as "at" and "up" vectors
+   (6 elements) of floating point values.
+
+Distance Model Constants
+------------------------
+
+Those constance are used by the
+:attr:`pygame2.openal.Context.distance_model` property.
+
+.. data:: AL_INVERSE_DISTANCE
+
+   TODO
+
+.. data:: AL_INVERSE_DISTANCE_CLAMPED
+
+   TODO
+
+.. data:: AL_LINEAR_DISTANCE
+
+   TODO
+
+.. data:: AL_LINEAR_DISTANCE_CLAMPED
+
+   TODO
+
+.. data:: AL_EXPONENT_DISTANCE
+
+   TODO
+
+.. data:: AL_EXPONENT_DISTANCE_CLAMPED
+
+   TODO
+
+.. data:: AL_NONE
+
+   TODO
+
+
+.. todo::
+
+   Complete the constant descriptions.

doc/src/openalbase.xml

+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE module SYSTEM "api.dtd">
+
+<module name="pygame2.openal.base">
+  <alias>pygame2.openal</alias>
+  <short>basic OpenAL wrapper module</short>
+  <desc>
+    Basic Pygame2 OpenAL wrapper module.
+  </desc>
+
+  <class name="Buffers">
+    <constructor>Buffers () -> NotImplementedError</constructor>
+    <desc>
+      Buffers objects are used by OpenAL to buffer and provide PCM data
+      for playback, recording and manipulation.
+      
+      The Buffers object provides methods and properties to manipulate
+      certain aspects of the buffered data.
+
+      Buffers instances cannot be created directly, but are bound to a
+      :class:`Device`. To create a Buffers instance for the currently
+      active :class:`Device`, use the :meth:`Context.create_buffers`
+      method.
+    </desc>
+    <example></example>
+    <method name="buffer_data">
+      <call>buffer_data (bufnum, format, data, samplerate)</call>
+      <desc>
+        Buffers a chunk of *data* into one of the created buffers. 
+      </desc>
+      <example></example>
+    </method>
+    <attr name="buffers">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <attr name="count">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="get_prop">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="set_prop">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+  </class>
+
+  <class name="CaptureDevice">
+    <constructor>TODO</constructor>
+    <desc>None</desc>
+    <example></example>
+    <attr name="format">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <attr name="frequency">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="get_samples">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <attr name="size">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="start">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="stop">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+  </class>
+
+  <class name="Context">
+    <constructor>TODO</constructor>
+    <desc>None</desc>
+    <example></example>
+    <method name="create_buffers">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="create_sources">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <attr name="device">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="disable">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <attr name="distance_model">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <attr name="doppler_factor">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="enable">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <attr name="is_current">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="is_enabled">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <attr name="listener">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="make_current">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="process">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <attr name="speed_of_sound">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="suspend">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+  </class>
+
+  <class name="Device">
+    <constructor>TODO</constructor>
+    <desc>None</desc>
+    <example></example>
+    <attr name="extensions">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="get_enum_value">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="get_error">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="has_extension">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <attr name="name">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+  </class>
+
+  <class name="Listener">
+    <constructor>TODO</constructor>
+    <desc>None</desc>
+    <example></example>
+    <method name="get_prop">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="set_prop">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+  </class>
+
+  <class name="Sources">
+    <constructor>TODO</constructor>
+    <desc>None</desc>
+    <example></example>
+    <attr name="count">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="get_prop">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="pause">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="play">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="queue_buffers">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="rewind">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="set_prop">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <attr name="sources">
+      <desc>None</desc>
+      <example></example>
+    </attr>
+    <method name="stop">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+    <method name="unqueue_buffers">
+      <call></call>
+      <desc></desc>
+      <example></example>
+    </method>
+  </class>
+
+  <func name="al_get_string">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="get_default_capture_device_name">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="get_default_output_device_name">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="get_enum_value">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="get_error">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="init">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="is_extension_present">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="list_capture_devices">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="list_output_devices">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="quit">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+  <func name="set_current_context">
+    <call></call>
+    <desc></desc>
+    <example></example>
+  </func>
+</module>
+

doc/src/pygame2math.xml

   <alias>pygame2.math</alias>
   <short>Vector math features used by pygame2</short>
   <desc>
-    TODO
+    Vector math features used by pygame2
   </desc>
 
   <include>pygame2_math_base.rst</include>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.