- added openal.loaders module for sound loading functions

- minor documentation improvements

Author: marcusva

Makefile

@@ -56,7 +56,7 @@ docs:
 
 release: dist
 runtest:
-	@PYTHONPATH=$(PYTHONPATH) $(PYTHON) -B -m test.util.runtests
+	@PYTHONPATH=$(PYTHONPATH) $(PYTHON) -B -m openal.test.util.runtests
 
 # Do not run these in production environments! They are for testing
 # purposes only!
@@ -75,10 +75,10 @@ installall:
 	@pypy2.0 setup.py install
 
 testall:
-	@-PYTHONPATH=$(PYTHONPATH) python2.7 -B -m test.util.runtests
-	@-PYTHONPATH=$(PYTHONPATH) python3.2 -B -m test.util.runtests
-	@-PYTHONPATH=$(PYTHONPATH) python3.3 -B -m test.util.runtests
-	@-PYTHONPATH=$(PYTHONPATH) pypy2.0 -B -m test.util.runtests
+	@-PYTHONPATH=$(PYTHONPATH) python2.7 -B -m openal.test.util.runtests
+	@-PYTHONPATH=$(PYTHONPATH) python3.2 -B -m openal.test.util.runtests
+	@-PYTHONPATH=$(PYTHONPATH) python3.3 -B -m openal.test.util.runtests
+	@-PYTHONPATH=$(PYTHONPATH) pypy2.0 -B -m openal.test.util.runtests
 
 purge_installs:
 	rm -rf /usr/local/lib/python2.7/site-packages/openal*

doc/openalaudio.rst renamed to doc/audio.rst

@@ -1,8 +1,8 @@
 .. module:: openal.audio
    :synopsis: Advanced OpenAL audio module
 
-Using openalaudio
-=================
+openal.audio -  advanced sound support
+======================================
 :mod:`openal.audio` is a set of advanced, pythonic classes for 3D positional
 audio support via the OpenAL standard. It utilises :mod:`openal`, but hides all
 the :mod:`ctypes` related, sequential programming workflow from you. It is
@@ -47,7 +47,6 @@ while each of them uses its own execution context.
 
 Placing the listener
 --------------------
-
 The OpenAL standard supports 3D positional audio, so that a source of sound can
 be placed anywhere relative to the listener (the user of the application or
 some in-application avatar).
@@ -121,7 +120,6 @@ ears of you receive the noise in nearly the same way).
 
 Creating sound sources
 ----------------------
-
 A :class:`SoundSource` represents an object that can emit sounds. It can be any
 kind of object and allows you to play any sound, you put into it. In an
 application you can enable objects to emit sounds, by binding a
@@ -135,7 +133,6 @@ application you can enable objects to emit sounds, by binding a
 
 Creating and playing sounds
 ---------------------------
-
 To create and play sounds you use :class:`SoundData` objects, which contain the
 raw PCM data to be played. To play the sound, the :class:`SoundData` needs to
 be queued on a :class:`SoundSource`, which provides all the necessary
@@ -148,20 +145,160 @@ There are some helper functions, which create :class:`SoundData` objects from
 audio files. If you have a raw PCM data buffer, you can create a
 :class:`SoundData` from it directly. ::
 
-   >>> rawsound = SoundData(pcmformat, pcmbuf, size_of_buf, frequency_in_hz)
+   >>> rawsound = SoundData(pcmbuf, size_of_buf, channels, bitrate, frequency_in_hz)
 
-Queueing the loaded sound is done via the :meth:`SoundSource.queue()` or
-:meth:`SoundSource.play()` method, which appends the sound to the source for
-processing and playback. ::
+Queueing the loaded sound is done via the :meth:`SoundSource.queue()` method,
+which appends the sound to the source for processing and playback. ::
 
    >>> wavsound = load_wav_file("vroom.wav")
-   >>> source.play(wavsound)
+   >>> source.queue(wavsound)
 
 You just need to inform the :class:`SoundSink` about the :class:`SoundSource`
 afterwards, so that it knows that a new sound emitter is available. ::
 
    >>> soundsink.play(source)
    
 When you add other sounds to play to the source, they will be picked up
