Various fixes and improvements in audio effects implementation

Effect API:
- Use different definitions for audio device, channels, formats... in AudioSystem and EffectApi:
  Removed media/AudioCommon.h file created for initial version of EffectApi
- Indicate audio session and output ID to effect library when calling EffectCreate(). Session ID can be useful to optimize
the implementation of effect chains in the same audio session. Output ID can be used for effects implemented in audio hardware.
- Renamed EffectQueryNext() function to EffectQueryEffect() and changed operating mode:
  now an index is passed for the queried effect instead of implicitly querying the next one.
- Added CPU load and memory usage indication in effects descriptor
- Added flags and commands to indicate changes in audio mode (ring tone, in call...) to effect engine
- Added flag to indicate hardware accelerated effect implementation.
- Renamed EffectFactoryApi.h to EffectsFactoryApi.h for consistency with EffectsFactory.c/h

Effect libraries:
- Reflected changes in Effect API
- Several fixes in reverb implementation
- Added build option TEST_EFFECT_LIBRARIES in makefile to prepare integration of actual effect library.
- Replaced pointer by integer identifier for library handle returned by effects factory

Audio effect framework:
- Added support for audio session -1 in preparation of output stage effects configuration.
- Reflected changes in Effect API
- Removed volume ramp up/down when effect is inserted/removed: this has to be taken care of by effect engines.
- Added some overflow verification on indexes used for deferred parameter updates via shared memory
- Added hardcoded CPU and memory limit check when creating a new effect instance

Change-Id: I43fee5182ee201384ea3479af6d0acb95092901d

1 files changed, 221 insertions, 0 deletions

