From ae301d0f1288b31841e91be8d63a2ab024c2158f Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Fri, 19 May 2023 07:48:37 +0200
Subject: AudioSink: Add latency query, init(..) frameDuration in ms shall be
 int, fix API doc

---
 src/java/com/jogamp/common/av/AudioSink.java      | 42 ++++++++++++++++++-----
 src/java/jogamp/common/av/JavaSoundAudioSink.java | 13 ++++++-
 src/java/jogamp/common/av/NullAudioSink.java      | 12 ++++++-
 3 files changed, 57 insertions(+), 10 deletions(-)

(limited to 'src')

diff --git a/src/java/com/jogamp/common/av/AudioSink.java b/src/java/com/jogamp/common/av/AudioSink.java
index 317b0ac..8067b51 100644
--- a/src/java/com/jogamp/common/av/AudioSink.java
+++ b/src/java/com/jogamp/common/av/AudioSink.java
@@ -145,18 +145,25 @@ public interface AudioSink {
     public boolean setVolume(float v);
 
     /**
-     * Returns the preferred sample-rate of this sink.
+     * Returns the preferred sample-rate of this sink, i.e. mixer frequency in Hz, e.g. 41000 or 48000.
      * <p>
      * The preferred sample-rate is guaranteed to be supported
      * and shall reflect this sinks most native format,
      * i.e. best performance w/o data conversion.
      * </p>
-     * @see #initSink(AudioFormat)
+     * @see #init(AudioFormat, float, int, int, int)
      * @see #isSupported(AudioFormat)
-     * @see #getPreferredSampleRate()
      */
     public int getPreferredSampleRate();
 
+    /**
+     * 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>
+     */
+    public float getDefaultLatency();
+
     /**
      * Returns the preferred {@link AudioFormat} by this sink.
      * <p>
@@ -170,7 +177,7 @@ public interface AudioSink {
      *   <li>ALAudioSink: {@link AudioFormat#sampleRate}.
      * </ul>
      * </p>
-     * @see #initSink(AudioFormat)
+     * @see #init(AudioFormat, float, int, int, int)
      * @see #isSupported(AudioFormat)
      * @see #getPreferredSampleRate()
      */
@@ -181,7 +188,7 @@ public interface AudioSink {
 
     /**
      * Returns true if the given format is supported by the sink, otherwise false.
-     * @see #initSink(AudioFormat)
+     * @see #init(AudioFormat, float, int, int, int)
      * @see #getPreferredFormat()
      */
     public boolean isSupported(AudioFormat format);
@@ -205,7 +212,7 @@ public interface AudioSink {
      * @param queueLimit maximum time in milliseconds the queue can hold (and grow), see {@link #DefaultQueueLimitWithVideo} and {@link #DefaultQueueLimitAudioOnly}.
      * @return true if successful, otherwise false
      */
-    public boolean init(AudioFormat requestedFormat, float frameDuration,
+    public boolean init(AudioFormat requestedFormat, int frameDuration,
                         int initialQueueSize, int queueGrowAmount, int queueLimit);
 
     /**
@@ -214,6 +221,15 @@ public interface AudioSink {
      */
     public AudioFormat getChosenFormat();
 
+    /**
+     * Returns the (minimum) latency in seconds of this sink as set by {@link #init(AudioFormat, float, int, int, int)}, see {@link #getDefaultLatency()}.
+     * <p>
+     * Latency might be the reciprocal mixer-refresh-interval [Hz], e.g. 50 Hz refresh-rate = 20ms minimum latency.
+     * </p>
+     * @see #init(AudioFormat, float, int, int, int)
+     */
+    public float getLatency();
+
     /**
      * Returns true, if {@link #play()} has been requested <i>and</i> the sink is still playing,
      * otherwise false.
@@ -244,6 +260,7 @@ public interface AudioSink {
      * @see #play()
      * @see #pause()
      * @see #enqueueData(AudioFrame)
+     * @see #init(AudioFormat, float, int, int, int)
      */
     public void flush();
 
@@ -253,10 +270,14 @@ public interface AudioSink {
     /**
      * Returns the number of allocated buffers as requested by
      * {@link #init(AudioFormat, float, int, int, int)}.
+     * @see #init(AudioFormat, float, int, int, int)
      */
     public int getFrameCount();
 
-    /** @return the current enqueued frames count since {@link #init(AudioFormat, float, int, int, int)}. */
+    /**
+     * Returns the current enqueued frames count since {@link #init(AudioFormat, float, int, int, int)}.
+     * @see #init(AudioFormat, float, int, int, int)
+     */
     public int getEnqueuedFrameCount();
 
     /**
@@ -264,6 +285,7 @@ public interface AudioSink {
      * <p>
      * {@link #init(AudioFormat, float, int, int, int)} must be called first.
      * </p>
+     * @see #init(AudioFormat, float, int, int, int)
      */
     public int getQueuedFrameCount();
 
@@ -272,6 +294,7 @@ public interface AudioSink {
      * <p>
      * {@link #init(AudioFormat, float, int, int, int)} must be called first.
      * </p>
+     * @see #init(AudioFormat, float, int, int, int)
      */
     public int getQueuedByteCount();
 
@@ -280,6 +303,7 @@ public interface AudioSink {
      * <p>
      * {@link #init(AudioFormat, float, int, int, int)} must be called first.
      * </p>
+     * @see #init(AudioFormat, float, int, int, int)
      */
     public int getQueuedTime();
 
@@ -293,18 +317,20 @@ public interface AudioSink {
      * <p>
      * {@link #init(AudioFormat, float, int, int, int)} must be called first.
      * </p>
+     * @see #init(AudioFormat, float, int, int, int)
      */
     public int getFreeFrameCount();
 
     /**
      * Enqueue <code>byteCount</code> bytes of the remaining bytes of the given NIO {@link ByteBuffer} to this sink.
      * <p>
-     * The data must comply with the chosen {@link AudioFormat} as returned by {@link #initSink(AudioFormat)}.
+     * The data must comply with the chosen {@link AudioFormat} as set via {@link #init(AudioFormat, float, int, int, int)}.
      * </p>
      * <p>
      * {@link #init(AudioFormat, float, int, int, int)} must be called first.
      * </p>
      * @returns the enqueued internal {@link AudioFrame}.
+     * @see #init(AudioFormat, float, int, int, int)
      */
     public AudioFrame enqueueData(int pts, ByteBuffer bytes, int byteCount);
 }
diff --git a/src/java/jogamp/common/av/JavaSoundAudioSink.java b/src/java/jogamp/common/av/JavaSoundAudioSink.java
index f5f9eb8..4d89c4d 100644
--- a/src/java/jogamp/common/av/JavaSoundAudioSink.java
+++ b/src/java/jogamp/common/av/JavaSoundAudioSink.java
@@ -122,6 +122,16 @@ public class JavaSoundAudioSink implements AudioSink {
         return DefaultFormat.sampleRate;
     }
 
+    @Override
+    public float getDefaultLatency() {
+        return 20f/1000f; // fake 20ms
+    }
+
+    @Override
+    public float getLatency() {
+        return 20f/1000f; // fake 20ms
+    }
+
     @Override
     public AudioFormat getPreferredFormat() {
         return DefaultFormat;
@@ -138,7 +148,7 @@ public class JavaSoundAudioSink implements AudioSink {
     }
 
     @Override
-    public boolean init(final AudioFormat requestedFormat, final float frameDuration, final int initialQueueSize, final int queueGrowAmount, final int queueLimit) {
+    public boolean init(final AudioFormat requestedFormat, final int frameDuration, final int initialQueueSize, final int queueGrowAmount, final int queueLimit) {
         if( !staticAvailable ) {
             return false;
         }
@@ -271,4 +281,5 @@ public class JavaSoundAudioSink implements AudioSink {
 
     @Override
     public final int getPTS() { return 0; } // FIXME
+
 }
diff --git a/src/java/jogamp/common/av/NullAudioSink.java b/src/java/jogamp/common/av/NullAudioSink.java
index 36681bb..7a02af9 100644
--- a/src/java/jogamp/common/av/NullAudioSink.java
+++ b/src/java/jogamp/common/av/NullAudioSink.java
@@ -88,6 +88,16 @@ public class NullAudioSink implements AudioSink {
         return DefaultFormat.sampleRate;
     }
 
+    @Override
+    public float getDefaultLatency() {
+        return 0;
+    }
+
+    @Override
+    public float getLatency() {
+        return 0;
+    }
+
     @Override
     public AudioFormat getPreferredFormat() {
         return DefaultFormat;
@@ -114,7 +124,7 @@ public class NullAudioSink implements AudioSink {
     }
 
     @Override
-    public boolean init(final AudioFormat requestedFormat, final float frameDuration, final int initialQueueSize, final int queueGrowAmount, final int queueLimit) {
+    public boolean init(final AudioFormat requestedFormat, final int frameDuration, final int initialQueueSize, final int queueGrowAmount, final int queueLimit) {
         chosenFormat = requestedFormat;
         return true;
     }
-- 
cgit v1.2.3