~sergiusens/libhybris/autotests

« back to all changes in this revision

Viewing changes to hybris/include/android/hardware/audio_effect.h

  • Committer: Package Import Robot
  • Author(s): Ricardo Salveti de Araujo
  • Date: 2013-06-24 01:28:22 UTC
  • Revision ID: package-import@ubuntu.com-20130624012822-uk1ppfvw6ubb88bb
Tags: 0.1.0+git20130606+c5d897a-0ubuntu4
* Adding 0010-hardware-include-adding-audio-hal-related-headers-fr.patch:
  - Exporting headers needed to access the Android Audio HAL

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
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 <android/cutils/bitops.h>
 
28
 
 
29
#include <android/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