Commit | Line | Data |
---|---|---|
1e494cf4 JB |
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.h> | |
30 | ||
31 | ||
32 | __BEGIN_DECLS | |
33 | ||
34 | ||
35 | ///////////////////////////////////////////////// | |
36 | // Common Definitions | |
37 | ///////////////////////////////////////////////// | |
38 | ||
39 | // | |
40 | //--- Effect descriptor structure effect_descriptor_t | |
41 | // | |
42 | ||
43 | // Unique effect ID (can be generated from the following site: | |
44 | // http://www.itu.int/ITU-T/asn1/uuid.html) | |
45 | // This format is used for both "type" and "uuid" fields of the effect descriptor structure. | |
46 | // - When used for effect type and the engine is implementing and effect corresponding to a standard | |
47 | // OpenSL ES interface, this ID must be the one defined in OpenSLES_IID.h for that interface. | |
48 | // - When used as uuid, it should be a unique UUID for this particular implementation. | |
49 | typedef struct effect_uuid_s { | |
50 | uint32_t timeLow; | |
51 | uint16_t timeMid; | |
52 | uint16_t timeHiAndVersion; | |
53 | uint16_t clockSeq; | |
54 | uint8_t node[6]; | |
55 | } effect_uuid_t; | |
56 | ||
57 | // Maximum length of character strings in structures defines by this API. | |
58 | #define EFFECT_STRING_LEN_MAX 64 | |
59 | ||
60 | // NULL UUID definition (matches SL_IID_NULL_) | |
61 | #define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \ | |
62 | { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } } | |
63 | static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER; | |
64 | const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_; | |
65 | const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210"; | |
66 | ||
67 | // The effect descriptor contains necessary information to facilitate the enumeration of the effect | |
68 | // engines present in a library. | |
69 | typedef struct effect_descriptor_s { | |
70 | effect_uuid_t type; // UUID of to the OpenSL ES interface implemented by this effect | |
71 | effect_uuid_t uuid; // UUID for this particular implementation | |
72 | uint32_t apiVersion; // Version of the effect control API implemented | |
73 | uint32_t flags; // effect engine capabilities/requirements flags (see below) | |
74 | uint16_t cpuLoad; // CPU load indication (see below) | |
75 | uint16_t memoryUsage; // Data Memory usage (see below) | |
76 | char name[EFFECT_STRING_LEN_MAX]; // human readable effect name | |
77 | char implementor[EFFECT_STRING_LEN_MAX]; // human readable effect implementor name | |
78 | } effect_descriptor_t; | |
79 | ||
80 | // CPU load and memory usage indication: each effect implementation must provide an indication of | |
81 | // its CPU and memory usage for the audio effect framework to limit the number of effects | |
82 | // instantiated at a given time on a given platform. | |
83 | // The CPU load is expressed in 0.1 MIPS units as estimated on an ARM9E core (ARMv5TE) with 0 WS. | |
84 | // The memory usage is expressed in KB and includes only dynamically allocated memory | |
85 | ||
86 | // Definitions for flags field of effect descriptor. | |
87 | // +---------------------------+-----------+----------------------------------- | |
88 | // | description | bits | values | |
89 | // +---------------------------+-----------+----------------------------------- | |
90 | // | connection mode | 0..2 | 0 insert: after track process | |
91 | // | | | 1 auxiliary: connect to track auxiliary | |
92 | // | | | output and use send level | |
93 | // | | | 2 replace: replaces track process function; | |
94 | // | | | must implement SRC, volume and mono to stereo. | |
95 | // | | | 3 pre processing: applied below audio HAL on input | |
96 | // | | | 4 post processing: applied below audio HAL on output | |
97 | // | | | 5 - 7 reserved | |
98 | // +---------------------------+-----------+----------------------------------- | |
99 | // | insertion preference | 3..5 | 0 none | |
100 | // | | | 1 first of the chain | |
101 | // | | | 2 last of the chain | |
102 | // | | | 3 exclusive (only effect in the insert chain) | |
103 | // | | | 4..7 reserved | |
104 | // +---------------------------+-----------+----------------------------------- | |
105 | // | Volume management | 6..8 | 0 none | |
106 | // | | | 1 implements volume control | |
107 | // | | | 2 requires volume indication | |
108 | // | | | 4 reserved | |
109 | // +---------------------------+-----------+----------------------------------- | |
110 | // | Device indication | 9..11 | 0 none | |
111 | // | | | 1 requires device updates | |
112 | // | | | 2, 4 reserved | |
113 | // +---------------------------+-----------+----------------------------------- | |
114 | // | Sample input mode | 12..13 | 1 direct: process() function or EFFECT_CMD_SET_CONFIG | |
115 | // | | | command must specify a buffer descriptor | |
116 | // | | | 2 provider: process() function uses the | |
117 | // | | | bufferProvider indicated by the | |
118 | // | | | EFFECT_CMD_SET_CONFIG command to request input. | |
119 | // | | | buffers. | |
120 | // | | | 3 both: both input modes are supported | |
121 | // +---------------------------+-----------+----------------------------------- | |
122 | // | Sample output mode | 14..15 | 1 direct: process() function or EFFECT_CMD_SET_CONFIG | |
123 | // | | | command must specify a buffer descriptor | |
124 | // | | | 2 provider: process() function uses the | |
125 | // | | | bufferProvider indicated by the | |
126 | // | | | EFFECT_CMD_SET_CONFIG command to request output | |
127 | // | | | buffers. | |
128 | // | | | 3 both: both output modes are supported | |
129 | // +---------------------------+-----------+----------------------------------- | |
130 | // | Hardware acceleration | 16..17 | 0 No hardware acceleration | |
131 | // | | | 1 non tunneled hw acceleration: the process() function | |
132 | // | | | reads the samples, send them to HW accelerated | |
133 | // | | | effect processor, reads back the processed samples | |
134 | // | | | and returns them to the output buffer. | |
135 | // | | | 2 tunneled hw acceleration: the process() function is | |
136 | // | | | transparent. The effect interface is only used to | |
137 | // | | | control the effect engine. This mode is relevant for | |
138 | // | | | global effects actually applied by the audio | |
139 | // | | | hardware on the output stream. | |
140 | // +---------------------------+-----------+----------------------------------- | |
141 | // | Audio Mode indication | 18..19 | 0 none | |
142 | // | | | 1 requires audio mode updates | |
143 | // | | | 2..3 reserved | |
144 | // +---------------------------+-----------+----------------------------------- | |
145 | // | Audio source indication | 20..21 | 0 none | |
146 | // | | | 1 requires audio source updates | |
147 | // | | | 2..3 reserved | |
148 | // +---------------------------+-----------+----------------------------------- | |
149 | ||
150 | // Insert mode | |
151 | #define EFFECT_FLAG_TYPE_SHIFT 0 | |
152 | #define EFFECT_FLAG_TYPE_SIZE 3 | |
153 | #define EFFECT_FLAG_TYPE_MASK (((1 << EFFECT_FLAG_TYPE_SIZE) -1) \ | |
154 | << EFFECT_FLAG_TYPE_SHIFT) | |
155 | #define EFFECT_FLAG_TYPE_INSERT (0 << EFFECT_FLAG_TYPE_SHIFT) | |
156 | #define EFFECT_FLAG_TYPE_AUXILIARY (1 << EFFECT_FLAG_TYPE_SHIFT) | |
157 | #define EFFECT_FLAG_TYPE_REPLACE (2 << EFFECT_FLAG_TYPE_SHIFT) | |
158 | #define EFFECT_FLAG_TYPE_PRE_PROC (3 << EFFECT_FLAG_TYPE_SHIFT) | |
159 | #define EFFECT_FLAG_TYPE_POST_PROC (4 << EFFECT_FLAG_TYPE_SHIFT) | |
160 | ||
161 | // Insert preference | |
162 | #define EFFECT_FLAG_INSERT_SHIFT (EFFECT_FLAG_TYPE_SHIFT + EFFECT_FLAG_TYPE_SIZE) | |
163 | #define EFFECT_FLAG_INSERT_SIZE 3 | |
164 | #define EFFECT_FLAG_INSERT_MASK (((1 << EFFECT_FLAG_INSERT_SIZE) -1) \ | |
165 | << EFFECT_FLAG_INSERT_SHIFT) | |
166 | #define EFFECT_FLAG_INSERT_ANY (0 << EFFECT_FLAG_INSERT_SHIFT) | |
167 | #define EFFECT_FLAG_INSERT_FIRST (1 << EFFECT_FLAG_INSERT_SHIFT) | |
168 | #define EFFECT_FLAG_INSERT_LAST (2 << EFFECT_FLAG_INSERT_SHIFT) | |
169 | #define EFFECT_FLAG_INSERT_EXCLUSIVE (3 << EFFECT_FLAG_INSERT_SHIFT) | |
170 | ||
171 | ||
172 | // Volume control | |
173 | #define EFFECT_FLAG_VOLUME_SHIFT (EFFECT_FLAG_INSERT_SHIFT + EFFECT_FLAG_INSERT_SIZE) | |
174 | #define EFFECT_FLAG_VOLUME_SIZE 3 | |
175 | #define EFFECT_FLAG_VOLUME_MASK (((1 << EFFECT_FLAG_VOLUME_SIZE) -1) \ | |
176 | << EFFECT_FLAG_VOLUME_SHIFT) | |
177 | #define EFFECT_FLAG_VOLUME_CTRL (1 << EFFECT_FLAG_VOLUME_SHIFT) | |
178 | #define EFFECT_FLAG_VOLUME_IND (2 << EFFECT_FLAG_VOLUME_SHIFT) | |
179 | #define EFFECT_FLAG_VOLUME_NONE (0 << EFFECT_FLAG_VOLUME_SHIFT) | |
180 | ||
181 | // Device indication | |
182 | #define EFFECT_FLAG_DEVICE_SHIFT (EFFECT_FLAG_VOLUME_SHIFT + EFFECT_FLAG_VOLUME_SIZE) | |
183 | #define EFFECT_FLAG_DEVICE_SIZE 3 | |
184 | #define EFFECT_FLAG_DEVICE_MASK (((1 << EFFECT_FLAG_DEVICE_SIZE) -1) \ | |
185 | << EFFECT_FLAG_DEVICE_SHIFT) | |
186 | #define EFFECT_FLAG_DEVICE_IND (1 << EFFECT_FLAG_DEVICE_SHIFT) | |
187 | #define EFFECT_FLAG_DEVICE_NONE (0 << EFFECT_FLAG_DEVICE_SHIFT) | |
188 | ||
189 | // Sample input modes | |
190 | #define EFFECT_FLAG_INPUT_SHIFT (EFFECT_FLAG_DEVICE_SHIFT + EFFECT_FLAG_DEVICE_SIZE) | |
191 | #define EFFECT_FLAG_INPUT_SIZE 2 | |
192 | #define EFFECT_FLAG_INPUT_MASK (((1 << EFFECT_FLAG_INPUT_SIZE) -1) \ | |
193 | << EFFECT_FLAG_INPUT_SHIFT) | |
194 | #define EFFECT_FLAG_INPUT_DIRECT (1 << EFFECT_FLAG_INPUT_SHIFT) | |
195 | #define EFFECT_FLAG_INPUT_PROVIDER (2 << EFFECT_FLAG_INPUT_SHIFT) | |
196 | #define EFFECT_FLAG_INPUT_BOTH (3 << EFFECT_FLAG_INPUT_SHIFT) | |
197 | ||
198 | // Sample output modes | |
199 | #define EFFECT_FLAG_OUTPUT_SHIFT (EFFECT_FLAG_INPUT_SHIFT + EFFECT_FLAG_INPUT_SIZE) | |
200 | #define EFFECT_FLAG_OUTPUT_SIZE 2 | |
201 | #define EFFECT_FLAG_OUTPUT_MASK (((1 << EFFECT_FLAG_OUTPUT_SIZE) -1) \ | |
202 | << EFFECT_FLAG_OUTPUT_SHIFT) | |
203 | #define EFFECT_FLAG_OUTPUT_DIRECT (1 << EFFECT_FLAG_OUTPUT_SHIFT) | |
204 | #define EFFECT_FLAG_OUTPUT_PROVIDER (2 << EFFECT_FLAG_OUTPUT_SHIFT) | |
205 | #define EFFECT_FLAG_OUTPUT_BOTH (3 << EFFECT_FLAG_OUTPUT_SHIFT) | |
206 | ||
207 | // Hardware acceleration mode | |
208 | #define EFFECT_FLAG_HW_ACC_SHIFT (EFFECT_FLAG_OUTPUT_SHIFT + EFFECT_FLAG_OUTPUT_SIZE) | |
209 | #define EFFECT_FLAG_HW_ACC_SIZE 2 | |
210 | #define EFFECT_FLAG_HW_ACC_MASK (((1 << EFFECT_FLAG_HW_ACC_SIZE) -1) \ | |
211 | << EFFECT_FLAG_HW_ACC_SHIFT) | |
212 | #define EFFECT_FLAG_HW_ACC_SIMPLE (1 << EFFECT_FLAG_HW_ACC_SHIFT) | |
213 | #define EFFECT_FLAG_HW_ACC_TUNNEL (2 << EFFECT_FLAG_HW_ACC_SHIFT) | |
214 | ||
215 | // Audio mode indication | |
216 | #define EFFECT_FLAG_AUDIO_MODE_SHIFT (EFFECT_FLAG_HW_ACC_SHIFT + EFFECT_FLAG_HW_ACC_SIZE) | |
217 | #define EFFECT_FLAG_AUDIO_MODE_SIZE 2 | |
218 | #define EFFECT_FLAG_AUDIO_MODE_MASK (((1 << EFFECT_FLAG_AUDIO_MODE_SIZE) -1) \ | |
219 | << EFFECT_FLAG_AUDIO_MODE_SHIFT) | |
220 | #define EFFECT_FLAG_AUDIO_MODE_IND (1 << EFFECT_FLAG_AUDIO_MODE_SHIFT) | |
221 | #define EFFECT_FLAG_AUDIO_MODE_NONE (0 << EFFECT_FLAG_AUDIO_MODE_SHIFT) | |
222 | ||
223 | // Audio source indication | |
224 | #define EFFECT_FLAG_AUDIO_SOURCE_SHIFT (EFFECT_FLAG_AUDIO_MODE_SHIFT + EFFECT_FLAG_AUDIO_MODE_SIZE) | |
225 | #define EFFECT_FLAG_AUDIO_SOURCE_SIZE 2 | |
226 | #define EFFECT_FLAG_AUDIO_SOURCE_MASK (((1 << EFFECT_FLAG_AUDIO_SOURCE_SIZE) -1) \ | |
227 | << EFFECT_FLAG_AUDIO_SOURCE_SHIFT) | |
228 | #define EFFECT_FLAG_AUDIO_SOURCE_IND (1 << EFFECT_FLAG_AUDIO_SOURCE_SHIFT) | |
229 | #define EFFECT_FLAG_AUDIO_SOURCE_NONE (0 << EFFECT_FLAG_AUDIO_SOURCE_SHIFT) | |
230 | ||
231 | #define EFFECT_MAKE_API_VERSION(M, m) (((M)<<16) | ((m) & 0xFFFF)) | |
232 | #define EFFECT_API_VERSION_MAJOR(v) ((v)>>16) | |
233 | #define EFFECT_API_VERSION_MINOR(v) ((m) & 0xFFFF) | |
234 | ||
235 | ||
236 | ||
237 | ///////////////////////////////////////////////// | |
238 | // Effect control interface | |
239 | ///////////////////////////////////////////////// | |
240 | ||
241 | // Effect control interface version 2.0 | |
242 | #define EFFECT_CONTROL_API_VERSION EFFECT_MAKE_API_VERSION(2,0) | |
243 | ||
244 | // Effect control interface structure: effect_interface_s | |
245 | // The effect control interface is exposed by each effect engine implementation. It consists of | |
246 | // a set of functions controlling the configuration, activation and process of the engine. | |
247 | // The functions are grouped in a structure of type effect_interface_s. | |
248 | // | |
249 | // Effect control interface handle: effect_handle_t | |
250 | // The effect_handle_t serves two purposes regarding the implementation of the effect engine: | |
251 | // - 1 it is the address of a pointer to an effect_interface_s structure where the functions | |
252 | // of the effect control API for a particular effect are located. | |
253 | // - 2 it is the address of the context of a particular effect instance. | |
254 | // A typical implementation in the effect library would define a structure as follows: | |
255 | // struct effect_module_s { | |
256 | // const struct effect_interface_s *itfe; | |
257 | // effect_config_t config; | |
258 | // effect_context_t context; | |
259 | // } | |
260 | // The implementation of EffectCreate() function would then allocate a structure of this | |
261 | // type and return its address as effect_handle_t | |
262 | typedef struct effect_interface_s **effect_handle_t; | |
263 | ||
264 | ||
265 | // Forward definition of type audio_buffer_t | |
266 | typedef struct audio_buffer_s audio_buffer_t; | |
267 | ||
268 | ||
269 | ||
270 | ||
271 | ||
272 | ||
273 | // Effect control interface definition | |
274 | struct effect_interface_s { | |
275 | //////////////////////////////////////////////////////////////////////////////// | |
276 | // | |
277 | // Function: process | |
278 | // | |
279 | // Description: Effect process function. Takes input samples as specified | |
280 | // (count and location) in input buffer descriptor and output processed | |
281 | // samples as specified in output buffer descriptor. If the buffer descriptor | |
282 | // is not specified the function must use either the buffer or the | |
283 | // buffer provider function installed by the EFFECT_CMD_SET_CONFIG command. | |
284 | // The effect framework will call the process() function after the EFFECT_CMD_ENABLE | |
285 | // command is received and until the EFFECT_CMD_DISABLE is received. When the engine | |
286 | // receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully | |
287 | // and when done indicate that it is OK to stop calling the process() function by | |
288 | // returning the -ENODATA status. | |
289 | // | |
290 | // NOTE: the process() function implementation should be "real-time safe" that is | |
291 | // it should not perform blocking calls: malloc/free, sleep, read/write/open/close, | |
292 | // pthread_cond_wait/pthread_mutex_lock... | |
293 | // | |
294 | // Input: | |
295 | // self: handle to the effect interface this function | |
296 | // is called on. | |
297 | // inBuffer: buffer descriptor indicating where to read samples to process. | |
298 | // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. | |
299 | // | |
300 | // outBuffer: buffer descriptor indicating where to write processed samples. | |
301 | // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. | |
302 | // | |
303 | // Output: | |
304 | // returned value: 0 successful operation | |
305 | // -ENODATA the engine has finished the disable phase and the framework | |
306 | // can stop calling process() | |
307 | // -EINVAL invalid interface handle or | |
308 | // invalid input/output buffer description | |
309 | //////////////////////////////////////////////////////////////////////////////// | |
310 | int32_t (*process)(effect_handle_t self, | |
311 | audio_buffer_t *inBuffer, | |
312 | audio_buffer_t *outBuffer); | |
313 | //////////////////////////////////////////////////////////////////////////////// | |
314 | // | |
315 | // Function: command | |
316 | // | |
317 | // Description: Send a command and receive a response to/from effect engine. | |
318 | // | |
319 | // Input: | |
320 | // self: handle to the effect interface this function | |
321 | // is called on. | |
322 | // cmdCode: command code: the command can be a standardized command defined in | |
323 | // effect_command_e (see below) or a proprietary command. | |
324 | // cmdSize: size of command in bytes | |
325 | // pCmdData: pointer to command data | |
326 | // pReplyData: pointer to reply data | |
327 | // | |
328 | // Input/Output: | |
329 | // replySize: maximum size of reply data as input | |
330 | // actual size of reply data as output | |
331 | // | |
332 | // Output: | |
333 | // returned value: 0 successful operation | |
334 | // -EINVAL invalid interface handle or | |
335 | // invalid command/reply size or format according to command code | |
336 | // The return code should be restricted to indicate problems related to the this | |
337 | // API specification. Status related to the execution of a particular command should be | |
338 | // indicated as part of the reply field. | |
339 | // | |
340 | // *pReplyData updated with command response | |
341 | // | |
342 | //////////////////////////////////////////////////////////////////////////////// | |
343 | int32_t (*command)(effect_handle_t self, | |
344 | uint32_t cmdCode, | |
345 | uint32_t cmdSize, | |
346 | void *pCmdData, | |
347 | uint32_t *replySize, | |
348 | void *pReplyData); | |
349 | //////////////////////////////////////////////////////////////////////////////// | |
350 | // | |
351 | // Function: get_descriptor | |
352 | // | |
353 | // Description: Returns the effect descriptor | |
354 | // | |
355 | // Input: | |
356 | // self: handle to the effect interface this function | |
357 | // is called on. | |
358 | // | |
359 | // Input/Output: | |
360 | // pDescriptor: address where to return the effect descriptor. | |
361 | // | |
362 | // Output: | |
363 | // returned value: 0 successful operation. | |
364 | // -EINVAL invalid interface handle or invalid pDescriptor | |
365 | // *pDescriptor: updated with the effect descriptor. | |
366 | // | |
367 | //////////////////////////////////////////////////////////////////////////////// | |
368 | int32_t (*get_descriptor)(effect_handle_t self, | |
369 | effect_descriptor_t *pDescriptor); | |
370 | //////////////////////////////////////////////////////////////////////////////// | |
371 | // | |
372 | // Function: process_reverse | |
373 | // | |
374 | // Description: Process reverse stream function. This function is used to pass | |
375 | // a reference stream to the effect engine. If the engine does not need a reference | |
376 | // stream, this function pointer can be set to NULL. | |
377 | // This function would typically implemented by an Echo Canceler. | |
378 | // | |
379 | // Input: | |
380 | // self: handle to the effect interface this function | |
381 | // is called on. | |
382 | // inBuffer: buffer descriptor indicating where to read samples to process. | |
383 | // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. | |
384 | // | |
385 | // outBuffer: buffer descriptor indicating where to write processed samples. | |
386 | // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. | |
387 | // If the buffer and buffer provider in the configuration received by | |
388 | // EFFECT_CMD_SET_CONFIG_REVERSE are also NULL, do not return modified reverse | |
389 | // stream data | |
390 | // | |
391 | // Output: | |
392 | // returned value: 0 successful operation | |
393 | // -ENODATA the engine has finished the disable phase and the framework | |
394 | // can stop calling process_reverse() | |
395 | // -EINVAL invalid interface handle or | |
396 | // invalid input/output buffer description | |
397 | //////////////////////////////////////////////////////////////////////////////// | |
398 | int32_t (*process_reverse)(effect_handle_t self, | |
399 | audio_buffer_t *inBuffer, | |
400 | audio_buffer_t *outBuffer); | |
401 | }; | |
402 | ||
403 | ||
404 | // | |
405 | //--- Standardized command codes for command() function | |
406 | // | |
407 | enum effect_command_e { | |
408 | EFFECT_CMD_INIT, // initialize effect engine | |
409 | EFFECT_CMD_SET_CONFIG, // configure effect engine (see effect_config_t) | |
410 | EFFECT_CMD_RESET, // reset effect engine | |
411 | EFFECT_CMD_ENABLE, // enable effect process | |
412 | EFFECT_CMD_DISABLE, // disable effect process | |
413 | EFFECT_CMD_SET_PARAM, // set parameter immediately (see effect_param_t) | |
414 | EFFECT_CMD_SET_PARAM_DEFERRED, // set parameter deferred | |
415 | EFFECT_CMD_SET_PARAM_COMMIT, // commit previous set parameter deferred | |
416 | EFFECT_CMD_GET_PARAM, // get parameter | |
417 | EFFECT_CMD_SET_DEVICE, // set audio device (see audio.h, audio_devices_t) | |
418 | EFFECT_CMD_SET_VOLUME, // set volume | |
419 | EFFECT_CMD_SET_AUDIO_MODE, // set the audio mode (normal, ring, ...) | |
420 | EFFECT_CMD_SET_CONFIG_REVERSE, // configure effect engine reverse stream(see effect_config_t) | |
421 | EFFECT_CMD_SET_INPUT_DEVICE, // set capture device (see audio.h, audio_devices_t) | |
422 | EFFECT_CMD_GET_CONFIG, // read effect engine configuration | |
423 | EFFECT_CMD_GET_CONFIG_REVERSE, // read configure effect engine reverse stream configuration | |
424 | EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS,// get all supported configurations for a feature. | |
425 | EFFECT_CMD_GET_FEATURE_CONFIG, // get current feature configuration | |
426 | EFFECT_CMD_SET_FEATURE_CONFIG, // set current feature configuration | |
427 | EFFECT_CMD_SET_AUDIO_SOURCE, // set the audio source (see audio.h, audio_source_t) | |
428 | EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code | |
429 | }; | |
430 | ||
431 | //================================================================================================== | |
432 | // command: EFFECT_CMD_INIT | |
433 | //-------------------------------------------------------------------------------------------------- | |
434 | // description: | |
435 | // Initialize effect engine: All configurations return to default | |
436 | //-------------------------------------------------------------------------------------------------- | |
437 | // command format: | |
438 | // size: 0 | |
439 | // data: N/A | |
440 | //-------------------------------------------------------------------------------------------------- | |
441 | // reply format: | |
442 | // size: sizeof(int) | |
443 | // data: status | |
444 | //================================================================================================== | |
445 | // command: EFFECT_CMD_SET_CONFIG | |
446 | //-------------------------------------------------------------------------------------------------- | |
447 | // description: | |
448 | // Apply new audio parameters configurations for input and output buffers | |
449 | //-------------------------------------------------------------------------------------------------- | |
450 | // command format: | |
451 | // size: sizeof(effect_config_t) | |
452 | // data: effect_config_t | |
453 | //-------------------------------------------------------------------------------------------------- | |
454 | // reply format: | |
455 | // size: sizeof(int) | |
456 | // data: status | |
457 | //================================================================================================== | |
458 | // command: EFFECT_CMD_RESET | |
459 | //-------------------------------------------------------------------------------------------------- | |
460 | // description: | |
461 | // Reset the effect engine. Keep configuration but resets state and buffer content | |
462 | //-------------------------------------------------------------------------------------------------- | |
463 | // command format: | |
464 | // size: 0 | |
465 | // data: N/A | |
466 | //-------------------------------------------------------------------------------------------------- | |
467 | // reply format: | |
468 | // size: 0 | |
469 | // data: N/A | |
470 | //================================================================================================== | |
471 | // command: EFFECT_CMD_ENABLE | |
472 | //-------------------------------------------------------------------------------------------------- | |
473 | // description: | |
474 | // Enable the process. Called by the framework before the first call to process() | |
475 | //-------------------------------------------------------------------------------------------------- | |
476 | // command format: | |
477 | // size: 0 | |
478 | // data: N/A | |
479 | //-------------------------------------------------------------------------------------------------- | |
480 | // reply format: | |
481 | // size: sizeof(int) | |
482 | // data: status | |
483 | //================================================================================================== | |
484 | // command: EFFECT_CMD_DISABLE | |
485 | //-------------------------------------------------------------------------------------------------- | |
486 | // description: | |
487 | // Disable the process. Called by the framework after the last call to process() | |
488 | //-------------------------------------------------------------------------------------------------- | |
489 | // command format: | |
490 | // size: 0 | |
491 | // data: N/A | |
492 | //-------------------------------------------------------------------------------------------------- | |
493 | // reply format: | |
494 | // size: sizeof(int) | |
495 | // data: status | |
496 | //================================================================================================== | |
497 | // command: EFFECT_CMD_SET_PARAM | |
498 | //-------------------------------------------------------------------------------------------------- | |
499 | // description: | |
500 | // Set a parameter and apply it immediately | |
501 | //-------------------------------------------------------------------------------------------------- | |
502 | // command format: | |
503 | // size: sizeof(effect_param_t) + size of param and value | |
504 | // data: effect_param_t + param + value. See effect_param_t definition below for value offset | |
505 | //-------------------------------------------------------------------------------------------------- | |
506 | // reply format: | |
507 | // size: sizeof(int) | |
508 | // data: status | |
509 | //================================================================================================== | |
510 | // command: EFFECT_CMD_SET_PARAM_DEFERRED | |
511 | //-------------------------------------------------------------------------------------------------- | |
512 | // description: | |
513 | // Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command | |
514 | //-------------------------------------------------------------------------------------------------- | |
515 | // command format: | |
516 | // size: sizeof(effect_param_t) + size of param and value | |
517 | // data: effect_param_t + param + value. See effect_param_t definition below for value offset | |
518 | //-------------------------------------------------------------------------------------------------- | |
519 | // reply format: | |
520 | // size: 0 | |
521 | // data: N/A | |
522 | //================================================================================================== | |
523 | // command: EFFECT_CMD_SET_PARAM_COMMIT | |
524 | //-------------------------------------------------------------------------------------------------- | |
525 | // description: | |
526 | // Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands | |
527 | //-------------------------------------------------------------------------------------------------- | |
528 | // command format: | |
529 | // size: 0 | |
530 | // data: N/A | |
531 | //-------------------------------------------------------------------------------------------------- | |
532 | // reply format: | |
533 | // size: sizeof(int) | |
534 | // data: status | |
535 | //================================================================================================== | |
536 | // command: EFFECT_CMD_GET_PARAM | |
537 | //-------------------------------------------------------------------------------------------------- | |
538 | // description: | |
539 | // Get a parameter value | |
540 | //-------------------------------------------------------------------------------------------------- | |
541 | // command format: | |
542 | // size: sizeof(effect_param_t) + size of param | |
543 | // data: effect_param_t + param | |
544 | //-------------------------------------------------------------------------------------------------- | |
545 | // reply format: | |
546 | // size: sizeof(effect_param_t) + size of param and value | |
547 | // data: effect_param_t + param + value. See effect_param_t definition below for value offset | |
548 | //================================================================================================== | |
549 | // command: EFFECT_CMD_SET_DEVICE | |
550 | //-------------------------------------------------------------------------------------------------- | |
551 | // description: | |
552 | // Set the rendering device the audio output path is connected to. See audio.h, audio_devices_t | |
553 | // for device values. | |
554 | // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this | |
555 | // command when the device changes | |
556 | //-------------------------------------------------------------------------------------------------- | |
557 | // command format: | |
558 | // size: sizeof(uint32_t) | |
559 | // data: uint32_t | |
560 | //-------------------------------------------------------------------------------------------------- | |
561 | // reply format: | |
562 | // size: 0 | |
563 | // data: N/A | |
564 | //================================================================================================== | |
565 | // command: EFFECT_CMD_SET_VOLUME | |
566 | //-------------------------------------------------------------------------------------------------- | |
567 | // description: | |
568 | // Set and get volume. Used by audio framework to delegate volume control to effect engine. | |
569 | // The effect implementation must set EFFECT_FLAG_VOLUME_IND or EFFECT_FLAG_VOLUME_CTRL flag in | |
570 | // its descriptor to receive this command before every call to process() function | |
571 | // If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return | |
572 | // the volume that should be applied before the effect is processed. The overall volume (the volume | |
573 | // actually applied by the effect engine multiplied by the returned value) should match the value | |
574 | // indicated in the command. | |
575 | //-------------------------------------------------------------------------------------------------- | |
576 | // command format: | |
577 | // size: n * sizeof(uint32_t) | |
578 | // data: volume for each channel defined in effect_config_t for output buffer expressed in | |
579 | // 8.24 fixed point format | |
580 | //-------------------------------------------------------------------------------------------------- | |
581 | // reply format: | |
582 | // size: n * sizeof(uint32_t) / 0 | |
583 | // data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor: | |
584 | // volume for each channel defined in effect_config_t for output buffer expressed in | |
585 | // 8.24 fixed point format | |
586 | // - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor: | |
587 | // N/A | |
588 | // It is legal to receive a null pointer as pReplyData in which case the effect framework has | |
589 | // delegated volume control to another effect | |
590 | //================================================================================================== | |
591 | // command: EFFECT_CMD_SET_AUDIO_MODE | |
592 | //-------------------------------------------------------------------------------------------------- | |
593 | // description: | |
594 | // Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its | |
595 | // descriptor to receive this command when the audio mode changes. | |
596 | //-------------------------------------------------------------------------------------------------- | |
597 | // command format: | |
598 | // size: sizeof(uint32_t) | |
599 | // data: audio_mode_t | |
600 | //-------------------------------------------------------------------------------------------------- | |
601 | // reply format: | |
602 | // size: 0 | |
603 | // data: N/A | |
604 | //================================================================================================== | |
605 | // command: EFFECT_CMD_SET_CONFIG_REVERSE | |
606 | //-------------------------------------------------------------------------------------------------- | |
607 | // description: | |
608 | // Apply new audio parameters configurations for input and output buffers of reverse stream. | |
609 | // An example of reverse stream is the echo reference supplied to an Acoustic Echo Canceler. | |
610 | //-------------------------------------------------------------------------------------------------- | |
611 | // command format: | |
612 | // size: sizeof(effect_config_t) | |
613 | // data: effect_config_t | |
614 | //-------------------------------------------------------------------------------------------------- | |
615 | // reply format: | |
616 | // size: sizeof(int) | |
617 | // data: status | |
618 | //================================================================================================== | |
619 | // command: EFFECT_CMD_SET_INPUT_DEVICE | |
620 | //-------------------------------------------------------------------------------------------------- | |
621 | // description: | |
622 | // Set the capture device the audio input path is connected to. See audio.h, audio_devices_t | |
623 | // for device values. | |
624 | // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this | |
625 | // command when the device changes | |
626 | //-------------------------------------------------------------------------------------------------- | |
627 | // command format: | |
628 | // size: sizeof(uint32_t) | |
629 | // data: uint32_t | |
630 | //-------------------------------------------------------------------------------------------------- | |
631 | // reply format: | |
632 | // size: 0 | |
633 | // data: N/A | |
634 | //================================================================================================== | |
635 | // command: EFFECT_CMD_GET_CONFIG | |
636 | //-------------------------------------------------------------------------------------------------- | |
637 | // description: | |
638 | // Read audio parameters configurations for input and output buffers | |
639 | //-------------------------------------------------------------------------------------------------- | |
640 | // command format: | |
641 | // size: 0 | |
642 | // data: N/A | |
643 | //-------------------------------------------------------------------------------------------------- | |
644 | // reply format: | |
645 | // size: sizeof(effect_config_t) | |
646 | // data: effect_config_t | |
647 | //================================================================================================== | |
648 | // command: EFFECT_CMD_GET_CONFIG_REVERSE | |
649 | //-------------------------------------------------------------------------------------------------- | |
650 | // description: | |
651 | // Read audio parameters configurations for input and output buffers of reverse stream | |
652 | //-------------------------------------------------------------------------------------------------- | |
653 | // command format: | |
654 | // size: 0 | |
655 | // data: N/A | |
656 | //-------------------------------------------------------------------------------------------------- | |
657 | // reply format: | |
658 | // size: sizeof(effect_config_t) | |
659 | // data: effect_config_t | |
660 | //================================================================================================== | |
661 | // command: EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS | |
662 | //-------------------------------------------------------------------------------------------------- | |
663 | // description: | |
664 | // Queries for supported configurations for a particular feature (e.g. get the supported | |
665 | // combinations of main and auxiliary channels for a noise suppressor). | |
666 | // The command parameter is the feature identifier (See effect_feature_e for a list of defined | |
667 | // features) followed by the maximum number of configuration descriptor to return. | |
668 | // The reply is composed of: | |
669 | // - status (uint32_t): | |
670 | // - 0 if feature is supported | |
671 | // - -ENOSYS if the feature is not supported, | |
672 | // - -ENOMEM if the feature is supported but the total number of supported configurations | |
673 | // exceeds the maximum number indicated by the caller. | |
674 | // - total number of supported configurations (uint32_t) | |
675 | // - an array of configuration descriptors. | |
676 | // The actual number of descriptors returned must not exceed the maximum number indicated by | |
677 | // the caller. | |
678 | //-------------------------------------------------------------------------------------------------- | |
679 | // command format: | |
680 | // size: 2 x sizeof(uint32_t) | |
681 | // data: effect_feature_e + maximum number of configurations to return | |
682 | //-------------------------------------------------------------------------------------------------- | |
683 | // reply format: | |
684 | // size: 2 x sizeof(uint32_t) + n x sizeof (<config descriptor>) | |
685 | // data: status + total number of configurations supported + array of n config descriptors | |
686 | //================================================================================================== | |
687 | // command: EFFECT_CMD_GET_FEATURE_CONFIG | |
688 | //-------------------------------------------------------------------------------------------------- | |
689 | // description: | |
690 | // Retrieves current configuration for a given feature. | |
691 | // The reply status is: | |
692 | // - 0 if feature is supported | |
693 | // - -ENOSYS if the feature is not supported, | |
694 | //-------------------------------------------------------------------------------------------------- | |
695 | // command format: | |
696 | // size: sizeof(uint32_t) | |
697 | // data: effect_feature_e | |
698 | //-------------------------------------------------------------------------------------------------- | |
699 | // reply format: | |
700 | // size: sizeof(uint32_t) + sizeof (<config descriptor>) | |
701 | // data: status + config descriptor | |
702 | //================================================================================================== | |
703 | // command: EFFECT_CMD_SET_FEATURE_CONFIG | |
704 | //-------------------------------------------------------------------------------------------------- | |
705 | // description: | |
706 | // Sets current configuration for a given feature. | |
707 | // The reply status is: | |
708 | // - 0 if feature is supported | |
709 | // - -ENOSYS if the feature is not supported, | |
710 | // - -EINVAL if the configuration is invalid | |
711 | //-------------------------------------------------------------------------------------------------- | |
712 | // command format: | |
713 | // size: sizeof(uint32_t) + sizeof (<config descriptor>) | |
714 | // data: effect_feature_e + config descriptor | |
715 | //-------------------------------------------------------------------------------------------------- | |
716 | // reply format: | |
717 | // size: sizeof(uint32_t) | |
718 | // data: status | |
719 | //================================================================================================== | |
720 | // command: EFFECT_CMD_SET_AUDIO_SOURCE | |
721 | //-------------------------------------------------------------------------------------------------- | |
722 | // description: | |
723 | // Set the audio source the capture path is configured for (Camcorder, voice recognition...). | |
724 | // See audio.h, audio_source_t for values. | |
725 | //-------------------------------------------------------------------------------------------------- | |
726 | // command format: | |
727 | // size: sizeof(uint32_t) | |
728 | // data: uint32_t | |
729 | //-------------------------------------------------------------------------------------------------- | |
730 | // reply format: | |
731 | // size: 0 | |
732 | // data: N/A | |
733 | //================================================================================================== | |
734 | // command: EFFECT_CMD_FIRST_PROPRIETARY | |
735 | //-------------------------------------------------------------------------------------------------- | |
736 | // description: | |
737 | // All proprietary effect commands must use command codes above this value. The size and format of | |
738 | // command and response fields is free in this case | |
739 | //================================================================================================== | |
740 | ||
741 | ||
742 | // Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t | |
743 | // structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with | |
744 | // regard to the channel mask definition in audio.h, audio_channel_mask_t e.g : | |
745 | // Stereo: left, right | |
746 | // 5 point 1: front left, front right, front center, low frequency, back left, back right | |
747 | // The buffer size is expressed in frame count, a frame being composed of samples for all | |
748 | // channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by | |
749 | // definition | |
750 | struct audio_buffer_s { | |
751 | size_t frameCount; // number of frames in buffer | |
752 | union { | |
753 | void* raw; // raw pointer to start of buffer | |
754 | int32_t* s32; // pointer to signed 32 bit data at start of buffer | |
755 | int16_t* s16; // pointer to signed 16 bit data at start of buffer | |
756 | uint8_t* u8; // pointer to unsigned 8 bit data at start of buffer | |
757 | }; | |
758 | }; | |
759 | ||
760 | // The buffer_provider_s structure contains functions that can be used | |
761 | // by the effect engine process() function to query and release input | |
762 | // or output audio buffer. | |
763 | // The getBuffer() function is called to retrieve a buffer where data | |
764 | // should read from or written to by process() function. | |
765 | // The releaseBuffer() function MUST be called when the buffer retrieved | |
766 | // with getBuffer() is not needed anymore. | |
767 | // The process function should use the buffer provider mechanism to retrieve | |
768 | // input or output buffer if the inBuffer or outBuffer passed as argument is NULL | |
769 | // and the buffer configuration (buffer_config_t) given by the EFFECT_CMD_SET_CONFIG | |
770 | // command did not specify an audio buffer. | |
771 | ||
772 | typedef int32_t (* buffer_function_t)(void *cookie, audio_buffer_t *buffer); | |
773 | ||
774 | typedef struct buffer_provider_s { | |
775 | buffer_function_t getBuffer; // retrieve next buffer | |
776 | buffer_function_t releaseBuffer; // release used buffer | |
777 | void *cookie; // for use by client of buffer provider functions | |
778 | } buffer_provider_t; | |
779 | ||
780 | ||
781 | // The buffer_config_s structure specifies the input or output audio format | |
782 | // to be used by the effect engine. It is part of the effect_config_t | |
783 | // structure that defines both input and output buffer configurations and is | |
784 | // passed by the EFFECT_CMD_SET_CONFIG or EFFECT_CMD_SET_CONFIG_REVERSE command. | |
785 | typedef struct buffer_config_s { | |
786 | audio_buffer_t buffer; // buffer for use by process() function if not passed explicitly | |
787 | uint32_t samplingRate; // sampling rate | |
788 | uint32_t channels; // channel mask (see audio_channel_mask_t in audio.h) | |
789 | buffer_provider_t bufferProvider; // buffer provider | |
790 | uint8_t format; // Audio format (see see audio_format_t in audio.h) | |
791 | uint8_t accessMode; // read/write or accumulate in buffer (effect_buffer_access_e) | |
792 | uint16_t mask; // indicates which of the above fields is valid | |
793 | } buffer_config_t; | |
794 | ||
795 | // Values for "accessMode" field of buffer_config_t: | |
796 | // overwrite, read only, accumulate (read/modify/write) | |
797 | enum effect_buffer_access_e { | |
798 | EFFECT_BUFFER_ACCESS_WRITE, | |
799 | EFFECT_BUFFER_ACCESS_READ, | |
800 | EFFECT_BUFFER_ACCESS_ACCUMULATE | |
801 | ||
802 | }; | |
803 | ||
804 | // feature identifiers for EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS command | |
805 | enum effect_feature_e { | |
806 | EFFECT_FEATURE_AUX_CHANNELS, // supports auxiliary channels (e.g. dual mic noise suppressor) | |
807 | EFFECT_FEATURE_CNT | |
808 | }; | |
809 | ||
810 | // EFFECT_FEATURE_AUX_CHANNELS feature configuration descriptor. Describe a combination | |
811 | // of main and auxiliary channels supported | |
812 | typedef struct channel_config_s { | |
813 | audio_channel_mask_t main_channels; // channel mask for main channels | |
814 | audio_channel_mask_t aux_channels; // channel mask for auxiliary channels | |
815 | } channel_config_t; | |
816 | ||
817 | ||
818 | // Values for bit field "mask" in buffer_config_t. If a bit is set, the corresponding field | |
819 | // in buffer_config_t must be taken into account when executing the EFFECT_CMD_SET_CONFIG command | |
820 | #define EFFECT_CONFIG_BUFFER 0x0001 // buffer field must be taken into account | |
821 | #define EFFECT_CONFIG_SMP_RATE 0x0002 // samplingRate field must be taken into account | |
822 | #define EFFECT_CONFIG_CHANNELS 0x0004 // channels field must be taken into account | |
823 | #define EFFECT_CONFIG_FORMAT 0x0008 // format field must be taken into account | |
824 | #define EFFECT_CONFIG_ACC_MODE 0x0010 // accessMode field must be taken into account | |
825 | #define EFFECT_CONFIG_PROVIDER 0x0020 // bufferProvider field must be taken into account | |
826 | #define EFFECT_CONFIG_ALL (EFFECT_CONFIG_BUFFER | EFFECT_CONFIG_SMP_RATE | \ | |
827 | EFFECT_CONFIG_CHANNELS | EFFECT_CONFIG_FORMAT | \ | |
828 | EFFECT_CONFIG_ACC_MODE | EFFECT_CONFIG_PROVIDER) | |
829 | ||
830 | ||
831 | // effect_config_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_CONFIG | |
832 | // command to configure audio parameters and buffers for effect engine input and output. | |
833 | typedef struct effect_config_s { | |
834 | buffer_config_t inputCfg; | |
835 | buffer_config_t outputCfg; | |
836 | } effect_config_t; | |
837 | ||
838 | ||
839 | // effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM | |
840 | // command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command. | |
841 | // psize and vsize represent the actual size of parameter and value. | |
842 | // | |
843 | // NOTE: the start of value field inside the data field is always on a 32 bit boundary: | |
844 | // | |
845 | // +-----------+ | |
846 | // | status | sizeof(int) | |
847 | // +-----------+ | |
848 | // | psize | sizeof(int) | |
849 | // +-----------+ | |
850 | // | vsize | sizeof(int) | |
851 | // +-----------+ | |
852 | // | | | | | |
853 | // ~ parameter ~ > psize | | |
854 | // | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int) | |
855 | // +-----------+ | | |
856 | // | padding | | | |
857 | // +-----------+ | |
858 | // | | | | |
859 | // ~ value ~ > vsize | |
860 | // | | | | |
861 | // +-----------+ | |
862 | ||
863 | typedef struct effect_param_s { | |
864 | int32_t status; // Transaction status (unused for command, used for reply) | |
865 | uint32_t psize; // Parameter size | |
866 | uint32_t vsize; // Value size | |
867 | char data[]; // Start of Parameter + Value data | |
868 | } effect_param_t; | |
869 | ||
870 | ||
871 | ||
872 | ///////////////////////////////////////////////// | |
873 | // Effect library interface | |
874 | ///////////////////////////////////////////////// | |
875 | ||
876 | // Effect library interface version 2.0 | |
877 | #define EFFECT_LIBRARY_API_VERSION EFFECT_MAKE_API_VERSION(2,0) | |
878 | ||
879 | #define AUDIO_EFFECT_LIBRARY_TAG ((('A') << 24) | (('E') << 16) | (('L') << 8) | ('T')) | |
880 | ||
881 | // Every effect library must have a data structure named AUDIO_EFFECT_LIBRARY_INFO_SYM | |
882 | // and the fields of this data structure must begin with audio_effect_library_t | |
883 | ||
884 | typedef struct audio_effect_library_s { | |
885 | // tag must be initialized to AUDIO_EFFECT_LIBRARY_TAG | |
886 | uint32_t tag; | |
887 | // Version of the effect library API : 0xMMMMmmmm MMMM: Major, mmmm: minor | |
888 | uint32_t version; | |
889 | // Name of this library | |
890 | const char *name; | |
891 | // Author/owner/implementor of the library | |
892 | const char *implementor; | |
893 | ||
894 | //////////////////////////////////////////////////////////////////////////////// | |
895 | // | |
896 | // Function: query_num_effects | |
897 | // | |
898 | // Description: Returns the number of different effects exposed by the | |
899 | // library. Each effect must have a unique effect uuid (see | |
900 | // effect_descriptor_t). This function together with EffectQueryEffect() | |
901 | // is used to enumerate all effects present in the library. | |
902 | // | |
903 | // Input/Output: | |
904 | // pNumEffects: address where the number of effects should be returned. | |
905 | // | |
906 | // Output: | |
907 | // returned value: 0 successful operation. | |
908 | // -ENODEV library failed to initialize | |
909 | // -EINVAL invalid pNumEffects | |
910 | // *pNumEffects: updated with number of effects in library | |
911 | // | |
912 | //////////////////////////////////////////////////////////////////////////////// | |
913 | int32_t (*query_num_effects)(uint32_t *pNumEffects); | |
914 | ||
915 | //////////////////////////////////////////////////////////////////////////////// | |
916 | // | |
917 | // Function: query_effect | |
918 | // | |
919 | // Description: Returns the descriptor of the effect engine which index is | |
920 | // given as argument. | |
921 | // See effect_descriptor_t for details on effect descriptors. | |
922 | // This function together with EffectQueryNumberEffects() is used to enumerate all | |
923 | // effects present in the library. The enumeration sequence is: | |
924 | // EffectQueryNumberEffects(&num_effects); | |
925 | // for (i = 0; i < num_effects; i++) | |
926 | // EffectQueryEffect(i,...); | |
927 | // | |
928 | // Input/Output: | |
929 | // index: index of the effect | |
930 | // pDescriptor: address where to return the effect descriptor. | |
931 | // | |
932 | // Output: | |
933 | // returned value: 0 successful operation. | |
934 | // -ENODEV library failed to initialize | |
935 | // -EINVAL invalid pDescriptor or index | |
936 | // -ENOSYS effect list has changed since last execution of | |
937 | // EffectQueryNumberEffects() | |
938 | // -ENOENT no more effect available | |
939 | // *pDescriptor: updated with the effect descriptor. | |
940 | // | |
941 | //////////////////////////////////////////////////////////////////////////////// | |
942 | int32_t (*query_effect)(uint32_t index, | |
943 | effect_descriptor_t *pDescriptor); | |
944 | ||
945 | //////////////////////////////////////////////////////////////////////////////// | |
946 | // | |
947 | // Function: create_effect | |
948 | // | |
949 | // Description: Creates an effect engine of the specified implementation uuid and | |
950 | // returns an effect control interface on this engine. The function will allocate the | |
951 | // resources for an instance of the requested effect engine and return | |
952 | // a handle on the effect control interface. | |
953 | // | |
954 | // Input: | |
955 | // uuid: pointer to the effect uuid. | |
956 | // sessionId: audio session to which this effect instance will be attached. All effects | |
957 | // created with the same session ID are connected in series and process the same signal | |
958 | // stream. Knowing that two effects are part of the same effect chain can help the | |
959 | // library implement some kind of optimizations. | |
960 | // ioId: identifies the output or input stream this effect is directed to at audio HAL. | |
961 | // For future use especially with tunneled HW accelerated effects | |
962 | // | |
963 | // Input/Output: | |
964 | // pHandle: address where to return the effect interface handle. | |
965 | // | |
966 | // Output: | |
967 | // returned value: 0 successful operation. | |
968 | // -ENODEV library failed to initialize | |
969 | // -EINVAL invalid pEffectUuid or pHandle | |
970 | // -ENOENT no effect with this uuid found | |
971 | // *pHandle: updated with the effect interface handle. | |
972 | // | |
973 | //////////////////////////////////////////////////////////////////////////////// | |
974 | int32_t (*create_effect)(const effect_uuid_t *uuid, | |
975 | int32_t sessionId, | |
976 | int32_t ioId, | |
977 | effect_handle_t *pHandle); | |
978 | ||
979 | //////////////////////////////////////////////////////////////////////////////// | |
980 | // | |
981 | // Function: release_effect | |
982 | // | |
983 | // Description: Releases the effect engine whose handle is given as argument. | |
984 | // All resources allocated to this particular instance of the effect are | |
985 | // released. | |
986 | // | |
987 | // Input: | |
988 | // handle: handle on the effect interface to be released. | |
989 | // | |
990 | // Output: | |
991 | // returned value: 0 successful operation. | |
992 | // -ENODEV library failed to initialize | |
993 | // -EINVAL invalid interface handle | |
994 | // | |
995 | //////////////////////////////////////////////////////////////////////////////// | |
996 | int32_t (*release_effect)(effect_handle_t handle); | |
997 | ||
998 | //////////////////////////////////////////////////////////////////////////////// | |
999 | // | |
1000 | // Function: get_descriptor | |
1001 | // | |
1002 | // Description: Returns the descriptor of the effect engine which implementation UUID is | |
1003 | // given as argument. | |
1004 | // | |
1005 | // Input/Output: | |
1006 | // uuid: pointer to the effect uuid. | |
1007 | // pDescriptor: address where to return the effect descriptor. | |
1008 | // | |
1009 | // Output: | |
1010 | // returned value: 0 successful operation. | |
1011 | // -ENODEV library failed to initialize | |
1012 | // -EINVAL invalid pDescriptor or uuid | |
1013 | // *pDescriptor: updated with the effect descriptor. | |
1014 | // | |
1015 | //////////////////////////////////////////////////////////////////////////////// | |
1016 | int32_t (*get_descriptor)(const effect_uuid_t *uuid, | |
1017 | effect_descriptor_t *pDescriptor); | |
1018 | } audio_effect_library_t; | |
1019 | ||
1020 | // Name of the hal_module_info | |
1021 | #define AUDIO_EFFECT_LIBRARY_INFO_SYM AELI | |
1022 | ||
1023 | // Name of the hal_module_info as a string | |
1024 | #define AUDIO_EFFECT_LIBRARY_INFO_SYM_AS_STR "AELI" | |
1025 | ||
1026 | __END_DECLS | |
1027 | ||
1028 | #endif // ANDROID_AUDIO_EFFECT_H |