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 ++++++++++++++++++++++------
1 file changed, 34 insertions(+), 8 deletions(-)
(limited to 'src/java/com/jogamp/common/av/AudioSink.java')
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);
}
--
cgit v1.2.3