ALAudioSink: Promote to public, be fully functional regarding AudioFormat and OpenAL paremeter. Can be 'plugged' into existing OpenAL logic.

1 files changed, 223 insertions, 19 deletions

diff --git a/src/java/com/jogamp/openal/util/ALHelpers.java b/src/java/com/jogamp/openal/util/ALHelpers.java
index a666049..65869cc 100644
--- a/src/java/com/jogamp/openal/util/ALHelpers.java
+++ b/src/java/com/jogamp/openal/util/ALHelpers.java
@@ -1,7 +1,8 @@
-/*
+/**
  * OpenAL Helpers
  *
  * Copyright (c) 2011 by Chris Robinson <[email protected]>
+ * Copyright (c) 2013-2023 JogAmp Community
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -21,53 +22,201 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-
-/* This file contains routines to help with some menial OpenAL-related tasks,
- * such as opening a device and setting up a context, closing the device and
- * destroying its context, converting between frame counts and byte lengths,
- * finding an appropriate buffer format, and getting readable strings for
- * channel configs and sample types. */
 package com.jogamp.openal.util;
 
 import com.jogamp.openal.AL;
 import com.jogamp.openal.ALConstants;
 import static com.jogamp.openal.ALConstants.*;
 import com.jogamp.openal.ALExt;
-// import com.jogamp.openal.ALExtConstants;
 import static com.jogamp.openal.ALExtConstants.*;
 
+import com.jogamp.common.av.AudioFormat;
 
