Sound3D: Further OO wrapper to be used in ALAudioSink: Context locking, ALCcontext recreation, ..

Context
- Recursive context locking (only 1st shall do native makeCurrent, only last shall do native release)
- Access to the current Context instance (thread local storage)
- Obey "One context can only be current on one thread,
        and one thread can only have one context current!"
- ALCcontext recreation within lock, allowing to change native OpenAL specifics via attr list
- ALCcontext creation (initial) w/ attr list

Device
- Retrieve name if default name null has been given
- Expose device name
- Allow to open() again

Source
- Allow lazy creation w/ invalid ID
- Allow create() post instantiation (for a single source)
- Throw ALException in all queued buffer methods as they are crucial
  in multithreading streaming.
- Add queue buffer with OpenAL buffer-id int[] arrays variant
  to be used w/o Buffer

Listener
- Fix (get|set)Orientation() API doc: It's 'at' vector, then 'up' vector.

General:
- Have toString()
- Added versatile AudioSystem3D.check*Error(..)

Earlier Sound3D changes
- 7f73d50c90d05cf7388f23977ca956a4933019ad
- 64b40bd4359cad46ebf62751ea342d80205bd98b

1 files changed, 69 insertions, 9 deletions

diff --git a/src/java/com/jogamp/openal/sound3d/Source.java b/src/java/com/jogamp/openal/sound3d/Source.java
index b3b0da9..09b255a 100644
--- a/src/java/com/jogamp/openal/sound3d/Source.java
+++ b/src/java/com/jogamp/openal/sound3d/Source.java
@@ -35,6 +35,7 @@
 package com.jogamp.openal.sound3d;
 
 import com.jogamp.openal.ALConstants;
+import com.jogamp.openal.ALException;
 
 /**
  * This class is used to represent sound-producing objects in the Sound3D
@@ -42,16 +43,44 @@ import com.jogamp.openal.ALConstants;
  * gain and other properties along with methods for starting, pausing, rewinding
  * and stopping sudio projecting from a source.
  *
- * @author Athomas Goldberg
+ * @author Athomas Goldberg, Sven Gothel, et al.
  */
 public final class Source {
     private int sourceID;
     private Buffer buffer;
 
+    /** Create a new instance with an invalid OpenAL source ID */
+    public Source() {
+        sourceID = -1;
+    }
+
+    /**
+     * Create a new instance with a given OpenAL source ID
+     * @param sourceID an OpenAL source ID, pass -1 for an invalid value for lazy creation
+     */
     public Source(final int sourceID) {
         this.sourceID = sourceID;
     }
 
+    /**
+     * Creates a new OpenAL source ID if {@link #isValid()} == false.
+     * @return true if a new ID has been successfully created, otherwise false
+     */
+    public boolean create() {
+        if( isValid() ) {
+            return false;
+        }
+        final int[] val = { -1 };
+        AudioSystem3D.al.alGenSources(1, val, 0);
+        if( 0 <= val[0] && AudioSystem3D.al.alIsSource(val[0]) ) {
+            sourceID = val[0];
+            return true;
+        } else {
+            sourceID = -1;
+            return false;
+        }
+    }
+
     /** Return the OpenAL source ID, -1 if invalid. */
     public int getID() { return sourceID; }
 
@@ -466,22 +495,24 @@ public final class Source {
     /**
      * Gets the number of buffers currently queued on this source.
      * @return the number of buffers currently queued on this source.
+     * @throws ALException on AL error
      */
-    public int getBuffersQueued() {
+    public int getBuffersQueued() throws ALException {
         final int[] result = new int[1];
         AudioSystem3D.al.alGetSourcei(sourceID, ALConstants.AL_BUFFERS_QUEUED, result, 0);
-
+        AudioSystem3D.checkALError("Query AL_BUFFERS_QUEUED", true, true);
         return result[0];
     }
 
     /**
      * Gets the number of buffers already processed on this source.
      * @return the number of buffers already processed on this source.
+     * @throws ALException on AL error
      */
-    public int getBuffersProcessed() {
+    public int getBuffersProcessed() throws ALException {
         final int[] result = new int[1];
         AudioSystem3D.al.alGetSourcei(sourceID, ALConstants.AL_BUFFERS_PROCESSED, result, 0);
-
+        AudioSystem3D.checkALError("Query AL_BUFFERS_PROCESSED", true, true);
         return result[0];
     }
 
@@ -515,31 +546,60 @@ public final class Source {
      * buffers will be played in the order they are queued.
      *
      * @param buffers a set of initialized (loaded) buffers.
+     * @throws ALException on AL error
      */
-    public void queueBuffers(final Buffer[] buffers) {
+    public void queueBuffers(final Buffer[] buffers) throws ALException {
         final int numBuffers = buffers.length;
         final int[] arr = new int[numBuffers];
 
         for (int i = 0; i < numBuffers; i++) {
             arr[i] = buffers[i].getID();
         }
-
         AudioSystem3D.al.alSourceQueueBuffers(sourceID, numBuffers, arr, 0);
+        AudioSystem3D.checkALError("alSourceQueueBuffers", true, true);
+    }
+
+    /**
+     * Queues `bufferIDs.length` OpenAL buffers on a source.
+     *
+     * @param bufferIDs array of to be queued OpenAL buffer IDs
+     * @throws ALException on AL error
+     */
+    public void queueBuffers(final int[] bufferIDs) throws ALException {
+        AudioSystem3D.al.alSourceQueueBuffers(sourceID, bufferIDs.length, bufferIDs, 0);
+        AudioSystem3D.checkALError("alSourceQueueBuffers", true, true);
     }
 
     /**
      * Unqueues one or more buffers on a source.
      *
      * @param buffers a set of previously queued buffers.
+     * @throws ALException on AL error
      */
-    public void unqueueBuffers(final Buffer[] buffers) {
+    public void unqueueBuffers(final Buffer[] buffers) throws ALException {
         final int numBuffers = buffers.length;
         final int[] arr = new int[numBuffers];
 
         for (int i = 0; i < numBuffers; i++) {
             arr[i] = buffers[i].getID();
         }
-
         AudioSystem3D.al.alSourceUnqueueBuffers(sourceID, numBuffers, arr, 0);
+        AudioSystem3D.checkALError("alSourceUnqueueBuffers", true, true);
+    }
+
+    /**
+     * Unqueues `bufferIDs.length` OpenAL buffers on a source.
+     *
+     * @param bufferIDs array of resulting unqueued OpenAL buffer IDs of previously queued buffers.
+     * @throws ALException on AL error
+     */
+    public void unqueueBuffers(final int[] bufferIDs) throws ALException {
+        AudioSystem3D.al.alSourceUnqueueBuffers(sourceID, bufferIDs.length, bufferIDs, 0);
+        AudioSystem3D.checkALError("alSourceUnqueueBuffers", true, true);
+    }
+
+    @Override
+    public String toString() {
+        return "ALSource[id "+sourceID+", buffer "+buffer+"]";
     }
 }