From e28a3b39e1e8caf3f6cf3bfe82efdaae818a6c7b Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Mon, 26 Aug 2013 09:59:47 +0200 Subject: AudioSink: Fixe type names ; Enhance AudioFormat negotiation ; ALAudioSink adds AL_SOFT_buffer_samples support w/ full AL caps - Fixe type names: - Remove AudioDataType, we only support PCM here anyways - AudioDataFormat -> AudioFormat / Add 'planar' attribute to distingush packed/planar data type - Validate float types - Enhance AudioFormat negotiation - Add 'isSupported(AudioFormat format)' which _shall_ be used before 'init(..)' to test/negotiate format - Add getMaxSupportedChannels(), which may be used w/ getPreferredFormat() if orig requested format fails via 'isSupported(..)' - 'init(..)' returns boolean only. - ALAudioSink adds AL_SOFT_buffer_samples support w/ full AL caps - Determine whether AL_SOFT_buffer_samples is supported - Use new JOAL ALHelper to convert AudioFormat -> AL-types, which also answers the 'isSupported(..)' query. - Now allows multiple: channles, sample-types, etc. --- .../com/jogamp/opengl/util/av/AudioSink.java | 169 +++++++++++++++------ 1 file changed, 120 insertions(+), 49 deletions(-) (limited to 'src/jogl/classes/com/jogamp/opengl/util') diff --git a/src/jogl/classes/com/jogamp/opengl/util/av/AudioSink.java b/src/jogl/classes/com/jogamp/opengl/util/av/AudioSink.java index 7f477a57d..8751fc816 100644 --- a/src/jogl/classes/com/jogamp/opengl/util/av/AudioSink.java +++ b/src/jogl/classes/com/jogamp/opengl/util/av/AudioSink.java @@ -39,33 +39,46 @@ public interface AudioSink { /** Default frame duration in millisecond, i.e. 1 frame per {@value} ms. */ public static final int DefaultFrameDuration = 32; - /** Initial audio queue size in milliseconds. {@value} ms, i.e. 16 frames per 32 ms. See {@link #init(AudioDataFormat, float, int, int, int)}.*/ + /** Initial audio queue size in milliseconds. {@value} ms, i.e. 16 frames per 32 ms. See {@link #init(AudioFormat, float, int, int, int)}.*/ public static final int DefaultInitialQueueSize = 16 * 32; // 512 ms - /** Audio queue grow size in milliseconds. {@value} ms, i.e. 16 frames per 32 ms. See {@link #init(AudioDataFormat, float, int, int, int)}.*/ + /** Audio queue grow size in milliseconds. {@value} ms, i.e. 16 frames per 32 ms. See {@link #init(AudioFormat, float, int, int, int)}.*/ public static final int DefaultQueueGrowAmount = 16 * 32; // 512 ms - /** Audio queue limit w/ video in milliseconds. {@value} ms, i.e. 96 frames per 32 ms. See {@link #init(AudioDataFormat, float, int, int, int)}.*/ + /** Audio queue limit w/ video in milliseconds. {@value} ms, i.e. 96 frames per 32 ms. See {@link #init(AudioFormat, float, int, int, int)}.*/ public static final int DefaultQueueLimitWithVideo = 96 * 32; // 3072 ms - /** Audio queue limit w/o video in milliseconds. {@value} ms, i.e. 32 frames per 32 ms. See {@link #init(AudioDataFormat, float, int, int, int)}.*/ + /** Audio queue limit w/o video in milliseconds. {@value} ms, i.e. 32 frames per 32 ms. See {@link #init(AudioFormat, float, int, int, int)}.*/ public static final int DefaultQueueLimitAudioOnly = 32 * 32; // 1024 ms - /** Specifies the audio data type. Currently only PCM is supported. */ - public static enum AudioDataType { PCM }; - /** - * Specifies the audio data format. + * Specifies the linear audio PCM format. */ - public static class AudioDataFormat { - public AudioDataFormat(AudioDataType dataType, int sampleRate, int sampleSize, int channelCount, boolean signed, boolean fixedP, boolean littleEndian) { - this.dataType = dataType; + public static 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 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 + */ + public AudioFormat(int sampleRate, int sampleSize, int channelCount, boolean signed, boolean fixedP, boolean planar, boolean littleEndian) { this.sampleRate = sampleRate; this.sampleSize = sampleSize; this.channelCount = channelCount; this.signed = signed; this.fixedP = fixedP; + this.planar = planar; this.littleEndian = littleEndian; + if( !fixedP ) { + if( sampleSize != 32 && sampleSize != 64 ) { + throw new IllegalArgumentException("Floating point: sampleSize "+sampleSize+" bits"); + } + if( !signed ) { + throw new IllegalArgumentException("Floating point: unsigned"); + } + } } - /** Audio data type. */ - public final AudioDataType dataType; + /** Sample rate in Hz (1/s). */ public final int sampleRate; /** Sample size in bits. */ @@ -73,15 +86,25 @@ public interface AudioSink { /** Number of channels. */ public final int channelCount; public final boolean signed; - /** Fixed or floating point values. Floating point 'float' has {@link #sampleSize} 32, 'double' has {@link #sampleSize} 64, */ + /** 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; public final boolean littleEndian; + + // + // Time <-> Bytes + // + /** * Returns the byte size of the given milliseconds - * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}. + * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}. + *

+ * Time -> Byte Count + *

*/ - public final int getByteSize(int millisecs) { + public final int getDurationsByteSize(int millisecs) { final int bytesPerSample = sampleSize >>> 3; // /8 return millisecs * ( channelCount * bytesPerSample * ( sampleRate / 1000 ) ); } @@ -89,6 +112,9 @@ public interface AudioSink { /** * Returns the duration in milliseconds of the given byte count * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}. + *

+ * Byte Count -> Time + *

*/ public final int getBytesDuration(int byteCount) { final int bytesPerSample = sampleSize >>> 3; // /8 @@ -96,11 +122,14 @@ public interface AudioSink { } /** - * Returns the duration in milliseconds of the given and sample count per frame and channel + * Returns the duration in milliseconds of the given sample count per frame and channel * according to the {@link #sampleRate}, i.e. * 
          *    ( 1000f * sampleCount ) / sampleRate
          *
+ *

+ * Sample Count -> Time + *

* @param sampleCount sample count per frame and channel */ public final float getSamplesDuration(int sampleCount) { @@ -116,6 +145,9 @@ public interface AudioSink { * Note: frameDuration can be derived by sample count per frame and channel * via {@link #getSamplesDuration(int)}. *

+ *

+ * Frame Time -> Frame Count + *

* @param millisecs time in milliseconds * @param frameDuration duration per frame in milliseconds. */ @@ -130,21 +162,44 @@ public interface AudioSink { * sampleCount * ( sampleSize / 8 ) * *

- * Note: To retrieve the byte size for all channels, you need to pre-multiply sampleCount - * with {@link #channelCount}. + * Note: To retrieve the byte size for all channels, + * you need to pre-multiply sampleCount with {@link #channelCount}. *

+ *

+ * Sample Count -> Byte Count + *

* @param sampleCount sample count */ - public final int getSamplesByteSize(int sampleCount) { + public final int getSamplesByteCount(int sampleCount) { return sampleCount * ( sampleSize >>> 3 ); } + /** + * Returns the sample count of given byte count + * according to the {@link #sampleSize}, i.e.: + * 
+         *  ( byteCount * 8 ) / sampleSize
+         *
+ *

+ * Note: If byteCount covers all channels and you request the sample size per channel, + * you need to divide the result by sampleCount by {@link #channelCount}. + *

+ *

+ * Byte Count -> Sample Count + *

+ * @param sampleCount sample count + */ + public final int getBytesSampleCount(int byteCount) { + return ( byteCount << 3 ) / sampleSize; + } + public String toString() { - return "AudioDataFormat[type "+dataType+", sampleRate "+sampleRate+", sampleSize "+sampleSize+", channelCount "+channelCount+ - ", signed "+signed+", fixedP "+fixedP+", "+(littleEndian?"little":"big")+"endian]"; } + return "AudioDataFormat[sampleRate "+sampleRate+", sampleSize "+sampleSize+", channelCount "+channelCount+ + ", signed "+signed+", fixedP "+fixedP+", "+(planar?"planar":"packed")+", "+(littleEndian?"little":"big")+"-endian]"; } } - /** Default {@link AudioDataFormat}, [type PCM, sampleRate 44100, sampleSize 16, channelCount 2, signed, fixedP, littleEndian]. */ - public static final AudioDataFormat DefaultFormat = new AudioDataFormat(AudioDataType.PCM, 44100, 16, 2, true /* signed */, true /* fixed point */, true /* littleEndian */); + /** Default {@link AudioFormat}, [type PCM, sampleRate 44100, sampleSize 16, channelCount 2, signed, fixedP, !planar, littleEndian]. */ + public static final AudioFormat DefaultFormat = new AudioFormat(44100, 16, 2, true /* signed */, + true /* fixed point */, false /* planar */, true /* littleEndian */); public static abstract class AudioFrame extends TimeFrameI { protected int byteSize; @@ -227,38 +282,54 @@ public interface AudioSink { public boolean setVolume(float v); /** - * Returns the preferred {@link AudioDataFormat} by this sink. + * Returns the preferred {@link AudioFormat} by this sink. *

- * The preferred format shall reflect this sinks most native format, + * The preferred format is guaranteed to be supported + * and shall reflect this sinks most native format, * i.e. best performance w/o data conversion. *

- * @see #initSink(AudioDataFormat) + *

+ * Known {@link #AudioFormat} attributes considered by implementations: + *

+ *

+ * @see #initSink(AudioFormat) + * @see #isSupported(AudioFormat) + */ + public AudioFormat getPreferredFormat(); + + /** Return the maximum number of supported channels. */ + public int getMaxSupportedChannels(); + + /** + * Returns true if the given format is supported by the sink, otherwise false. + * @see #initSink(AudioFormat) + * @see #getPreferredFormat() */ - public AudioDataFormat getPreferredFormat(); + public boolean isSupported(AudioFormat format); /** * Initializes the sink. *

- * Implementation shall try to match the given requestedFormat {@link AudioDataFormat} - * as close as possible, regarding it's capabilities. + * Implementation must match the given requestedFormat {@link AudioFormat}. *

*

- * A user may consider {@link #getPreferredFormat()} and pass this value - * to utilize best performance and behavior. - *

- * The {@link #DefaultFormat} should be supported by all implementations. + * Caller shall validate requestedFormat via {@link #isSupported(AudioFormat)} + * beforehand and try to find a suitable supported one. + * {@link #getPreferredFormat()} and {@link #getMaxSupportedChannels()} may help. *

- * @param requestedFormat the requested {@link AudioDataFormat}. + * @param requestedFormat the requested {@link AudioFormat}. * @param frameDuration average or fixed frame duration in milliseconds * helping a caching {@link AudioFrame} based implementation to determine the frame count in the queue. * See {@link #DefaultFrameDuration}. * @param initialQueueSize initial time in milliseconds to queue in this sink, see {@link #DefaultInitialQueueSize}. * @param queueGrowAmount time in milliseconds to grow queue if full, see {@link #DefaultQueueGrowAmount}. * @param queueLimit maximum time in milliseconds the queue can hold (and grow), see {@link #DefaultQueueLimitWithVideo} and {@link #DefaultQueueLimitAudioOnly}. - * @return if successful the chosen AudioDataFormat based on the requestedFormat and this sinks capabilities, otherwise null. + * @return true if successful, otherwise false */ - public AudioDataFormat init(AudioDataFormat requestedFormat, float frameDuration, - int initialQueueSize, int queueGrowAmount, int queueLimit); + public boolean init(AudioFormat requestedFormat, float frameDuration, + int initialQueueSize, int queueGrowAmount, int queueLimit); /** * Returns true, if {@link #play()} has been requested and the sink is still playing, @@ -285,7 +356,7 @@ public interface AudioSink { /** * Flush all queued buffers, implies {@link #pause()}. *

- * {@link #init(AudioDataFormat, float, int, int, int)} must be called first. + * {@link #init(AudioFormat, float, int, int, int)} must be called first. *

* @see #play() * @see #pause() @@ -298,17 +369,17 @@ public interface AudioSink { /** * Returns the number of allocated buffers as requested by - * {@link #init(AudioDataFormat, float, int, int, int)}. + * {@link #init(AudioFormat, float, int, int, int)}. */ public int getFrameCount(); - /** @return the current enqueued frames count since {@link #init(AudioDataFormat, float, int, int, int)}. */ + /** @return the current enqueued frames count since {@link #init(AudioFormat, float, int, int, int)}. */ public int getEnqueuedFrameCount(); /** * Returns the current number of frames queued for playing. *

- * {@link #init(AudioDataFormat, float, int, int, int)} must be called first. + * {@link #init(AudioFormat, float, int, int, int)} must be called first. *

*/ public int getQueuedFrameCount(); @@ -316,7 +387,7 @@ public interface AudioSink { /** * Returns the current number of bytes queued for playing. *

- * {@link #init(AudioDataFormat, float, int, int, int)} must be called first. + * {@link #init(AudioFormat, float, int, int, int)} must be called first. *

*/ public int getQueuedByteCount(); @@ -324,7 +395,7 @@ public interface AudioSink { /** * Returns the current queued frame time in milliseconds for playing. *

- * {@link #init(AudioDataFormat, float, int, int, int)} must be called first. + * {@link #init(AudioFormat, float, int, int, int)} must be called first. *

*/ public int getQueuedTime(); @@ -337,7 +408,7 @@ public interface AudioSink { /** * Returns the current number of frames in the sink available for writing. *

- * {@link #init(AudioDataFormat, float, int, int, int)} must be called first. + * {@link #init(AudioFormat, float, int, int, int)} must be called first. *

*/ public int getFreeFrameCount(); @@ -345,10 +416,10 @@ public interface AudioSink { /** * Enqueue the remaining bytes of the given {@link AudioDataFrame}'s direct ByteBuffer to this sink. *

- * The data must comply with the chosen {@link AudioDataFormat} as returned by {@link #initSink(AudioDataFormat)}. + * The data must comply with the chosen {@link AudioFormat} as returned by {@link #initSink(AudioFormat)}. *

*

- * {@link #init(AudioDataFormat, float, int, int, int)} must be called first. + * {@link #init(AudioFormat, float, int, int, int)} must be called first. *

* @returns the enqueued internal {@link AudioFrame}, which may differ from the input audioDataFrame. * @deprecated User shall use {@link #enqueueData(int, ByteBuffer, int)}, which allows implementation @@ -359,10 +430,10 @@ public interface AudioSink { /** * Enqueue byteCount bytes of the remaining bytes of the given NIO {@link ByteBuffer} to this sink. *

- * The data must comply with the chosen {@link AudioDataFormat} as returned by {@link #initSink(AudioDataFormat)}. + * The data must comply with the chosen {@link AudioFormat} as returned by {@link #initSink(AudioFormat)}. *

*

- * {@link #init(AudioDataFormat, float, int, int, int)} must be called first. + * {@link #init(AudioFormat, float, int, int, int)} must be called first. *

* @returns the enqueued internal {@link AudioFrame}. */ -- cgit v1.2.3