Add AudioSink.getSourceCount(), refine Audio* API doc

4 files changed, 44 insertions, 10 deletions

diff --git a/src/java/com/jogamp/common/av/AudioFormat.java b/src/java/com/jogamp/common/av/AudioFormat.java
index de7824c..8102034 100644
--- a/src/java/com/jogamp/common/av/AudioFormat.java
+++ b/src/java/com/jogamp/common/av/AudioFormat.java
@@ -32,13 +32,13 @@ package com.jogamp.common.av;
  */
 public class AudioFormat {
     /**
-     * @param sampleRate sample rate in Hz (1/s)
-     * @param sampleSize sample size in bits
-     * @param channelCount number of channels
-     * @param signed true if signed number, false for unsigned
-     * @param fixedP true for fixed point value, false for unsigned floating point value with a sampleSize of 32 (float) or 64 (double)
+     * @param sampleRate sample rate in Hz (1/s), e.g. 44100 Hz
+     * @param sampleSize sample size in bits, e.g. 16 bits
+     * @param channelCount number of channels, e.g. 2 channels for stereo
+     * @param signed true if signed PCM values, false for unsigned values
+     * @param fixedP true for fixed point values, false for unsigned floating point values with a sampleSize of 32 (float) or 64 (double)
      * @param planar true for planar data package (each channel in own data buffer), false for packed data channels interleaved in one buffer.
-     * @param littleEndian true for little-endian, false for big endian
+     * @param littleEndian true for little-endian byte order, false for big endian byte order
      */
     public AudioFormat(final int sampleRate, final int sampleSize, final int channelCount, final boolean signed, final boolean fixedP, final boolean planar, final boolean littleEndian) {
         this.sampleRate = sampleRate;
@@ -58,17 +58,19 @@ public class AudioFormat {
         }
     }
 
-    /** Sample rate in Hz (1/s). */
+    /** Sample rate in Hz (1/s, e.g. 44100 Hz. */
     public final int sampleRate;
-    /** Sample size in bits. */
+    /** Sample size in bits, e.g. 16 bits. */
     public final int sampleSize;
-    /** Number of channels. */
+    /** Number of channels, e.g. 2 channels for stereo. */
     public final int channelCount;
+    /** Signed PCM values if true, otherwise unsigned values. */
     public final boolean signed;
     /** Fixed or floating point values. Floating point 'float' has {@link #sampleSize} 32, 'double' has {@link #sampleSize} 64. */
     public final boolean fixedP;
     /** Planar or packed samples. If planar, each channel has their own data buffer. If packed, channel data is interleaved in one buffer. */
     public final boolean planar;
+    /** Little-endian byte order if true, otherwise big endian byte order. */
     public final boolean littleEndian;
 
 
diff --git a/src/java/com/jogamp/common/av/AudioSink.java b/src/java/com/jogamp/common/av/AudioSink.java
index 8067b51..7f0c620 100644
--- a/src/java/com/jogamp/common/av/AudioSink.java
+++ b/src/java/com/jogamp/common/av/AudioSink.java
@@ -151,16 +151,35 @@ public interface AudioSink {
      * and shall reflect this sinks most native format,
      * i.e. best performance w/o data conversion.
      * </p>
+     * <p>
+     * May return {@link AudioSink#DefaultFormat}'s  44100 default if undefined.
+     * </p>
      * @see #init(AudioFormat, float, int, int, int)
      * @see #isSupported(AudioFormat)
      */
     public int getPreferredSampleRate();
 
     /**
+     * Returns the number of sources the used device is capable to mix.
+     * <p>
+     * This device attribute is only formally exposed and not used,
+     * since an audio sink is only utilizing one source.
+     * </p>
+     * <p>
+     * May return <code>-1</code> if undefined.
+     * </p>
+     * @return
+     */
+    public int getSourceCount();
+
+    /**
      * Returns the default (minimum) latency in seconds
      * <p>
      * Latency might be the reciprocal mixer-refresh-interval [Hz], e.g. 50 Hz refresh-rate = 20ms minimum latency.
      * </p>
+     * <p>
+     * May return 20ms for a 50 Hz refresh rate if undefined.
+     * </p>
      */
     public float getDefaultLatency();
 
@@ -177,13 +196,16 @@ public interface AudioSink {
      *   <li>ALAudioSink: {@link AudioFormat#sampleRate}.
      * </ul>
      * </p>
+     * <p>
+     * May return {@link AudioSink#DefaultFormat} if undefined.
+     * </p>
      * @see #init(AudioFormat, float, int, int, int)
      * @see #isSupported(AudioFormat)
      * @see #getPreferredSampleRate()
      */
     public AudioFormat getPreferredFormat();
 
-    /** Return the maximum number of supported channels. */
+    /** Return the maximum number of supported channels, e.g. 1 for mono, 2 for stereo, etc. */
     public int getMaxSupportedChannels();
 
     /**
diff --git a/src/java/jogamp/common/av/JavaSoundAudioSink.java b/src/java/jogamp/common/av/JavaSoundAudioSink.java
index 4d89c4d..1617b10 100644
--- a/src/java/jogamp/common/av/JavaSoundAudioSink.java
+++ b/src/java/jogamp/common/av/JavaSoundAudioSink.java
@@ -123,6 +123,11 @@ public class JavaSoundAudioSink implements AudioSink {
     }
 
     @Override
+    public int getSourceCount() {
+        return -1;
+    }
+
+    @Override
     public float getDefaultLatency() {
         return 20f/1000f; // fake 20ms
     }
diff --git a/src/java/jogamp/common/av/NullAudioSink.java b/src/java/jogamp/common/av/NullAudioSink.java
index 7a02af9..781cfca 100644
--- a/src/java/jogamp/common/av/NullAudioSink.java
+++ b/src/java/jogamp/common/av/NullAudioSink.java
@@ -89,6 +89,11 @@ public class NullAudioSink implements AudioSink {
     }
 
     @Override
+    public int getSourceCount() {
+        return -1;
+    }
+
+    @Override
     public float getDefaultLatency() {
         return 0;
     }