310 lines
14 KiB
C
310 lines
14 KiB
C
/*
|
|
* Copyright (C) 2011 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_AUDIO_EFFECT_H
|
|
#define ANDROID_AUDIO_EFFECT_H
|
|
|
|
#include <errno.h>
|
|
#include <stdint.h>
|
|
#include <strings.h>
|
|
#include <sys/cdefs.h>
|
|
#include <sys/types.h>
|
|
|
|
#include <cutils/bitops.h>
|
|
|
|
#include <system/audio_effect.h>
|
|
|
|
|
|
__BEGIN_DECLS
|
|
|
|
|
|
/////////////////////////////////////////////////
|
|
// Common Definitions
|
|
/////////////////////////////////////////////////
|
|
|
|
#define EFFECT_MAKE_API_VERSION(M, m) (((M)<<16) | ((m) & 0xFFFF))
|
|
#define EFFECT_API_VERSION_MAJOR(v) ((v)>>16)
|
|
#define EFFECT_API_VERSION_MINOR(v) ((m) & 0xFFFF)
|
|
|
|
|
|
/////////////////////////////////////////////////
|
|
// Effect control interface
|
|
/////////////////////////////////////////////////
|
|
|
|
// Effect control interface version 2.0
|
|
#define EFFECT_CONTROL_API_VERSION EFFECT_MAKE_API_VERSION(2,0)
|
|
|
|
// Effect control interface structure: effect_interface_s
|
|
// The effect control interface is exposed by each effect engine implementation. It consists of
|
|
// a set of functions controlling the configuration, activation and process of the engine.
|
|
// The functions are grouped in a structure of type effect_interface_s.
|
|
//
|
|
// Effect control interface handle: effect_handle_t
|
|
// The effect_handle_t serves two purposes regarding the implementation of the effect engine:
|
|
// - 1 it is the address of a pointer to an effect_interface_s structure where the functions
|
|
// of the effect control API for a particular effect are located.
|
|
// - 2 it is the address of the context of a particular effect instance.
|
|
// A typical implementation in the effect library would define a structure as follows:
|
|
// struct effect_module_s {
|
|
// const struct effect_interface_s *itfe;
|
|
// effect_config_t config;
|
|
// effect_context_t context;
|
|
// }
|
|
// The implementation of EffectCreate() function would then allocate a structure of this
|
|
// type and return its address as effect_handle_t
|
|
typedef struct effect_interface_s **effect_handle_t;
|
|
|
|
// Effect control interface definition
|
|
struct effect_interface_s {
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Function: process
|
|
//
|
|
// Description: Effect process function. Takes input samples as specified
|
|
// (count and location) in input buffer descriptor and output processed
|
|
// samples as specified in output buffer descriptor. If the buffer descriptor
|
|
// is not specified the function must use either the buffer or the
|
|
// buffer provider function installed by the EFFECT_CMD_SET_CONFIG command.
|
|
// The effect framework will call the process() function after the EFFECT_CMD_ENABLE
|
|
// command is received and until the EFFECT_CMD_DISABLE is received. When the engine
|
|
// receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully
|
|
// and when done indicate that it is OK to stop calling the process() function by
|
|
// returning the -ENODATA status.
|
|
//
|
|
// NOTE: the process() function implementation should be "real-time safe" that is
|
|
// it should not perform blocking calls: malloc/free, sleep, read/write/open/close,
|
|
// pthread_cond_wait/pthread_mutex_lock...
|
|
//
|
|
// Input:
|
|
// self: handle to the effect interface this function
|
|
// is called on.
|
|
// inBuffer: buffer descriptor indicating where to read samples to process.
|
|
// If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command.
|
|
//
|
|
// outBuffer: buffer descriptor indicating where to write processed samples.
|
|
// If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command.
|
|
//
|
|
// Output:
|
|
// returned value: 0 successful operation
|
|
// -ENODATA the engine has finished the disable phase and the framework
|
|
// can stop calling process()
|
|
// -EINVAL invalid interface handle or
|
|
// invalid input/output buffer description
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
int32_t (*process)(effect_handle_t self,
|
|
audio_buffer_t *inBuffer,
|
|
audio_buffer_t *outBuffer);
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Function: command
|
|
//
|
|
// Description: Send a command and receive a response to/from effect engine.
|
|
//
|
|
// Input:
|
|
// self: handle to the effect interface this function
|
|
// is called on.
|
|
// cmdCode: command code: the command can be a standardized command defined in
|
|
// effect_command_e (see below) or a proprietary command.
|
|
// cmdSize: size of command in bytes
|
|
// pCmdData: pointer to command data
|
|
// pReplyData: pointer to reply data
|
|
//
|
|
// Input/Output:
|
|
// replySize: maximum size of reply data as input
|
|
// actual size of reply data as output
|
|
//
|
|
// Output:
|
|
// returned value: 0 successful operation
|
|
// -EINVAL invalid interface handle or
|
|
// invalid command/reply size or format according to
|
|
// command code
|
|
// The return code should be restricted to indicate problems related to this API
|
|
// specification. Status related to the execution of a particular command should be
|
|
// indicated as part of the reply field.
|
|
//
|
|
// *pReplyData updated with command response
|
|
//
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
int32_t (*command)(effect_handle_t self,
|
|
uint32_t cmdCode,
|
|
uint32_t cmdSize,
|
|
void *pCmdData,
|
|
uint32_t *replySize,
|
|
void *pReplyData);
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Function: get_descriptor
|
|
//
|
|
// Description: Returns the effect descriptor
|
|
//
|
|
// Input:
|
|
// self: handle to the effect interface this function
|
|
// is called on.
|
|
//
|
|
// Input/Output:
|
|
// pDescriptor: address where to return the effect descriptor.
|
|
//
|
|
// Output:
|
|
// returned value: 0 successful operation.
|
|
// -EINVAL invalid interface handle or invalid pDescriptor
|
|
// *pDescriptor: updated with the effect descriptor.
|
|
//
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
int32_t (*get_descriptor)(effect_handle_t self,
|
|
effect_descriptor_t *pDescriptor);
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Function: process_reverse
|
|
//
|
|
// Description: Process reverse stream function. This function is used to pass
|
|
// a reference stream to the effect engine. If the engine does not need a reference
|
|
// stream, this function pointer can be set to NULL.
|
|
// This function would typically implemented by an Echo Canceler.
|
|
//
|
|
// Input:
|
|
// self: handle to the effect interface this function
|
|
// is called on.
|
|
// inBuffer: buffer descriptor indicating where to read samples to process.
|
|
// If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command.
|
|
//
|
|
// outBuffer: buffer descriptor indicating where to write processed samples.
|
|
// If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command.
|
|
// If the buffer and buffer provider in the configuration received by
|
|
// EFFECT_CMD_SET_CONFIG_REVERSE are also NULL, do not return modified reverse
|
|
// stream data
|
|
//
|
|
// Output:
|
|
// returned value: 0 successful operation
|
|
// -ENODATA the engine has finished the disable phase and the framework
|
|
// can stop calling process_reverse()
|
|
// -EINVAL invalid interface handle or
|
|
// invalid input/output buffer description
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
int32_t (*process_reverse)(effect_handle_t self,
|
|
audio_buffer_t *inBuffer,
|
|
audio_buffer_t *outBuffer);
|
|
};
|
|
|
|
/////////////////////////////////////////////////
|
|
// Effect library interface
|
|
/////////////////////////////////////////////////
|
|
|
|
// Effect library interface version 3.0
|
|
// Note that EffectsFactory.c only checks the major version component, so changes to the minor
|
|
// number can only be used for fully backwards compatible changes
|
|
#define EFFECT_LIBRARY_API_VERSION EFFECT_MAKE_API_VERSION(3,0)
|
|
|
|
#define AUDIO_EFFECT_LIBRARY_TAG ((('A') << 24) | (('E') << 16) | (('L') << 8) | ('T'))
|
|
|
|
// Every effect library must have a data structure named AUDIO_EFFECT_LIBRARY_INFO_SYM
|
|
// and the fields of this data structure must begin with audio_effect_library_t
|
|
|
|
typedef struct audio_effect_library_s {
|
|
// tag must be initialized to AUDIO_EFFECT_LIBRARY_TAG
|
|
uint32_t tag;
|
|
// Version of the effect library API : 0xMMMMmmmm MMMM: Major, mmmm: minor
|
|
uint32_t version;
|
|
// Name of this library
|
|
const char *name;
|
|
// Author/owner/implementor of the library
|
|
const char *implementor;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Function: create_effect
|
|
//
|
|
// Description: Creates an effect engine of the specified implementation uuid 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 handle on the effect control interface.
|
|
//
|
|
// Input:
|
|
// uuid: 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 in
|
|
// audio HAL.
|
|
// For future use especially with tunneled HW accelerated effects
|
|
//
|
|
// Input/Output:
|
|
// pHandle: address where to return the effect interface handle.
|
|
//
|
|
// Output:
|
|
// returned value: 0 successful operation.
|
|
// -ENODEV library failed to initialize
|
|
// -EINVAL invalid pEffectUuid or pHandle
|
|
// -ENOENT no effect with this uuid found
|
|
// *pHandle: updated with the effect interface handle.
|
|
//
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
int32_t (*create_effect)(const effect_uuid_t *uuid,
|
|
int32_t sessionId,
|
|
int32_t ioId,
|
|
effect_handle_t *pHandle);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Function: release_effect
|
|
//
|
|
// Description: Releases the effect engine whose handle is given as argument.
|
|
// All resources allocated to this particular instance of the effect are
|
|
// released.
|
|
//
|
|
// Input:
|
|
// handle: handle on the effect interface to be released.
|
|
//
|
|
// Output:
|
|
// returned value: 0 successful operation.
|
|
// -ENODEV library failed to initialize
|
|
// -EINVAL invalid interface handle
|
|
//
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
int32_t (*release_effect)(effect_handle_t handle);
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Function: get_descriptor
|
|
//
|
|
// Description: Returns the descriptor of the effect engine which implementation UUID is
|
|
// given as argument.
|
|
//
|
|
// Input/Output:
|
|
// uuid: pointer to the effect uuid.
|
|
// pDescriptor: address where to return the effect descriptor.
|
|
//
|
|
// Output:
|
|
// returned value: 0 successful operation.
|
|
// -ENODEV library failed to initialize
|
|
// -EINVAL invalid pDescriptor or uuid
|
|
// *pDescriptor: updated with the effect descriptor.
|
|
//
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
int32_t (*get_descriptor)(const effect_uuid_t *uuid,
|
|
effect_descriptor_t *pDescriptor);
|
|
} audio_effect_library_t;
|
|
|
|
// Name of the hal_module_info
|
|
#define AUDIO_EFFECT_LIBRARY_INFO_SYM AELI
|
|
|
|
// Name of the hal_module_info as a string
|
|
#define AUDIO_EFFECT_LIBRARY_INFO_SYM_AS_STR "AELI"
|
|
|
|
__END_DECLS
|
|
|
|
#endif // ANDROID_AUDIO_EFFECT_H
|