1/* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18#ifndef ANDROID_AUDIO_EFFECT_H 19#define ANDROID_AUDIO_EFFECT_H 20 21#include <errno.h> 22#include <stdint.h> 23#include <strings.h> 24#include <sys/cdefs.h> 25#include <sys/types.h> 26 27#include <cutils/bitops.h> 28 29#include <system/audio_effect.h> 30 31 32__BEGIN_DECLS 33 34 35///////////////////////////////////////////////// 36// Common Definitions 37///////////////////////////////////////////////// 38 39#define EFFECT_MAKE_API_VERSION(M, m) (((M)<<16) | ((m) & 0xFFFF)) 40#define EFFECT_API_VERSION_MAJOR(v) ((v)>>16) 41#define EFFECT_API_VERSION_MINOR(v) ((m) & 0xFFFF) 42 43 44///////////////////////////////////////////////// 45// Effect control interface 46///////////////////////////////////////////////// 47 48// Effect control interface version 2.0 49#define EFFECT_CONTROL_API_VERSION EFFECT_MAKE_API_VERSION(2,0) 50 51// Effect control interface structure: effect_interface_s 52// The effect control interface is exposed by each effect engine implementation. It consists of 53// a set of functions controlling the configuration, activation and process of the engine. 54// The functions are grouped in a structure of type effect_interface_s. 55// 56// Effect control interface handle: effect_handle_t 57// The effect_handle_t serves two purposes regarding the implementation of the effect engine: 58// - 1 it is the address of a pointer to an effect_interface_s structure where the functions 59// of the effect control API for a particular effect are located. 60// - 2 it is the address of the context of a particular effect instance. 61// A typical implementation in the effect library would define a structure as follows: 62// struct effect_module_s { 63// const struct effect_interface_s *itfe; 64// effect_config_t config; 65// effect_context_t context; 66// } 67// The implementation of EffectCreate() function would then allocate a structure of this 68// type and return its address as effect_handle_t 69typedef struct effect_interface_s **effect_handle_t; 70 71// Effect control interface definition 72struct effect_interface_s { 73 //////////////////////////////////////////////////////////////////////////////// 74 // 75 // Function: process 76 // 77 // Description: Effect process function. Takes input samples as specified 78 // (count and location) in input buffer descriptor and output processed 79 // samples as specified in output buffer descriptor. If the buffer descriptor 80 // is not specified the function must use either the buffer or the 81 // buffer provider function installed by the EFFECT_CMD_SET_CONFIG command. 82 // The effect framework will call the process() function after the EFFECT_CMD_ENABLE 83 // command is received and until the EFFECT_CMD_DISABLE is received. When the engine 84 // receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully 85 // and when done indicate that it is OK to stop calling the process() function by 86 // returning the -ENODATA status. 87 // 88 // NOTE: the process() function implementation should be "real-time safe" that is 89 // it should not perform blocking calls: malloc/free, sleep, read/write/open/close, 90 // pthread_cond_wait/pthread_mutex_lock... 91 // 92 // Input: 93 // self: handle to the effect interface this function 94 // is called on. 95 // inBuffer: buffer descriptor indicating where to read samples to process. 96 // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. 97 // 98 // outBuffer: buffer descriptor indicating where to write processed samples. 99 // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. 100 // 101 // Output: 102 // returned value: 0 successful operation 103 // -ENODATA the engine has finished the disable phase and the framework 104 // can stop calling process() 105 // -EINVAL invalid interface handle or 106 // invalid input/output buffer description 107 //////////////////////////////////////////////////////////////////////////////// 108 int32_t (*process)(effect_handle_t self, 109 audio_buffer_t *inBuffer, 110 audio_buffer_t *outBuffer); 111 //////////////////////////////////////////////////////////////////////////////// 112 // 113 // Function: command 114 // 115 // Description: Send a command and receive a response to/from effect engine. 116 // 117 // Input: 118 // self: handle to the effect interface this function 119 // is called on. 120 // cmdCode: command code: the command can be a standardized command defined in 121 // effect_command_e (see below) or a proprietary command. 122 // cmdSize: size of command in bytes 123 // pCmdData: pointer to command data 124 // pReplyData: pointer to reply data 125 // 126 // Input/Output: 127 // replySize: maximum size of reply data as input 128 // actual size of reply data as output 129 // 130 // Output: 131 // returned value: 0 successful operation 132 // -EINVAL invalid interface handle or 133 // invalid command/reply size or format according to 134 // command code 135 // The return code should be restricted to indicate problems related to this API 136 // specification. Status related to the execution of a particular command should be 137 // indicated as part of the reply field. 138 // 139 // *pReplyData updated with command response 140 // 141 //////////////////////////////////////////////////////////////////////////////// 142 int32_t (*command)(effect_handle_t self, 143 uint32_t cmdCode, 144 uint32_t cmdSize, 145 void *pCmdData, 146 uint32_t *replySize, 147 void *pReplyData); 148 //////////////////////////////////////////////////////////////////////////////// 149 // 150 // Function: get_descriptor 151 // 152 // Description: Returns the effect descriptor 153 // 154 // Input: 155 // self: handle to the effect interface this function 156 // is called on. 157 // 158 // Input/Output: 159 // pDescriptor: address where to return the effect descriptor. 160 // 161 // Output: 162 // returned value: 0 successful operation. 163 // -EINVAL invalid interface handle or invalid pDescriptor 164 // *pDescriptor: updated with the effect descriptor. 165 // 166 //////////////////////////////////////////////////////////////////////////////// 167 int32_t (*get_descriptor)(effect_handle_t self, 168 effect_descriptor_t *pDescriptor); 169 //////////////////////////////////////////////////////////////////////////////// 170 // 171 // Function: process_reverse 172 // 173 // Description: Process reverse stream function. This function is used to pass 174 // a reference stream to the effect engine. If the engine does not need a reference 175 // stream, this function pointer can be set to NULL. 176 // This function would typically implemented by an Echo Canceler. 177 // 178 // Input: 179 // self: handle to the effect interface this function 180 // is called on. 181 // inBuffer: buffer descriptor indicating where to read samples to process. 182 // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. 183 // 184 // outBuffer: buffer descriptor indicating where to write processed samples. 185 // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. 186 // If the buffer and buffer provider in the configuration received by 187 // EFFECT_CMD_SET_CONFIG_REVERSE are also NULL, do not return modified reverse 188 // stream data 189 // 190 // Output: 191 // returned value: 0 successful operation 192 // -ENODATA the engine has finished the disable phase and the framework 193 // can stop calling process_reverse() 194 // -EINVAL invalid interface handle or 195 // invalid input/output buffer description 196 //////////////////////////////////////////////////////////////////////////////// 197 int32_t (*process_reverse)(effect_handle_t self, 198 audio_buffer_t *inBuffer, 199 audio_buffer_t *outBuffer); 200}; 201 202///////////////////////////////////////////////// 203// Effect library interface 204///////////////////////////////////////////////// 205 206// Effect library interface version 3.0 207// Note that EffectsFactory.c only checks the major version component, so changes to the minor 208// number can only be used for fully backwards compatible changes 209#define EFFECT_LIBRARY_API_VERSION EFFECT_MAKE_API_VERSION(3,0) 210 211#define AUDIO_EFFECT_LIBRARY_TAG ((('A') << 24) | (('E') << 16) | (('L') << 8) | ('T')) 212 213// Every effect library must have a data structure named AUDIO_EFFECT_LIBRARY_INFO_SYM 214// and the fields of this data structure must begin with audio_effect_library_t 215 216typedef struct audio_effect_library_s { 217 // tag must be initialized to AUDIO_EFFECT_LIBRARY_TAG 218 uint32_t tag; 219 // Version of the effect library API : 0xMMMMmmmm MMMM: Major, mmmm: minor 220 uint32_t version; 221 // Name of this library 222 const char *name; 223 // Author/owner/implementor of the library 224 const char *implementor; 225 226 //////////////////////////////////////////////////////////////////////////////// 227 // 228 // Function: create_effect 229 // 230 // Description: Creates an effect engine of the specified implementation uuid and 231 // returns an effect control interface on this engine. The function will allocate the 232 // resources for an instance of the requested effect engine and return 233 // a handle on the effect control interface. 234 // 235 // Input: 236 // uuid: pointer to the effect uuid. 237 // sessionId: audio session to which this effect instance will be attached. 238 // All effects created with the same session ID are connected in series and process 239 // the same signal stream. Knowing that two effects are part of the same effect 240 // chain can help the library implement some kind of optimizations. 241 // ioId: identifies the output or input stream this effect is directed to in 242 // audio HAL. 243 // For future use especially with tunneled HW accelerated effects 244 // 245 // Input/Output: 246 // pHandle: address where to return the effect interface handle. 247 // 248 // Output: 249 // returned value: 0 successful operation. 250 // -ENODEV library failed to initialize 251 // -EINVAL invalid pEffectUuid or pHandle 252 // -ENOENT no effect with this uuid found 253 // *pHandle: updated with the effect interface handle. 254 // 255 //////////////////////////////////////////////////////////////////////////////// 256 int32_t (*create_effect)(const effect_uuid_t *uuid, 257 int32_t sessionId, 258 int32_t ioId, 259 effect_handle_t *pHandle); 260 261 //////////////////////////////////////////////////////////////////////////////// 262 // 263 // Function: release_effect 264 // 265 // Description: Releases the effect engine whose handle is given as argument. 266 // All resources allocated to this particular instance of the effect are 267 // released. 268 // 269 // Input: 270 // handle: handle on the effect interface to be released. 271 // 272 // Output: 273 // returned value: 0 successful operation. 274 // -ENODEV library failed to initialize 275 // -EINVAL invalid interface handle 276 // 277 //////////////////////////////////////////////////////////////////////////////// 278 int32_t (*release_effect)(effect_handle_t handle); 279 280 //////////////////////////////////////////////////////////////////////////////// 281 // 282 // Function: get_descriptor 283 // 284 // Description: Returns the descriptor of the effect engine which implementation UUID is 285 // given as argument. 286 // 287 // Input/Output: 288 // uuid: pointer to the effect uuid. 289 // pDescriptor: address where to return the effect descriptor. 290 // 291 // Output: 292 // returned value: 0 successful operation. 293 // -ENODEV library failed to initialize 294 // -EINVAL invalid pDescriptor or uuid 295 // *pDescriptor: updated with the effect descriptor. 296 // 297 //////////////////////////////////////////////////////////////////////////////// 298 int32_t (*get_descriptor)(const effect_uuid_t *uuid, 299 effect_descriptor_t *pDescriptor); 300} audio_effect_library_t; 301 302// Name of the hal_module_info 303#define AUDIO_EFFECT_LIBRARY_INFO_SYM AELI 304 305// Name of the hal_module_info as a string 306#define AUDIO_EFFECT_LIBRARY_INFO_SYM_AS_STR "AELI" 307 308__END_DECLS 309 310#endif // ANDROID_AUDIO_EFFECT_H 311