content: /*
   * Copyright (C) 2010 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.media.audiofx;
  
  import android.media.audiofx.AudioEffect;
  import java.util.StringTokenizer;
  
  
  /**
   * A sound generated within a room travels in many directions. The listener first hears the
   * direct sound from the source itself. Later, he or she hears discrete echoes caused by sound
   * bouncing off nearby walls, the ceiling and the floor. As sound waves arrive after
   * undergoing more and more reflections, individual reflections become indistinguishable and
   * the listener hears continuous reverberation that decays over time.
   * Reverb is vital for modeling a listener's environment. It can be used in music applications
   * to simulate music being played back in various environments, or in games to immerse the
   * listener within the game's environment.
   * The PresetReverb class allows an application to configure the global reverb using a reverb preset.
   * This is primarily used for adding some reverb in a music playback context. Applications
   * requiring control over a more advanced environmental reverb are advised to use the
   * {@link android.media.audiofx.EnvironmentalReverb} class.
   * <p>An application creates a PresetReverb object to instantiate and control a reverb engine in the
   * audio framework.
   * <p>The methods, parameter types and units exposed by the PresetReverb implementation are
   * directly mapping those defined by the OpenSL ES 1.0.1 Specification
   * (http://www.khronos.org/opensles/) for the SLPresetReverbItf interface.
   * Please refer to this specification for more details.
   * <p>The PresetReverb is an output mix auxiliary effect and should be created on
   * Audio session 0. In order for a MediaPlayer or AudioTrack to be fed into this effect,
   * they must be explicitely attached to it and a send level must be specified. Use the effect ID
   * returned by getId() method to designate this particular effect when attaching it to the
   * MediaPlayer or AudioTrack.
   * <p>Creating a reverb on the output mix (audio session 0) requires permission
   * {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}
   * <p>See {@link android.media.audiofx.AudioEffect} class for more details on controlling
   * audio effects.
   */
  
  public class PresetReverb extends AudioEffect {
  
      private final static String TAG = "PresetReverb";
  
      // These constants must be synchronized with those in
      // frameworks/base/include/media/EffectPresetReverbApi.h
  
      /**
       * Preset. Parameter ID for
       * {@link android.media.audiofx.PresetReverb.OnParameterChangeListener}
       */
      public static final int PARAM_PRESET = 0;
  
      /**
       * No reverb or reflections
       */
      public static final short PRESET_NONE        = 0;
      /**
       * Reverb preset representing a small room less than five meters in length
       */
      public static final short PRESET_SMALLROOM   = 1;
      /**
       * Reverb preset representing a medium room with a length of ten meters or less
       */
      public static final short PRESET_MEDIUMROOM  = 2;
      /**
       * Reverb preset representing a large-sized room suitable for live performances
       */
      public static final short PRESET_LARGEROOM   = 3;
      /**
       * Reverb preset representing a medium-sized hall
       */
      public static final short PRESET_MEDIUMHALL  = 4;
      /**
       * Reverb preset representing a large-sized hall suitable for a full orchestra
       */
      public static final short PRESET_LARGEHALL   = 5;
      /**
       * Reverb preset representing a synthesis of the traditional plate reverb
       */
      public static final short PRESET_PLATE       = 6;
  
      /**
       * Registered listener for parameter changes.
       */
      private OnParameterChangeListener mParamListener = null;
  
      /**
       * Listener used internally to to receive raw parameter change event from AudioEffect super class
       */
      private BaseParameterListener mBaseParamListener = null;
  
      /**
       * Lock for access to mParamListener
       */
      private final Object mParamListenerLock = new Object();
  
      /**
       * Class constructor.
       * @param priority the priority level requested by the application for controlling the
       * PresetReverb engine. As the same engine can be shared by several applications, this
       * parameter indicates how much the requesting application needs control of effect parameters.
       * The normal priority is 0, above normal is a positive number, below normal a negative number.
       * @param audioSession  system wide unique audio session identifier. If audioSession
       *  is not 0, the PresetReverb will be attached to the MediaPlayer or AudioTrack in the
       *  same audio session. Otherwise, the PresetReverb will apply to the output mix.
       *  As the PresetReverb is an auxiliary effect it is recommended to instantiate it on
       *  audio session 0 and to attach it to the MediaPLayer auxiliary output.
       *
       * @throws java.lang.IllegalArgumentException
       * @throws java.lang.UnsupportedOperationException
       * @throws java.lang.RuntimeException
       */
      public PresetReverb(int priority, int audioSession)
      throws IllegalArgumentException, UnsupportedOperationException, RuntimeException {
          super(EFFECT_TYPE_PRESET_REVERB, EFFECT_TYPE_NULL, priority, audioSession);
      }
  
      /**
       *  Enables a preset on the reverb.
       *  <p>The reverb PRESET_NONE disables any reverb from the current output but does not free the
       *  resources associated with the reverb. For an application to signal to the implementation
       *  to free the resources, it must call the release() method.
       * @param preset this must be one of the the preset constants defined in this class.
       * e.g. {@link #PRESET_SMALLROOM}
       * @throws IllegalStateException
       * @throws IllegalArgumentException
       * @throws UnsupportedOperationException
       */
      public void setPreset(short preset)
      throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
          checkStatus(setParameter(PARAM_PRESET, preset));
      }
  
      /**
       * Gets current reverb preset.
       * @return the preset that is set at the moment.
       * @throws IllegalStateException
       * @throws IllegalArgumentException
       * @throws UnsupportedOperationException
       */
      public short getPreset()
      throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
          short[] value = new short[1];
          checkStatus(getParameter(PARAM_PRESET, value));
          return value[0];
      }
  
      /**
       * The OnParameterChangeListener interface defines a method called by the PresetReverb
       * when a parameter value has changed.
       */
      public interface OnParameterChangeListener  {
          /**
           * Method called when a parameter value has changed. The method is called only if the
           * parameter was changed by another application having the control of the same
           * PresetReverb engine.
           * @param effect the PresetReverb on which the interface is registered.
           * @param status status of the set parameter operation.
           * @param param ID of the modified parameter. See {@link #PARAM_PRESET} ...
           * @param value the new parameter value.
           */
          void onParameterChange(PresetReverb effect, int status, int param, short value);
      }
  
      /**
       * Listener used internally to receive unformatted parameter change events from AudioEffect
       * super class.
       */
      private class BaseParameterListener implements AudioEffect.OnParameterChangeListener {
          private BaseParameterListener() {
  
          }
          public void onParameterChange(AudioEffect effect, int status, byte[] param, byte[] value) {
              OnParameterChangeListener l = null;
  
              synchronized (mParamListenerLock) {
                  if (mParamListener != null) {
                      l = mParamListener;
                  }
              }
              if (l != null) {
                  int p = -1;
                  short v = -1;
  
                  if (param.length == 4) {
                      p = byteArrayToInt(param, 0);
                  }
                  if (value.length == 2) {
                      v = byteArrayToShort(value, 0);
                  }
                  if (p != -1 && v != -1) {
                      l.onParameterChange(PresetReverb.this, status, p, v);
                  }
              }
          }
      }
  
      /**
       * Registers an OnParameterChangeListener interface.
       * @param listener OnParameterChangeListener interface registered
       */
      public void setParameterListener(OnParameterChangeListener listener) {
          synchronized (mParamListenerLock) {
              if (mParamListener == null) {
                  mParamListener = listener;
                  mBaseParamListener = new BaseParameterListener();
                  super.setParameterListener(mBaseParamListener);
              }
          }
      }
  
      /**
       * The Settings class regroups all preset reverb parameters. It is used in
       * conjuntion with getProperties() and setProperties() methods to backup and restore
       * all parameters in a single call.
       */
      public static class Settings {
          public short preset;
  
          public Settings() {
          }
  
          /**
           * Settings class constructor from a key=value; pairs formatted string. The string is
           * typically returned by Settings.toString() method.
           * @throws IllegalArgumentException if the string is not correctly formatted.
           */
          public Settings(String settings) {
              StringTokenizer st = new StringTokenizer(settings, "=;");
              int tokens = st.countTokens();
              if (st.countTokens() != 3) {
                  throw new IllegalArgumentException("settings: " + settings);
              }
              String key = st.nextToken();
              if (!key.equals("PresetReverb")) {
                  throw new IllegalArgumentException(
                          "invalid settings for PresetReverb: " + key);
              }
              try {
                  key = st.nextToken();
                  if (!key.equals("preset")) {
                      throw new IllegalArgumentException("invalid key name: " + key);
                  }
                  preset = Short.parseShort(st.nextToken());
               } catch (NumberFormatException nfe) {
                  throw new IllegalArgumentException("invalid value for key: " + key);
              }
          }
  
          @Override
          public String toString() {
              String str = new String (
                      "PresetReverb"+
                      ";preset="+Short.toString(preset)
                      );
              return str;
          }
      };
  
  
      /**
       * Gets the preset reverb properties. This method is useful when a snapshot of current
       * preset reverb settings must be saved by the application.
       * @return a PresetReverb.Settings object containing all current parameters values
       * @throws IllegalStateException
       * @throws IllegalArgumentException
       * @throws UnsupportedOperationException
       */
      public PresetReverb.Settings getProperties()
      throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
          Settings settings = new Settings();
          short[] value = new short[1];
          checkStatus(getParameter(PARAM_PRESET, value));
          settings.preset = value[0];
          return settings;
      }
  
      /**
       * Sets the preset reverb properties. This method is useful when preset reverb settings have to
       * be applied from a previous backup.
       * @param settings a PresetReverb.Settings object containing the properties to apply
       * @throws IllegalStateException
       * @throws IllegalArgumentException
       * @throws UnsupportedOperationException
       */
      public void setProperties(PresetReverb.Settings settings)
      throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
          checkStatus(setParameter(PARAM_PRESET, settings.preset));
      }
  }
  