2 * Copyright (C) 2011 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef ANDROID_AUDIO_EFFECT_H
19 #define ANDROID_AUDIO_EFFECT_H
24 #include <sys/cdefs.h>
25 #include <sys/types.h>
27 #include <cutils/bitops.h>
29 #include <system/audio.h>
35 /////////////////////////////////////////////////
37 /////////////////////////////////////////////////
40 //--- Effect descriptor structure effect_descriptor_t
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
{
52 uint16_t timeHiAndVersion
;
57 // Maximum length of character strings in structures defines by this API.
58 #define EFFECT_STRING_LEN_MAX 64
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";
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
;
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
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
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.
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
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 // +---------------------------+-----------+-----------------------------------
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
237 /////////////////////////////////////////////////
238 // Effect control interface
239 /////////////////////////////////////////////////
241 // Effect control interface version 2.0
242 #define EFFECT_CONTROL_API_VERSION EFFECT_MAKE_API_VERSION(2,0)
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.
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;
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
;
265 // Forward definition of type audio_buffer_t
266 typedef struct audio_buffer_s audio_buffer_t
;
273 // Effect control interface definition
274 struct effect_interface_s
{
275 ////////////////////////////////////////////////////////////////////////////////
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.
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...
295 // self: handle to the effect interface this function
297 // inBuffer: buffer descriptor indicating where to read samples to process.
298 // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command.
300 // outBuffer: buffer descriptor indicating where to write processed samples.
301 // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command.
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 ////////////////////////////////////////////////////////////////////////////////
317 // Description: Send a command and receive a response to/from effect engine.
320 // self: handle to the effect interface this function
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
329 // replySize: maximum size of reply data as input
330 // actual size of reply data as 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.
340 // *pReplyData updated with command response
342 ////////////////////////////////////////////////////////////////////////////////
343 int32_t (*command
)(effect_handle_t self
,
349 ////////////////////////////////////////////////////////////////////////////////
351 // Function: get_descriptor
353 // Description: Returns the effect descriptor
356 // self: handle to the effect interface this function
360 // pDescriptor: address where to return the effect descriptor.
363 // returned value: 0 successful operation.
364 // -EINVAL invalid interface handle or invalid pDescriptor
365 // *pDescriptor: updated with the effect descriptor.
367 ////////////////////////////////////////////////////////////////////////////////
368 int32_t (*get_descriptor
)(effect_handle_t self
,
369 effect_descriptor_t
*pDescriptor
);
370 ////////////////////////////////////////////////////////////////////////////////
372 // Function: process_reverse
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.
380 // self: handle to the effect interface this function
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.
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
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
);
405 //--- Standardized command codes for command() function
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
431 //==================================================================================================
432 // command: EFFECT_CMD_INIT
433 //--------------------------------------------------------------------------------------------------
435 // Initialize effect engine: All configurations return to default
436 //--------------------------------------------------------------------------------------------------
440 //--------------------------------------------------------------------------------------------------
444 //==================================================================================================
445 // command: EFFECT_CMD_SET_CONFIG
446 //--------------------------------------------------------------------------------------------------
448 // Apply new audio parameters configurations for input and output buffers
449 //--------------------------------------------------------------------------------------------------
451 // size: sizeof(effect_config_t)
452 // data: effect_config_t
453 //--------------------------------------------------------------------------------------------------
457 //==================================================================================================
458 // command: EFFECT_CMD_RESET
459 //--------------------------------------------------------------------------------------------------
461 // Reset the effect engine. Keep configuration but resets state and buffer content
462 //--------------------------------------------------------------------------------------------------
466 //--------------------------------------------------------------------------------------------------
470 //==================================================================================================
471 // command: EFFECT_CMD_ENABLE
472 //--------------------------------------------------------------------------------------------------
474 // Enable the process. Called by the framework before the first call to process()
475 //--------------------------------------------------------------------------------------------------
479 //--------------------------------------------------------------------------------------------------
483 //==================================================================================================
484 // command: EFFECT_CMD_DISABLE
485 //--------------------------------------------------------------------------------------------------
487 // Disable the process. Called by the framework after the last call to process()
488 //--------------------------------------------------------------------------------------------------
492 //--------------------------------------------------------------------------------------------------
496 //==================================================================================================
497 // command: EFFECT_CMD_SET_PARAM
498 //--------------------------------------------------------------------------------------------------
500 // Set a parameter and apply it immediately
501 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
509 //==================================================================================================
510 // command: EFFECT_CMD_SET_PARAM_DEFERRED
511 //--------------------------------------------------------------------------------------------------
513 // Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command
514 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
522 //==================================================================================================
523 // command: EFFECT_CMD_SET_PARAM_COMMIT
524 //--------------------------------------------------------------------------------------------------
526 // Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands
527 //--------------------------------------------------------------------------------------------------
531 //--------------------------------------------------------------------------------------------------
535 //==================================================================================================
536 // command: EFFECT_CMD_GET_PARAM
537 //--------------------------------------------------------------------------------------------------
539 // Get a parameter value
540 //--------------------------------------------------------------------------------------------------
542 // size: sizeof(effect_param_t) + size of param
543 // data: effect_param_t + param
544 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
558 // size: sizeof(uint32_t)
560 //--------------------------------------------------------------------------------------------------
564 //==================================================================================================
565 // command: EFFECT_CMD_SET_VOLUME
566 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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:
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
598 // size: sizeof(uint32_t)
599 // data: audio_mode_t
600 //--------------------------------------------------------------------------------------------------
604 //==================================================================================================
605 // command: EFFECT_CMD_SET_CONFIG_REVERSE
606 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
612 // size: sizeof(effect_config_t)
613 // data: effect_config_t
614 //--------------------------------------------------------------------------------------------------
618 //==================================================================================================
619 // command: EFFECT_CMD_SET_INPUT_DEVICE
620 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
628 // size: sizeof(uint32_t)
630 //--------------------------------------------------------------------------------------------------
634 //==================================================================================================
635 // command: EFFECT_CMD_GET_CONFIG
636 //--------------------------------------------------------------------------------------------------
638 // Read audio parameters configurations for input and output buffers
639 //--------------------------------------------------------------------------------------------------
643 //--------------------------------------------------------------------------------------------------
645 // size: sizeof(effect_config_t)
646 // data: effect_config_t
647 //==================================================================================================
648 // command: EFFECT_CMD_GET_CONFIG_REVERSE
649 //--------------------------------------------------------------------------------------------------
651 // Read audio parameters configurations for input and output buffers of reverse stream
652 //--------------------------------------------------------------------------------------------------
656 //--------------------------------------------------------------------------------------------------
658 // size: sizeof(effect_config_t)
659 // data: effect_config_t
660 //==================================================================================================
661 // command: EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS
662 //--------------------------------------------------------------------------------------------------
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
678 //--------------------------------------------------------------------------------------------------
680 // size: 2 x sizeof(uint32_t)
681 // data: effect_feature_e + maximum number of configurations to return
682 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
696 // size: sizeof(uint32_t)
697 // data: effect_feature_e
698 //--------------------------------------------------------------------------------------------------
700 // size: sizeof(uint32_t) + sizeof (<config descriptor>)
701 // data: status + config descriptor
702 //==================================================================================================
703 // command: EFFECT_CMD_SET_FEATURE_CONFIG
704 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
713 // size: sizeof(uint32_t) + sizeof (<config descriptor>)
714 // data: effect_feature_e + config descriptor
715 //--------------------------------------------------------------------------------------------------
717 // size: sizeof(uint32_t)
719 //==================================================================================================
720 // command: EFFECT_CMD_SET_AUDIO_SOURCE
721 //--------------------------------------------------------------------------------------------------
723 // Set the audio source the capture path is configured for (Camcorder, voice recognition...).
724 // See audio.h, audio_source_t for values.
725 //--------------------------------------------------------------------------------------------------
727 // size: sizeof(uint32_t)
729 //--------------------------------------------------------------------------------------------------
733 //==================================================================================================
734 // command: EFFECT_CMD_FIRST_PROPRIETARY
735 //--------------------------------------------------------------------------------------------------
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 //==================================================================================================
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
750 struct audio_buffer_s
{
751 size_t frameCount
; // number of frames in buffer
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
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.
772 typedef int32_t (* buffer_function_t
)(void *cookie
, audio_buffer_t
*buffer
);
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
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
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
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)
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
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)
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
;
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.
843 // NOTE: the start of value field inside the data field is always on a 32 bit boundary:
846 // | status | sizeof(int)
848 // | psize | sizeof(int)
850 // | vsize | sizeof(int)
853 // ~ parameter ~ > psize |
854 // | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int)
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
872 /////////////////////////////////////////////////
873 // Effect library interface
874 /////////////////////////////////////////////////
876 // Effect library interface version 2.0
877 #define EFFECT_LIBRARY_API_VERSION EFFECT_MAKE_API_VERSION(2,0)
879 #define AUDIO_EFFECT_LIBRARY_TAG ((('A') << 24) | (('E') << 16) | (('L') << 8) | ('T'))
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
884 typedef struct audio_effect_library_s
{
885 // tag must be initialized to AUDIO_EFFECT_LIBRARY_TAG
887 // Version of the effect library API : 0xMMMMmmmm MMMM: Major, mmmm: minor
889 // Name of this library
891 // Author/owner/implementor of the library
892 const char *implementor
;
894 ////////////////////////////////////////////////////////////////////////////////
896 // Function: query_num_effects
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.
904 // pNumEffects: address where the number of effects should be returned.
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
912 ////////////////////////////////////////////////////////////////////////////////
913 int32_t (*query_num_effects
)(uint32_t *pNumEffects
);
915 ////////////////////////////////////////////////////////////////////////////////
917 // Function: query_effect
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,...);
929 // index: index of the effect
930 // pDescriptor: address where to return the effect descriptor.
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.
941 ////////////////////////////////////////////////////////////////////////////////
942 int32_t (*query_effect
)(uint32_t index
,
943 effect_descriptor_t
*pDescriptor
);
945 ////////////////////////////////////////////////////////////////////////////////
947 // Function: create_effect
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.
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
964 // pHandle: address where to return the effect interface handle.
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.
973 ////////////////////////////////////////////////////////////////////////////////
974 int32_t (*create_effect
)(const effect_uuid_t
*uuid
,
977 effect_handle_t
*pHandle
);
979 ////////////////////////////////////////////////////////////////////////////////
981 // Function: release_effect
983 // Description: Releases the effect engine whose handle is given as argument.
984 // All resources allocated to this particular instance of the effect are
988 // handle: handle on the effect interface to be released.
991 // returned value: 0 successful operation.
992 // -ENODEV library failed to initialize
993 // -EINVAL invalid interface handle
995 ////////////////////////////////////////////////////////////////////////////////
996 int32_t (*release_effect
)(effect_handle_t handle
);
998 ////////////////////////////////////////////////////////////////////////////////
1000 // Function: get_descriptor
1002 // Description: Returns the descriptor of the effect engine which implementation UUID is
1003 // given as argument.
1006 // uuid: pointer to the effect uuid.
1007 // pDescriptor: address where to return the effect descriptor.
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.
1015 ////////////////////////////////////////////////////////////////////////////////
1016 int32_t (*get_descriptor
)(const effect_uuid_t
*uuid
,
1017 effect_descriptor_t
*pDescriptor
);
1018 } audio_effect_library_t
;
1020 // Name of the hal_module_info
1021 #define AUDIO_EFFECT_LIBRARY_INFO_SYM AELI
1023 // Name of the hal_module_info as a string
1024 #define AUDIO_EFFECT_LIBRARY_INFO_SYM_AS_STR "AELI"
1028 #endif // ANDROID_AUDIO_EFFECT_H