diff --git a/include/media/EffectsFactoryApi.h b/include/media/EffectsFactoryApi.h
new file mode 100644
index 0000000..0ed1a14
--- /dev/null
+++ b/include/media/EffectsFactoryApi.h
@@ -0,0 +1,221 @@
+/*
+ * 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.
+ */
+
+#ifndef ANDROID_EFFECTSFACTORYAPI_H_
+#define ANDROID_EFFECTSFACTORYAPI_H_
+
+#include <errno.h>
+#include <stdint.h>
+#include <sys/types.h>
+#include <media/EffectApi.h>
+
+#if __cplusplus
+extern "C" {
+#endif
+
+/////////////////////////////////////////////////
+//      Effect factory interface
+/////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//    Function:       EffectQueryNumberEffects
+//
+//    Description:    Returns the number of different effects in all loaded libraries.
+//          Each effect must have a different effect uuid (see
+//          effect_descriptor_t). This function together with EffectQueryEffect()
+//          is used to enumerate all effects present in all loaded libraries.
+//          Each time EffectQueryNumberEffects() is called, the factory must
+//          reset the index of the effect descriptor returned by next call to
+//          EffectQueryEffect() to restart enumeration from the beginning.
+//
+//    Input/Output:
+//          pNumEffects:    address where the number of effects should be returned.
+//
+//    Output:
+//        returned value:    0          successful operation.
+//                          -ENODEV     factory failed to initialize
+//                          -EINVAL     invalid pNumEffects
+//        *pNumEffects:     updated with number of effects in factory
+//
+////////////////////////////////////////////////////////////////////////////////
+int EffectQueryNumberEffects(uint32_t *pNumEffects);
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//    Function:       EffectQueryEffect
+//
+//    Description:    Returns a descriptor of the next available effect.
+//          See effect_descriptor_t for a details on effect descriptor.
+//          This function together with EffectQueryNumberEffects() is used to enumerate all
+//          effects present in all loaded libraries. The enumeration sequence is:
+//              EffectQueryNumberEffects(&num_effects);
+//              for (i = 0; i < num_effects; i++)
+//                  EffectQueryEffect(i,...);
+//
+//    Input/Output:
+//          pDescriptor:    address where to return the effect descriptor.
+//
+//    Output:
+//        returned value:    0          successful operation.
+//                          -ENOENT     no more effect available
+//                          -ENODEV     factory failed to initialize
+//                          -EINVAL     invalid pDescriptor
+//                          -ENOSYS     effect list has changed since last execution of EffectQueryNumberEffects()
+//        *pDescriptor:     updated with the effect descriptor.
+//
+////////////////////////////////////////////////////////////////////////////////
+int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor);
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//    Function:       EffectCreate
+//
+//    Description:    Creates an effect engine of the specified type and returns an
+//          effect control interface on this engine. The function will allocate the
+//          resources for an instance of the requested effect engine and return
+//          a handler on the effect control interface.
+//
+//    Input:
+//          pEffectUuid:    pointer to the effect uuid.
+//          sessionId:  audio session to which this effect instance will be attached. All effects created
+//              with the same session ID are connected in series and process the same signal stream.
+//              Knowing that two effects are part of the same effect chain can help the library implement
+//              some kind of optimizations.
+//          ioId:   identifies the output or input stream this effect is directed to at audio HAL. For future
+//              use especially with tunneled HW accelerated effects
+//
+//    Input/Output:
+//          pInterface:    address where to return the effect interface.
+//
+//    Output:
+//        returned value:    0          successful operation.
+//                          -ENODEV     factory failed to initialize
+//                          -EINVAL     invalid pEffectUuid or pInterface
+//                          -ENOENT     no effect with this uuid found
+//        *pInterface:     updated with the effect interface.
+//
+////////////////////////////////////////////////////////////////////////////////
+int EffectCreate(effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, effect_interface_t *pInterface);
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//    Function:       EffectRelease
+//
+//    Description:    Releases the effect engine whose handler is given as argument.
+//          All resources allocated to this particular instance of the effect are
+//          released.
+//
+//    Input:
+//          interface:    handler on the effect interface to be released.
+//
+//    Output:
+//        returned value:    0          successful operation.
+//                          -ENODEV     factory failed to initialize
+//                          -EINVAL     invalid interface handler
+//
+////////////////////////////////////////////////////////////////////////////////
+int EffectRelease(effect_interface_t interface);
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//    Function:       EffectLoadLibrary
+//
+//    Description:    Loads the effect library which path is given as first argument.
+//          This must be the full path of a dynamic library (.so) implementing one or
+//          more effect engines and exposing the effect library interface described in
+//          EffectApi.h. The function returns a handle on the library for used by
+//          further call to EffectUnloadLibrary() to unload the library.
+//
+//    Input:
+//          libPath:    full path of the dynamic library file in the file system.
+//
+//          handle:     address where to return the library handle
+//
+//    Output:
+//        returned value:    0          successful operation.
+//                          -ENODEV     effect factory not initialized or
+//                                      library could not be loaded or
+//                                      library does not implement required functions
+//                          -EINVAL     invalid libPath string or handle
+//
+////////////////////////////////////////////////////////////////////////////////
+int EffectLoadLibrary(const char *libPath, int *handle);
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//    Function:       EffectUnloadLibrary
+//
+//    Description:  Unloads the effect library which handle is given as argument.
+//
+//    Input:
+//          handle: library handle
+//
+//    Output:
+//        returned value:    0          successful operation.
+//                          -ENODEV     effect factory not initialized
+//                          -ENOENT     invalid handle
+//
+////////////////////////////////////////////////////////////////////////////////
+int EffectUnloadLibrary(int handle);
+
+
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//    Function:       EffectGetDescriptor
+//
+//    Description:    Returns the descriptor of the effect which uuid is pointed
+//          to by first argument.
+//
+//    Input:
+//          pEffectUuid:    pointer to the effect uuid.
+//
+//    Input/Output:
+//          pDescriptor:    address where to return the effect descriptor.
+//
+//    Output:
+//        returned value:    0          successful operation.
+//                          -ENODEV     factory failed to initialize
+//                          -EINVAL     invalid pEffectUuid or pDescriptor
+//                          -ENOENT     no effect with this uuid found
+//        *pDescriptor:     updated with the effect descriptor.
+//
+////////////////////////////////////////////////////////////////////////////////
+int EffectGetDescriptor(effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor);
+
+////////////////////////////////////////////////////////////////////////////////
+//
+//    Function:       EffectIsNullUuid
+//
+//    Description:    Helper function to compare effect uuid to EFFECT_UUID_NULL
+//
+//    Input:
+//          pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL.
+//
+//    Output:
+//        returned value:    0 if uuid is different from EFFECT_UUID_NULL.
+//                           1 if uuid is equal to EFFECT_UUID_NULL.
+//
+////////////////////////////////////////////////////////////////////////////////
+int EffectIsNullUuid(effect_uuid_t *pEffectUuid);
+
+#if __cplusplus
+}  // extern "C"
+#endif
+
+
+#endif /*ANDROID_EFFECTSFACTORYAPI_H_*/