-automatically for playback, as long as the :class:`SoundSource` is not paused,
-stopped or ran out of something to play.
+automatically for playback, as long as the :class:`SoundSource` is not paused
+or ran out of something to play.
+
+API
+^^^
+
+.. class:: OpenALError([msg=None[, alcdevice=None]])
+
+   An OpenAL specific exception class. If a new :class:`OpenALError` is created
+   and no *msg* is provided, the message will be set a mapped value of
+   :meth:`openal.al.alGetError()`. If an :class:`openal.alc.ALCdevice` is
+   provided as *alcdevice*, :meth:`openal.alc.alcGetError()` will be used
+   instead of :meth:`openal.al.alGetError()`.
+
+.. class:: SoundData(data=None, channels=None, bitrate=None, size=None, \
+                     frequency=None, dformat=None)
+
+   The :class:`SoundData` consists of a PCM audio data buffer, the audio
+   frequency and additional format information to allow easy buffering through
+   OpenAL.
+
+   .. attribute:: channels
+
+      The channel count for the sound data.
+      
+   .. attribute:: bitrate
+   
+      The bitrate of the sound data.
+      
+   .. attribute:: size
+   
+      The buffer size in bytes.
+   
+   .. attribute:: frequency
+   
+      The sound frequency in Hz.
+      
+   .. attribute:: data
+   
+      The buffered audio data.
+      
+.. class:: SoundListener(position=[0, 0, 0], velocity=[0, 0, 0], \
+                         orientation=[0, 0, -1, 0, 1, 0])
+
+   A listener object within the 3D audio space.
+
+   .. attribute:: orientation
+   
+      The listening orientation as 6-value list. 
+   
+   .. attribute:: position
+   
+      The listener position as 3-value list.  
+
+   .. attribute:: velocity
+   
+      The movement velocity as 3-value list.
+    
+   .. attribute:: gain
+    
+      The relative sound volume (perceiptive for the listener).
+
+   .. attribute:: changed
+
+      Indicates, if an attribute has been changed.
+      
+.. class:: SoundSource(gain=1.0, pitch=1.0, position=[0, 0, 0], \
+                       velocity=[0, 0, 0])
+
+   An object within the application world, which can emit sounds.
+
+   .. attribute:: gain
+
+      The volume gain of the source.
+
+   .. attribute:: pitch
+
+      The pitch of the source.
+
+   .. attribute:: position
+
+      The (initial) position of the source as 3-value tuple in a x-y-z
+      coordinate system.
+
+   .. attribute:: velocity
+
+      The velocity of the source as 3-value tuple in a x-y-z coordinate system.
+
+   .. method:: queue(sounddata : SoundData) -> None
+
+      Adds a :class:`SoundData` audio buffer to the source's processing and
+      playback queue.
+
+.. class:: SoundSink(device=None)
+
+   Audio playback system.
+
+   The SoundSink handles audio output for sound sources. It connects to an
+   audio output device and manages the source settings, their buffer queues
+   and the playback of them.
+
+   .. attribute:: device
+
+      The used OpenAL :class:`openal.alc.ALCdevice`.
+
+   .. attribute:: context
+
+      The used :class:`openal.alc.ALCcontext`.
+
+   .. method:: activate() -> None
+
+      Activates the :class:`SoundSink`, marking its :attr:`context` as the
+      currently active one.
+
+      Subsequent OpenAL operations are done in the context of the
+      SoundSink's bindings.
+
+   .. method:: set_listener(listener : SoundListener) -> None
+
+      Sets the listener position for the :class:`SoundSink`.
+
+      .. note::
+
+         This implicitly activates the :class:`SoundSink`.
+
+   .. method:: process_source(source : SoundSource) -> None
+
+      Processes a single :class:`SoundSource`.
+
+      .. note::
+
+        This does *not* activate the :class:`SoundSink`. If another
+        :class:`SoundSink` is active, chances are good that the
+        source is processed in that :class:`SoundSink`.
+
+   .. method:: process(world, components) -> None
+
+      Processes :class:`SoundSource` components, according to their
+      :attr:`SoundSource.request`
+
+      .. note::
+
+         This implicitly activates the :class:`SoundSink`.

doc/conf.py

@@ -48,7 +48,7 @@
 
 # General information about the project.
 project = u'PyAL'
-copyright = u'2012, Marcus von Appen'
+copyright = u'2012-2013, Marcus von Appen'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -235,7 +235,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'PyAL', u'PyAL Documentation',
-   u'Marcus von Appen', 'PyAL', 'One line description of project.',
+   u'Marcus von Appen', 'PyAL', 'ctypes wrapper for OpenAL',
    'Miscellaneous'),
 ]
 

doc/index.rst

@@ -8,12 +8,13 @@ Contents
 ========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    install.rst
    integration.rst
    openal.rst
-   openalaudio.rst
+   audio.rst
+   loaders.rst
    news.rst
 
 Further readings:

doc/loaders.rst

@@ -0,0 +1,24 @@
+.. module:: openal.loaders
+   :synopsis: Easy sound loading supports
+
+openal.loaders - loading sounds
+===============================
+
+.. todo::
+
+   Outline
+
+API
+^^^
+
+.. function:: load_file(fname : string) -> SoundData
+
+   Loads an audio file into a :class:`SoundData` object.
+
+.. function:: load_stream(source : object) -> SoundData
+
+   Not implemented yet.
+
+.. function:: load_wav_file(fname : string) -> SoundData
+
+   Loads a WAV audio file into a :class:`SoundData` object.

doc/news.rst

@@ -2,8 +2,8 @@ Release News
 ============
 This describes the latest changes between the PyAL releases.
 
-1.0.0
+0.1.0
 -----
-Released on 2013-XX-XX.
+Released on 2013-04-21.
 
 * Initial Release

doc/todos.rst

@@ -1,6 +1,5 @@
-TODOs
-=====
+Todo list for PyAL
+==================
 
-General
--------
 * proper unit tests
+* more examples

examples/audioplayer.py

@@ -2,8 +2,8 @@
 import os
 import sys
 import time
-import wave
-from openal.audio import SoundSink, SoundData, SoundSource
+from openal.audio import SoundSink, SoundSource
+from openal.loaders import load_wav_file
 
 def run():
     if len (sys.argv) < 2:
@@ -14,19 +14,14 @@ def run():
     else:
         fname = sys.argv[1]
 
-    wavefp = wave.open(fname)
-    channels = wavefp.getnchannels()
-    bitrate = wavefp.getsampwidth() * 8
-    samplerate = wavefp.getframerate()
-    wavbuf = wavefp.readframes(wavefp.getnframes())
 
     sink = SoundSink()
     sink.activate()
 
     source = SoundSource(position=[10, 0, 0])
     source.looping = True
 
-    data = SoundData(wavbuf, channels, bitrate, len(wavbuf), samplerate)
+    data = load_wav_file(fname)
     source.queue(data)
 
     sink.play(source)