Such a mode is therefore meant to be used when audio is playing over stereo wired + * headphones or headsets, but also stereo headphones through a wireless A2DP Bluetooth link. + *
See {@link #canVirtualize(int, int)} to verify this mode is supported by this Virtualizer. + */ + public final static int VIRTUALIZATION_MODE_BINAURAL = 2; + + /** + * A virtualization mode typically used over speakers. + * Transaural virtualization describes an audio processing configuration that differs from + * binaural (as described in {@link #VIRTUALIZATION_MODE_BINAURAL} in that cross-talk is + * present, i.e. audio played from the left channel also reaches the right ear of the user, + * and vice-versa. + *
When supported, such a mode is therefore meant to be used when audio is playing over the + * built-in stereo speakers of a device, if they are featured. + *
See {@link #canVirtualize(int, int)} to verify this mode is supported by this Virtualizer.
+ */
+ public final static int VIRTUALIZATION_MODE_TRANSAURAL = 3;
+
+ /** @hide */
+ @IntDef( {
+ VIRTUALIZATION_MODE_BINAURAL,
+ VIRTUALIZATION_MODE_TRANSAURAL
+ })
+ @Retention(RetentionPolicy.SOURCE)
+ public @interface VirtualizationMode {}
+
+ /** @hide */
+ @IntDef( {
+ VIRTUALIZATION_MODE_AUTO,
+ VIRTUALIZATION_MODE_BINAURAL,
+ VIRTUALIZATION_MODE_TRANSAURAL
+ })
+ @Retention(RetentionPolicy.SOURCE)
+ public @interface ForceVirtualizationMode {}
+
+ private static int getDeviceForModeQuery(@VirtualizationMode int virtualizationMode)
+ throws IllegalArgumentException {
+ switch (virtualizationMode) {
+ case VIRTUALIZATION_MODE_BINAURAL:
+ return AudioDevice.TYPE_WIRED_HEADPHONES;
+ case VIRTUALIZATION_MODE_TRANSAURAL:
+ return AudioDevice.TYPE_BUILTIN_SPEAKER;
+ default:
+ throw (new IllegalArgumentException(
+ "Virtualizer: illegal virtualization mode " + virtualizationMode));
+ }
+ }
+
+ private static int getDeviceForModeForce(@ForceVirtualizationMode int virtualizationMode)
+ throws IllegalArgumentException {
+ if (virtualizationMode == VIRTUALIZATION_MODE_AUTO) {
+ return AudioDevice.TYPE_UNKNOWN;
+ } else {
+ return getDeviceForModeQuery(virtualizationMode);
+ }
+ }
+
+ private static int deviceToMode(int deviceType) {
+ switch (deviceType) {
+ case AudioDevice.TYPE_WIRED_HEADSET:
+ case AudioDevice.TYPE_WIRED_HEADPHONES:
+ case AudioDevice.TYPE_BLUETOOTH_SCO:
+ case AudioDevice.TYPE_BUILTIN_EARPIECE:
+ return VIRTUALIZATION_MODE_BINAURAL;
+ case AudioDevice.TYPE_BUILTIN_SPEAKER:
+ case AudioDevice.TYPE_LINE_ANALOG:
+ case AudioDevice.TYPE_LINE_DIGITAL:
+ case AudioDevice.TYPE_BLUETOOTH_A2DP:
+ case AudioDevice.TYPE_HDMI:
+ case AudioDevice.TYPE_HDMI_ARC:
+ case AudioDevice.TYPE_USB_DEVICE:
+ case AudioDevice.TYPE_USB_ACCESSORY:
+ case AudioDevice.TYPE_DOCK:
+ case AudioDevice.TYPE_FM:
+ case AudioDevice.TYPE_AUX_LINE:
+ return VIRTUALIZATION_MODE_TRANSAURAL;
+ case AudioDevice.TYPE_UNKNOWN:
+ default:
+ return VIRTUALIZATION_MODE_OFF;
+ }
+ }
+
+ /**
+ * Checks if the combination of a channel mask and virtualization mode is supported by this
+ * virtualizer.
* Some virtualizer implementations may only support binaural processing (i.e. only support
- * headphone output), some may support transaural processing (i.e. for speaker output) for the
+ * headphone output, see {@link #VIRTUALIZATION_MODE_BINAURAL}), some may support transaural
+ * processing (i.e. for speaker output, see {@link #VIRTUALIZATION_MODE_TRANSAURAL}) for the
* built-in speakers. Use this method to query the virtualizer implementation capabilities.
* @param inputChannelMask the channel mask of the content to virtualize.
- * @param deviceType the device type for which virtualization processing is to be performed.
- * @return true if the combination of channel mask and output device type is supported, false
+ * @param virtualizationMode the mode for which virtualization processing is to be performed,
+ * one of {@link #VIRTUALIZATION_MODE_BINAURAL}, {@link #VIRTUALIZATION_MODE_TRANSAURAL}.
+ * @return true if the combination of channel mask and virtualization mode is supported, false
* otherwise.
*
An indication that a certain channel mask is not supported doesn't necessarily mean
* you cannot play content with that channel mask, it more likely implies the content will
@@ -267,23 +370,23 @@ public class Virtualizer extends AudioEffect {
* @throws IllegalStateException
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
- * FIXME: replace deviceType by virtualization mode
*/
- public boolean canVirtualize(int inputChannelMask, int deviceType)
+ public boolean canVirtualize(int inputChannelMask, @VirtualizationMode int virtualizationMode)
throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
- return getAnglesInt(inputChannelMask, deviceType, null);
+ return getAnglesInt(inputChannelMask, getDeviceForModeQuery(virtualizationMode), null);
}
/**
* Queries the virtual speaker angles (azimuth and elevation) for a combination of a channel
- * mask and device type.
- * If the virtualization configuration (mask and device) is supported (see
+ * mask and virtualization mode.
+ * If the virtualization configuration (mask and mode) is supported (see
* {@link #canVirtualize(int, int)}, the array angles will contain upon return the
* definition of each virtual speaker and its azimuth and elevation angles relative to the
* listener.
*
Note that in some virtualizer implementations, the angles may be strength-dependent.
* @param inputChannelMask the channel mask of the content to virtualize.
- * @param deviceType the device type for which virtualization processing is to be performed.
+ * @param virtualizationMode the mode for which virtualization processing is to be performed,
+ * one of {@link #VIRTUALIZATION_MODE_BINAURAL}, {@link #VIRTUALIZATION_MODE_TRANSAURAL}.
* @param angles a non-null array whose length is 3 times the number of channels in the channel
* mask.
* If the method indicates the configuration is supported, the array will contain upon return
@@ -297,37 +400,39 @@ public class Virtualizer extends AudioEffect {
*
3*i+2 contains its corresponding elevation angle
* where +90 is directly above the listener, 0 is the horizontal plane, and -90 is
* directly below the listener.Note that the return value may differ from a device type successfully set with - * {@link #forceVirtualizationMode(int)} as the implementation - * may use a single mode for multiple devices. + * Return the virtualization mode being used, if any. + * @return the virtualization mode being used. + * If virtualization is not active, the virtualization mode will be + * {@link #VIRTUALIZATION_MODE_OFF}. Otherwise the value will be + * {@link #VIRTUALIZATION_MODE_BINAURAL} or {@link #VIRTUALIZATION_MODE_TRANSAURAL}. + * Virtualization may not be active either because the effect is not enabled or + * because the current output device is not compatible with this virtualization + * implementation. * @throws IllegalStateException - * @throws IllegalArgumentException * @throws UnsupportedOperationException - * FIXME: replace deviceType by virtualization mode */ public int getVirtualizationMode() - throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException { + throws IllegalStateException, UnsupportedOperationException { int[] value = new int[1]; int status = getParameter(PARAM_VIRTUALIZATION_MODE, value); if (status >= 0) { - return AudioDevice.convertInternalDeviceToDeviceType(value[0]); + return deviceToMode(AudioDevice.convertInternalDeviceToDeviceType(value[0])); } else if (status == AudioEffect.ERROR_BAD_VALUE) { - return AudioDevice.TYPE_UNKNOWN; + return VIRTUALIZATION_MODE_OFF; } else { // something wrong may have happened checkStatus(status); @@ -378,7 +480,7 @@ public class Virtualizer extends AudioEffect { // unexpected virtualizer behavior Log.e(TAG, "unexpected status code " + status + " after getParameter(PARAM_VIRTUALIZATION_MODE)"); - return AudioDevice.TYPE_UNKNOWN; + return VIRTUALIZATION_MODE_OFF; } /**