-/* This file contains routines to help with some menial OpenAL-related tasks,
- * such as converting between frame counts and byte lengths,
- * finding an appropriate buffer format, and getting readable strings for
+
+/* This class contains routines to help with some menial OpenAL-related tasks,
+ * such as finding an audio format and getting readable strings for
  * channel configs and sample types. */
 public class ALHelpers {
+    /**
+     * [openal-soft >= 1.18.0](https://github.com/kcat/openal-soft/blob/master/ChangeLog)
+     * - Removed support for the AL_SOFT_buffer_samples and AL_SOFT_buffer_sub_data
+     *   extensions. Due to conflicts with AL_EXT_SOURCE_RADIUS.
+     */
+    public static final String AL_SOFT_buffer_samples = "AL_SOFT_buffer_samples";
+    public static final String AL_EXT_MCFORMATS = "AL_EXT_MCFORMATS";
+    public static final String AL_EXT_FLOAT32 = "AL_EXT_FLOAT32";
+    public static final String AL_EXT_DOUBLE = "AL_EXT_DOUBLE";
+
+    public static final String ALC_EXT_thread_local_context = "ALC_EXT_thread_local_context";
+
+    /**
+     * Returns a compatible {@link AudioFormat} based on given OpenAL channel-layout, sample-type and format,
+     * as well as the generic sample-rate and sample-size.
+     * <p>
+     * The resulting {@link AudioFormat} uses {@link AudioFormat#planar} = false and {@link AudioFormat#littleEndian} = true.
+     * </p>
+     * @param alChannelLayout OpenAL channel layout
+     * @param alSampleType OpenAL sample type
+     * @param alFormat OpenAL format
+     * @param sampleRate sample rate, e.g. 44100
+     * @param sampleSize sample size in bits, e.g. 16
+     * @return a new {@link AudioFormat} instance or null if parameter are not conclusive or invalid.
+     */
+    public static AudioFormat getAudioFormat(final int alChannelLayout, final int alSampleType, final int alFormat,
+                                             final int sampleRate, final int sampleSize) {
+        if( ALConstants.AL_NONE == alChannelLayout || ALConstants.AL_NONE == alSampleType ||
+            ALConstants.AL_NONE == alFormat || 0 == sampleRate || 0 == sampleSize ) {
+            return null;
+        }
+        final int channelCount = getALChannelLayoutChannelCount(alChannelLayout);
+        if( 0 == channelCount ) {
+            return null;
+        }
+        final boolean signed = isALSampleTypeSigned(alSampleType);
+        final boolean fixedP = isALSampleTypeFixed(alSampleType);
+        return new AudioFormat(sampleRate, sampleSize, channelCount, signed, fixedP,
+                               false /* planar */, true /* littleEndian */);
+    }
 
     /**
-     * Returns a compatible AL buffer format given the AL channel layout and
-     * AL sample type. If <code>hasSOFTBufferSamples</code> is true,
+     * Returns a compatible AL buffer format given the {@link AudioFormat},
+     * which determines the AL channel layout and AL sample type.
+     * </p>
+     * <p>
+     * If <code>hasEXTMcFormats</code> or <code>hasSOFTBufferSamples</code> is true,
      * it will be called to find the closest-matching format from
-     * <code>AL_SOFT_buffer_samples</code>.
+     * <code>AL_EXT_MCFORMATS</code> or <code>AL_SOFT_buffer_samples</code>.
+     * </p>
      * <p>
      * Returns {@link ALConstants#AL_NONE} if no supported format can be found.
      * </p>
+     * <p>
+     * Function uses {@link AL#alIsExtensionPresent(String)}, which might be context dependent,
+     * otherwise function is context independent.
+     * </p>
      *
-     * @param alChannelLayout AL channel layout, see {@link #getDefaultALChannelLayout(int)}
-     * @param alSampleType AL sample type, see {@link #getALSampleType(int, boolean, boolean)}.
+     * @param audioFormat used to derive AL channel layout {@link #getDefaultALChannelLayout(int)}
+     *                    and AL sample type {@link #getALSampleType(int, boolean, boolean)}
+     * @param al AL instance
+     * @param alExt ALExt instance
+     * @return AL buffer format
+     */
+    public static int getALFormat(final AudioFormat audioFormat,
+                                  final AL al, final ALExt alExt) {
+        final int alChannelLayout = ALHelpers.getDefaultALChannelLayout(audioFormat.channelCount);
+        final int alSampleType = ALHelpers.getALSampleType(audioFormat.sampleSize, audioFormat.signed, audioFormat.fixedP);
+        if( ALConstants.AL_NONE != alChannelLayout && ALConstants.AL_NONE != alSampleType ) {
+            return ALHelpers.getALFormat(alChannelLayout, alSampleType, al, alExt);
+        } else {
+            return ALConstants.AL_NONE;
+        }
+    }
+
+    /**
+     * Returns a compatible AL buffer format given the {@link AudioFormat},
+     * which determines the AL channel layout and AL sample type.
+     * </p>
+     * <p>
+     * If <code>hasEXTMcFormats</code> or <code>hasSOFTBufferSamples</code> is true,
+     * it will be called to find the closest-matching format from
+     * <code>AL_EXT_MCFORMATS</code> or <code>AL_SOFT_buffer_samples</code>.
+     * </p>
+     * <p>
+     * Returns {@link ALConstants#AL_NONE} if no supported format can be found.
+     * </p>
+     * <p>
+     * Function is context independent.
+     * </p>
+     *
+     * @param audioFormat used to derive AL channel layout {@link #getDefaultALChannelLayout(int)}
+     *                    and AL sample type {@link #getALSampleType(int, boolean, boolean)}
+     * @param al AL instance
+     * @param alExt ALExt instance
      * @param hasSOFTBufferSamples true if having extension <code>AL_SOFT_buffer_samples</code>, otherwise false
      * @param hasEXTMcFormats true if having extension <code>AL_EXT_MCFORMATS</code>, otherwise false
      * @param hasEXTFloat32 true if having extension <code>AL_EXT_FLOAT32</code>, otherwise false
      * @param hasEXTDouble true if having extension <code>AL_EXT_DOUBLE</code>, otherwise false
+     * @return AL buffer format
+     */
+    public static int getALFormat(final AudioFormat audioFormat,
+                                  final AL al, final ALExt alExt,
+                                  final boolean hasSOFTBufferSamples,
+                                  final boolean hasEXTMcFormats,
+                                  final boolean hasEXTFloat32, final boolean hasEXTDouble) {
+        final int alChannelLayout = ALHelpers.getDefaultALChannelLayout(audioFormat.channelCount);
+        final int alSampleType = ALHelpers.getALSampleType(audioFormat.sampleSize, audioFormat.signed, audioFormat.fixedP);
+        final int alFormat;
+        if( ALConstants.AL_NONE != alChannelLayout && ALConstants.AL_NONE != alSampleType ) {
+            alFormat = ALHelpers.getALFormat(alChannelLayout, alSampleType, al, alExt,
+                                             hasSOFTBufferSamples, hasEXTMcFormats,
+                                             hasEXTFloat32, hasEXTDouble);
+        } else {
+            alFormat = ALConstants.AL_NONE;
+        }
+        return alFormat;
+    }
+
+    /**
+     * Returns a compatible AL buffer format given the AL channel layout and AL sample type.
+     * <p>
+     * If <code>hasEXTMcFormats</code> or <code>hasSOFTBufferSamples</code> is true,
+     * it will be called to find the closest-matching format from
+     * <code>AL_EXT_MCFORMATS</code> or <code>AL_SOFT_buffer_samples</code>.
+     * </p>
+     * <p>
+     * Returns {@link ALConstants#AL_NONE} if no supported format can be found.
+     * </p>
+     * <p>
+     * Function uses {@link AL#alIsExtensionPresent(String)}, which might be context dependent,
+     * otherwise function is context independent.
+     * </p>
+     *
+     * @param alChannelLayout AL channel layout, see {@link #getDefaultALChannelLayout(int)}
+     * @param alSampleType AL sample type, see {@link #getALSampleType(int, boolean, boolean)}.
      * @param al AL instance
      * @param alExt ALExt instance
      * @return AL buffer format
      */
     public static final int getALFormat(final int alChannelLayout, final int alSampleType,
+                                        final AL al, final ALExt alExt) {
+        final boolean hasSOFTBufferSamples = al.alIsExtensionPresent(AL_SOFT_buffer_samples);
+        final boolean hasEXTMcFormats = al.alIsExtensionPresent(AL_EXT_MCFORMATS);
+        final boolean hasEXTFloat32 = al.alIsExtensionPresent(AL_EXT_FLOAT32);
+        final boolean hasEXTDouble = al.alIsExtensionPresent(AL_EXT_DOUBLE);
+        return ALHelpers.getALFormat(alChannelLayout, alSampleType, al, alExt,
+                                     hasSOFTBufferSamples, hasEXTMcFormats,
+                                     hasEXTFloat32, hasEXTDouble);
+    }
+
+    /**
+     * Returns a compatible AL buffer format given the AL channel layout and AL sample type.
+     * <p>
+     * If <code>hasEXTMcFormats</code> or <code>hasSOFTBufferSamples</code> is true,
+     * it will be called to find the closest-matching format from
+     * <code>AL_EXT_MCFORMATS</code> or <code>AL_SOFT_buffer_samples</code>.
+     * </p>
+     * <p>
+     * Returns {@link ALConstants#AL_NONE} if no supported format can be found.
+     * </p>
+     * <p>
+     * Function is context independent.
+     * </p>
+     *
+     * @param alChannelLayout AL channel layout, see {@link #getDefaultALChannelLayout(int)}
+     * @param alSampleType AL sample type, see {@link #getALSampleType(int, boolean, boolean)}.
+     * @param al AL instance
+     * @param alExt ALExt instance
+     * @param hasSOFTBufferSamples true if having extension <code>AL_SOFT_buffer_samples</code>, otherwise false
+     * @param hasEXTMcFormats true if having extension <code>AL_EXT_MCFORMATS</code>, otherwise false
+     * @param hasEXTFloat32 true if having extension <code>AL_EXT_FLOAT32</code>, otherwise false
+     * @param hasEXTDouble true if having extension <code>AL_EXT_DOUBLE</code>, otherwise false
+     * @return AL buffer format
+     */
+    public static final int getALFormat(final int alChannelLayout, final int alSampleType,
+                                        final AL al, final ALExt alExt,
                                         final boolean hasSOFTBufferSamples,
                                         final boolean hasEXTMcFormats,
-                                        final boolean hasEXTFloat32,
-                                        final boolean hasEXTDouble,
-                                        final AL al, final ALExt alExt) {
+                                        final boolean hasEXTFloat32, final boolean hasEXTDouble) {
         int format = AL_NONE;
 
         /* If using AL_SOFT_buffer_samples, try looking through its formats */
@@ -262,6 +411,22 @@ public class ALHelpers {
     }
 
     /**
+     * Returns the channel count of the given AL channel layout
+     */
+    public static final int getALChannelLayoutChannelCount(final int alChannelLayout) {
+        switch(alChannelLayout) {
+            case AL_MONO_SOFT: return 1;
+            case AL_STEREO_SOFT: return 2;
+            case AL_REAR_SOFT: return 2;
+            case AL_QUAD_SOFT: return 4;
+            case AL_5POINT1_SOFT: return 6;
+            case AL_6POINT1_SOFT: return 7;
+            case AL_7POINT1_SOFT: return 8;
+        }
+        return 0;
+    }
+
+    /**
      * Returns the AL sample type matching the given audio type attributes, or {@link ALConstants#AL_NONE}.
      * @param sampleSize sample size in bits
      * @param signed true if signed number, false for unsigned
@@ -311,6 +476,45 @@ public class ALHelpers {
     }
 
     /**
+     * Returns whether the given AL sample type is signed
+     */
+    public static final boolean isALSampleTypeSigned(final int alSampleType) {
+        switch(alSampleType) {
+            case AL_BYTE_SOFT:
+            case AL_SHORT_SOFT:
+            case AL_INT_SOFT:
+            case AL_FLOAT_SOFT:
+            case AL_DOUBLE_SOFT:
+                return true;
+            case AL_UNSIGNED_BYTE_SOFT:
+            case AL_UNSIGNED_SHORT_SOFT:
+            case AL_UNSIGNED_INT_SOFT:
+            default:
+                return false;
+        }
+    }
+
+    /**
+     * Returns true if the given AL sample type is a fixed point (byte, short, int, ..)
+     * or false if a floating point type (float, double).
+     */
+    public static final boolean isALSampleTypeFixed(final int alSampleType) {
+        switch(alSampleType) {
+            case AL_BYTE_SOFT:
+            case AL_SHORT_SOFT:
+            case AL_INT_SOFT:
+            case AL_UNSIGNED_BYTE_SOFT:
+            case AL_UNSIGNED_SHORT_SOFT:
+            case AL_UNSIGNED_INT_SOFT:
+                return true;
+            case AL_FLOAT_SOFT:
+            case AL_DOUBLE_SOFT:
+            default:
+                return false;
+        }
+    }
+
+    /**
      * Returns the byte size of the given AL sample type
      * @throws IllegalArgumentException for unknown <code>alChannelLayout</code> or <code>alSampleType</code> values.
      */