1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/system/gonk/android_audio/EffectApi.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,798 @@
1.4 +/*
1.5 + * Copyright (C) 2010 The Android Open Source Project
1.6 + *
1.7 + * Licensed under the Apache License, Version 2.0 (the "License");
1.8 + * you may not use this file except in compliance with the License.
1.9 + * You may obtain a copy of the License at
1.10 + *
1.11 + * http://www.apache.org/licenses/LICENSE-2.0
1.12 + *
1.13 + * Unless required by applicable law or agreed to in writing, software
1.14 + * distributed under the License is distributed on an "AS IS" BASIS,
1.15 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1.16 + * See the License for the specific language governing permissions and
1.17 + * limitations under the License.
1.18 + */
1.19 +
1.20 +#ifndef ANDROID_EFFECTAPI_H_
1.21 +#define ANDROID_EFFECTAPI_H_
1.22 +
1.23 +#include <errno.h>
1.24 +#include <stdint.h>
1.25 +#include <sys/types.h>
1.26 +
1.27 +#if __cplusplus
1.28 +extern "C" {
1.29 +#endif
1.30 +
1.31 +/////////////////////////////////////////////////
1.32 +// Effect control interface
1.33 +/////////////////////////////////////////////////
1.34 +
1.35 +// The effect control interface is exposed by each effect engine implementation. It consists of
1.36 +// a set of functions controlling the configuration, activation and process of the engine.
1.37 +// The functions are grouped in a structure of type effect_interface_s:
1.38 +// struct effect_interface_s {
1.39 +// effect_process_t process;
1.40 +// effect_command_t command;
1.41 +// };
1.42 +
1.43 +
1.44 +// effect_interface_t: Effect control interface handle.
1.45 +// The effect_interface_t serves two purposes regarding the implementation of the effect engine:
1.46 +// - 1 it is the address of a pointer to an effect_interface_s structure where the functions
1.47 +// of the effect control API for a particular effect are located.
1.48 +// - 2 it is the address of the context of a particular effect instance.
1.49 +// A typical implementation in the effect library would define a structure as follows:
1.50 +// struct effect_module_s {
1.51 +// const struct effect_interface_s *itfe;
1.52 +// effect_config_t config;
1.53 +// effect_context_t context;
1.54 +// }
1.55 +// The implementation of EffectCreate() function would then allocate a structure of this
1.56 +// type and return its address as effect_interface_t
1.57 +typedef struct effect_interface_s **effect_interface_t;
1.58 +
1.59 +
1.60 +// Effect API version 1.0
1.61 +#define EFFECT_API_VERSION 0x0100 // Format 0xMMmm MM: Major version, mm: minor version
1.62 +
1.63 +// Maximum length of character strings in structures defines by this API.
1.64 +#define EFFECT_STRING_LEN_MAX 64
1.65 +
1.66 +//
1.67 +//--- Effect descriptor structure effect_descriptor_t
1.68 +//
1.69 +
1.70 +// Unique effect ID (can be generated from the following site:
1.71 +// http://www.itu.int/ITU-T/asn1/uuid.html)
1.72 +// This format is used for both "type" and "uuid" fields of the effect descriptor structure.
1.73 +// - When used for effect type and the engine is implementing and effect corresponding to a standard
1.74 +// OpenSL ES interface, this ID must be the one defined in OpenSLES_IID.h for that interface.
1.75 +// - When used as uuid, it should be a unique UUID for this particular implementation.
1.76 +typedef struct effect_uuid_s {
1.77 + uint32_t timeLow;
1.78 + uint16_t timeMid;
1.79 + uint16_t timeHiAndVersion;
1.80 + uint16_t clockSeq;
1.81 + uint8_t node[6];
1.82 +} effect_uuid_t;
1.83 +
1.84 +// NULL UUID definition (matches SL_IID_NULL_)
1.85 +#define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \
1.86 + { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } }
1.87 +static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER;
1.88 +const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_;
1.89 +const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210";
1.90 +
1.91 +// The effect descriptor contains necessary information to facilitate the enumeration of the effect
1.92 +// engines present in a library.
1.93 +typedef struct effect_descriptor_s {
1.94 + effect_uuid_t type; // UUID of to the OpenSL ES interface implemented by this effect
1.95 + effect_uuid_t uuid; // UUID for this particular implementation
1.96 + uint16_t apiVersion; // Version of the effect API implemented: matches EFFECT_API_VERSION
1.97 + uint32_t flags; // effect engine capabilities/requirements flags (see below)
1.98 + uint16_t cpuLoad; // CPU load indication (see below)
1.99 + uint16_t memoryUsage; // Data Memory usage (see below)
1.100 + char name[EFFECT_STRING_LEN_MAX]; // human readable effect name
1.101 + char implementor[EFFECT_STRING_LEN_MAX]; // human readable effect implementor name
1.102 +} effect_descriptor_t;
1.103 +
1.104 +// CPU load and memory usage indication: each effect implementation must provide an indication of
1.105 +// its CPU and memory usage for the audio effect framework to limit the number of effects
1.106 +// instantiated at a given time on a given platform.
1.107 +// The CPU load is expressed in 0.1 MIPS units as estimated on an ARM9E core (ARMv5TE) with 0 WS.
1.108 +// The memory usage is expressed in KB and includes only dynamically allocated memory
1.109 +
1.110 +// Definitions for flags field of effect descriptor.
1.111 +// +---------------------------+-----------+-----------------------------------
1.112 +// | description | bits | values
1.113 +// +---------------------------+-----------+-----------------------------------
1.114 +// | connection mode | 0..1 | 0 insert: after track process
1.115 +// | | | 1 auxiliary: connect to track auxiliary
1.116 +// | | | output and use send level
1.117 +// | | | 2 replace: replaces track process function;
1.118 +// | | | must implement SRC, volume and mono to stereo.
1.119 +// | | | 3 reserved
1.120 +// +---------------------------+-----------+-----------------------------------
1.121 +// | insertion preference | 2..4 | 0 none
1.122 +// | | | 1 first of the chain
1.123 +// | | | 2 last of the chain
1.124 +// | | | 3 exclusive (only effect in the insert chain)
1.125 +// | | | 4..7 reserved
1.126 +// +---------------------------+-----------+-----------------------------------
1.127 +// | Volume management | 5..6 | 0 none
1.128 +// | | | 1 implements volume control
1.129 +// | | | 2 requires volume indication
1.130 +// | | | 3 reserved
1.131 +// +---------------------------+-----------+-----------------------------------
1.132 +// | Device indication | 7..8 | 0 none
1.133 +// | | | 1 requires device updates
1.134 +// | | | 2..3 reserved
1.135 +// +---------------------------+-----------+-----------------------------------
1.136 +// | Sample input mode | 9..10 | 0 direct: process() function or EFFECT_CMD_CONFIGURE
1.137 +// | | | command must specify a buffer descriptor
1.138 +// | | | 1 provider: process() function uses the
1.139 +// | | | bufferProvider indicated by the
1.140 +// | | | EFFECT_CMD_CONFIGURE command to request input.
1.141 +// | | | buffers.
1.142 +// | | | 2 both: both input modes are supported
1.143 +// | | | 3 reserved
1.144 +// +---------------------------+-----------+-----------------------------------
1.145 +// | Sample output mode | 11..12 | 0 direct: process() function or EFFECT_CMD_CONFIGURE
1.146 +// | | | command must specify a buffer descriptor
1.147 +// | | | 1 provider: process() function uses the
1.148 +// | | | bufferProvider indicated by the
1.149 +// | | | EFFECT_CMD_CONFIGURE command to request output
1.150 +// | | | buffers.
1.151 +// | | | 2 both: both output modes are supported
1.152 +// | | | 3 reserved
1.153 +// +---------------------------+-----------+-----------------------------------
1.154 +// | Hardware acceleration | 13..15 | 0 No hardware acceleration
1.155 +// | | | 1 non tunneled hw acceleration: the process() function
1.156 +// | | | reads the samples, send them to HW accelerated
1.157 +// | | | effect processor, reads back the processed samples
1.158 +// | | | and returns them to the output buffer.
1.159 +// | | | 2 tunneled hw acceleration: the process() function is
1.160 +// | | | transparent. The effect interface is only used to
1.161 +// | | | control the effect engine. This mode is relevant for
1.162 +// | | | global effects actually applied by the audio
1.163 +// | | | hardware on the output stream.
1.164 +// +---------------------------+-----------+-----------------------------------
1.165 +// | Audio Mode indication | 16..17 | 0 none
1.166 +// | | | 1 requires audio mode updates
1.167 +// | | | 2..3 reserved
1.168 +// +---------------------------+-----------+-----------------------------------
1.169 +
1.170 +// Insert mode
1.171 +#define EFFECT_FLAG_TYPE_MASK 0x00000003
1.172 +#define EFFECT_FLAG_TYPE_INSERT 0x00000000
1.173 +#define EFFECT_FLAG_TYPE_AUXILIARY 0x00000001
1.174 +#define EFFECT_FLAG_TYPE_REPLACE 0x00000002
1.175 +
1.176 +// Insert preference
1.177 +#define EFFECT_FLAG_INSERT_MASK 0x0000001C
1.178 +#define EFFECT_FLAG_INSERT_ANY 0x00000000
1.179 +#define EFFECT_FLAG_INSERT_FIRST 0x00000004
1.180 +#define EFFECT_FLAG_INSERT_LAST 0x00000008
1.181 +#define EFFECT_FLAG_INSERT_EXCLUSIVE 0x0000000C
1.182 +
1.183 +
1.184 +// Volume control
1.185 +#define EFFECT_FLAG_VOLUME_MASK 0x00000060
1.186 +#define EFFECT_FLAG_VOLUME_CTRL 0x00000020
1.187 +#define EFFECT_FLAG_VOLUME_IND 0x00000040
1.188 +#define EFFECT_FLAG_VOLUME_NONE 0x00000000
1.189 +
1.190 +// Device indication
1.191 +#define EFFECT_FLAG_DEVICE_MASK 0x00000180
1.192 +#define EFFECT_FLAG_DEVICE_IND 0x00000080
1.193 +#define EFFECT_FLAG_DEVICE_NONE 0x00000000
1.194 +
1.195 +// Sample input modes
1.196 +#define EFFECT_FLAG_INPUT_MASK 0x00000600
1.197 +#define EFFECT_FLAG_INPUT_DIRECT 0x00000000
1.198 +#define EFFECT_FLAG_INPUT_PROVIDER 0x00000200
1.199 +#define EFFECT_FLAG_INPUT_BOTH 0x00000400
1.200 +
1.201 +// Sample output modes
1.202 +#define EFFECT_FLAG_OUTPUT_MASK 0x00001800
1.203 +#define EFFECT_FLAG_OUTPUT_DIRECT 0x00000000
1.204 +#define EFFECT_FLAG_OUTPUT_PROVIDER 0x00000800
1.205 +#define EFFECT_FLAG_OUTPUT_BOTH 0x00001000
1.206 +
1.207 +// Hardware acceleration mode
1.208 +#define EFFECT_FLAG_HW_ACC_MASK 0x00006000
1.209 +#define EFFECT_FLAG_HW_ACC_SIMPLE 0x00002000
1.210 +#define EFFECT_FLAG_HW_ACC_TUNNEL 0x00004000
1.211 +
1.212 +// Audio mode indication
1.213 +#define EFFECT_FLAG_AUDIO_MODE_MASK 0x00018000
1.214 +#define EFFECT_FLAG_AUDIO_MODE_IND 0x00008000
1.215 +#define EFFECT_FLAG_AUDIO_MODE_NONE 0x00000000
1.216 +
1.217 +// Forward definition of type audio_buffer_t
1.218 +typedef struct audio_buffer_s audio_buffer_t;
1.219 +
1.220 +////////////////////////////////////////////////////////////////////////////////
1.221 +//
1.222 +// Function: process
1.223 +//
1.224 +// Description: Effect process function. Takes input samples as specified
1.225 +// (count and location) in input buffer descriptor and output processed
1.226 +// samples as specified in output buffer descriptor. If the buffer descriptor
1.227 +// is not specified the function must use either the buffer or the
1.228 +// buffer provider function installed by the EFFECT_CMD_CONFIGURE command.
1.229 +// The effect framework will call the process() function after the EFFECT_CMD_ENABLE
1.230 +// command is received and until the EFFECT_CMD_DISABLE is received. When the engine
1.231 +// receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully
1.232 +// and when done indicate that it is OK to stop calling the process() function by
1.233 +// returning the -ENODATA status.
1.234 +//
1.235 +// NOTE: the process() function implementation should be "real-time safe" that is
1.236 +// it should not perform blocking calls: malloc/free, sleep, read/write/open/close,
1.237 +// pthread_cond_wait/pthread_mutex_lock...
1.238 +//
1.239 +// Input:
1.240 +// effect_interface_t: handle to the effect interface this function
1.241 +// is called on.
1.242 +// inBuffer: buffer descriptor indicating where to read samples to process.
1.243 +// If NULL, use the configuration passed by EFFECT_CMD_CONFIGURE command.
1.244 +//
1.245 +// inBuffer: buffer descriptor indicating where to write processed samples.
1.246 +// If NULL, use the configuration passed by EFFECT_CMD_CONFIGURE command.
1.247 +//
1.248 +// Output:
1.249 +// returned value: 0 successful operation
1.250 +// -ENODATA the engine has finished the disable phase and the framework
1.251 +// can stop calling process()
1.252 +// -EINVAL invalid interface handle or
1.253 +// invalid input/output buffer description
1.254 +////////////////////////////////////////////////////////////////////////////////
1.255 +typedef int32_t (*effect_process_t)(effect_interface_t self,
1.256 + audio_buffer_t *inBuffer,
1.257 + audio_buffer_t *outBuffer);
1.258 +
1.259 +////////////////////////////////////////////////////////////////////////////////
1.260 +//
1.261 +// Function: command
1.262 +//
1.263 +// Description: Send a command and receive a response to/from effect engine.
1.264 +//
1.265 +// Input:
1.266 +// effect_interface_t: handle to the effect interface this function
1.267 +// is called on.
1.268 +// cmdCode: command code: the command can be a standardized command defined in
1.269 +// effect_command_e (see below) or a proprietary command.
1.270 +// cmdSize: size of command in bytes
1.271 +// pCmdData: pointer to command data
1.272 +// pReplyData: pointer to reply data
1.273 +//
1.274 +// Input/Output:
1.275 +// replySize: maximum size of reply data as input
1.276 +// actual size of reply data as output
1.277 +//
1.278 +// Output:
1.279 +// returned value: 0 successful operation
1.280 +// -EINVAL invalid interface handle or
1.281 +// invalid command/reply size or format according to command code
1.282 +// The return code should be restricted to indicate problems related to the this
1.283 +// API specification. Status related to the execution of a particular command should be
1.284 +// indicated as part of the reply field.
1.285 +//
1.286 +// *pReplyData updated with command response
1.287 +//
1.288 +////////////////////////////////////////////////////////////////////////////////
1.289 +typedef int32_t (*effect_command_t)(effect_interface_t self,
1.290 + uint32_t cmdCode,
1.291 + uint32_t cmdSize,
1.292 + void *pCmdData,
1.293 + uint32_t *replySize,
1.294 + void *pReplyData);
1.295 +
1.296 +
1.297 +// Effect control interface definition
1.298 +struct effect_interface_s {
1.299 + effect_process_t process;
1.300 + effect_command_t command;
1.301 +};
1.302 +
1.303 +
1.304 +//
1.305 +//--- Standardized command codes for command() function
1.306 +//
1.307 +enum effect_command_e {
1.308 + EFFECT_CMD_INIT, // initialize effect engine
1.309 + EFFECT_CMD_CONFIGURE, // configure effect engine (see effect_config_t)
1.310 + EFFECT_CMD_RESET, // reset effect engine
1.311 + EFFECT_CMD_ENABLE, // enable effect process
1.312 + EFFECT_CMD_DISABLE, // disable effect process
1.313 + EFFECT_CMD_SET_PARAM, // set parameter immediately (see effect_param_t)
1.314 + EFFECT_CMD_SET_PARAM_DEFERRED, // set parameter deferred
1.315 + EFFECT_CMD_SET_PARAM_COMMIT, // commit previous set parameter deferred
1.316 + EFFECT_CMD_GET_PARAM, // get parameter
1.317 + EFFECT_CMD_SET_DEVICE, // set audio device (see audio_device_e)
1.318 + EFFECT_CMD_SET_VOLUME, // set volume
1.319 + EFFECT_CMD_SET_AUDIO_MODE, // set the audio mode (normal, ring, ...)
1.320 + EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code
1.321 +};
1.322 +
1.323 +//==================================================================================================
1.324 +// command: EFFECT_CMD_INIT
1.325 +//--------------------------------------------------------------------------------------------------
1.326 +// description:
1.327 +// Initialize effect engine: All configurations return to default
1.328 +//--------------------------------------------------------------------------------------------------
1.329 +// command format:
1.330 +// size: 0
1.331 +// data: N/A
1.332 +//--------------------------------------------------------------------------------------------------
1.333 +// reply format:
1.334 +// size: sizeof(int)
1.335 +// data: status
1.336 +//==================================================================================================
1.337 +// command: EFFECT_CMD_CONFIGURE
1.338 +//--------------------------------------------------------------------------------------------------
1.339 +// description:
1.340 +// Apply new audio parameters configurations for input and output buffers
1.341 +//--------------------------------------------------------------------------------------------------
1.342 +// command format:
1.343 +// size: sizeof(effect_config_t)
1.344 +// data: effect_config_t
1.345 +//--------------------------------------------------------------------------------------------------
1.346 +// reply format:
1.347 +// size: sizeof(int)
1.348 +// data: status
1.349 +//==================================================================================================
1.350 +// command: EFFECT_CMD_RESET
1.351 +//--------------------------------------------------------------------------------------------------
1.352 +// description:
1.353 +// Reset the effect engine. Keep configuration but resets state and buffer content
1.354 +//--------------------------------------------------------------------------------------------------
1.355 +// command format:
1.356 +// size: 0
1.357 +// data: N/A
1.358 +//--------------------------------------------------------------------------------------------------
1.359 +// reply format:
1.360 +// size: 0
1.361 +// data: N/A
1.362 +//==================================================================================================
1.363 +// command: EFFECT_CMD_ENABLE
1.364 +//--------------------------------------------------------------------------------------------------
1.365 +// description:
1.366 +// Enable the process. Called by the framework before the first call to process()
1.367 +//--------------------------------------------------------------------------------------------------
1.368 +// command format:
1.369 +// size: 0
1.370 +// data: N/A
1.371 +//--------------------------------------------------------------------------------------------------
1.372 +// reply format:
1.373 +// size: sizeof(int)
1.374 +// data: status
1.375 +//==================================================================================================
1.376 +// command: EFFECT_CMD_DISABLE
1.377 +//--------------------------------------------------------------------------------------------------
1.378 +// description:
1.379 +// Disable the process. Called by the framework after the last call to process()
1.380 +//--------------------------------------------------------------------------------------------------
1.381 +// command format:
1.382 +// size: 0
1.383 +// data: N/A
1.384 +//--------------------------------------------------------------------------------------------------
1.385 +// reply format:
1.386 +// size: sizeof(int)
1.387 +// data: status
1.388 +//==================================================================================================
1.389 +// command: EFFECT_CMD_SET_PARAM
1.390 +//--------------------------------------------------------------------------------------------------
1.391 +// description:
1.392 +// Set a parameter and apply it immediately
1.393 +//--------------------------------------------------------------------------------------------------
1.394 +// command format:
1.395 +// size: sizeof(effect_param_t) + size of param and value
1.396 +// data: effect_param_t + param + value. See effect_param_t definition below for value offset
1.397 +//--------------------------------------------------------------------------------------------------
1.398 +// reply format:
1.399 +// size: sizeof(int)
1.400 +// data: status
1.401 +//==================================================================================================
1.402 +// command: EFFECT_CMD_SET_PARAM_DEFERRED
1.403 +//--------------------------------------------------------------------------------------------------
1.404 +// description:
1.405 +// Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command
1.406 +//--------------------------------------------------------------------------------------------------
1.407 +// command format:
1.408 +// size: sizeof(effect_param_t) + size of param and value
1.409 +// data: effect_param_t + param + value. See effect_param_t definition below for value offset
1.410 +//--------------------------------------------------------------------------------------------------
1.411 +// reply format:
1.412 +// size: 0
1.413 +// data: N/A
1.414 +//==================================================================================================
1.415 +// command: EFFECT_CMD_SET_PARAM_COMMIT
1.416 +//--------------------------------------------------------------------------------------------------
1.417 +// description:
1.418 +// Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands
1.419 +//--------------------------------------------------------------------------------------------------
1.420 +// command format:
1.421 +// size: 0
1.422 +// data: N/A
1.423 +//--------------------------------------------------------------------------------------------------
1.424 +// reply format:
1.425 +// size: sizeof(int)
1.426 +// data: status
1.427 +//==================================================================================================
1.428 +// command: EFFECT_CMD_GET_PARAM
1.429 +//--------------------------------------------------------------------------------------------------
1.430 +// description:
1.431 +// Get a parameter value
1.432 +//--------------------------------------------------------------------------------------------------
1.433 +// command format:
1.434 +// size: sizeof(effect_param_t) + size of param
1.435 +// data: effect_param_t + param
1.436 +//--------------------------------------------------------------------------------------------------
1.437 +// reply format:
1.438 +// size: sizeof(effect_param_t) + size of param and value
1.439 +// data: effect_param_t + param + value. See effect_param_t definition below for value offset
1.440 +//==================================================================================================
1.441 +// command: EFFECT_CMD_SET_DEVICE
1.442 +//--------------------------------------------------------------------------------------------------
1.443 +// description:
1.444 +// Set the rendering device the audio output path is connected to. See audio_device_e for device
1.445 +// values.
1.446 +// The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this
1.447 +// command when the device changes
1.448 +//--------------------------------------------------------------------------------------------------
1.449 +// command format:
1.450 +// size: sizeof(uint32_t)
1.451 +// data: audio_device_e
1.452 +//--------------------------------------------------------------------------------------------------
1.453 +// reply format:
1.454 +// size: 0
1.455 +// data: N/A
1.456 +//==================================================================================================
1.457 +// command: EFFECT_CMD_SET_VOLUME
1.458 +//--------------------------------------------------------------------------------------------------
1.459 +// description:
1.460 +// Set and get volume. Used by audio framework to delegate volume control to effect engine.
1.461 +// The effect implementation must set EFFECT_FLAG_VOLUME_IND or EFFECT_FLAG_VOLUME_CTRL flag in
1.462 +// its descriptor to receive this command before every call to process() function
1.463 +// If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return
1.464 +// the volume that should be applied before the effect is processed. The overall volume (the volume
1.465 +// actually applied by the effect engine multiplied by the returned value) should match the value
1.466 +// indicated in the command.
1.467 +//--------------------------------------------------------------------------------------------------
1.468 +// command format:
1.469 +// size: n * sizeof(uint32_t)
1.470 +// data: volume for each channel defined in effect_config_t for output buffer expressed in
1.471 +// 8.24 fixed point format
1.472 +//--------------------------------------------------------------------------------------------------
1.473 +// reply format:
1.474 +// size: n * sizeof(uint32_t) / 0
1.475 +// data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor:
1.476 +// volume for each channel defined in effect_config_t for output buffer expressed in
1.477 +// 8.24 fixed point format
1.478 +// - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor:
1.479 +// N/A
1.480 +// It is legal to receive a null pointer as pReplyData in which case the effect framework has
1.481 +// delegated volume control to another effect
1.482 +//==================================================================================================
1.483 +// command: EFFECT_CMD_SET_AUDIO_MODE
1.484 +//--------------------------------------------------------------------------------------------------
1.485 +// description:
1.486 +// Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its
1.487 +// descriptor to receive this command when the audio mode changes.
1.488 +//--------------------------------------------------------------------------------------------------
1.489 +// command format:
1.490 +// size: sizeof(uint32_t)
1.491 +// data: audio_mode_e
1.492 +//--------------------------------------------------------------------------------------------------
1.493 +// reply format:
1.494 +// size: 0
1.495 +// data: N/A
1.496 +//==================================================================================================
1.497 +// command: EFFECT_CMD_FIRST_PROPRIETARY
1.498 +//--------------------------------------------------------------------------------------------------
1.499 +// description:
1.500 +// All proprietary effect commands must use command codes above this value. The size and format of
1.501 +// command and response fields is free in this case
1.502 +//==================================================================================================
1.503 +
1.504 +
1.505 +// Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t
1.506 +// structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with
1.507 +// regard to the channel mask definition in audio_channels_e e.g :
1.508 +// Stereo: left, right
1.509 +// 5 point 1: front left, front right, front center, low frequency, back left, back right
1.510 +// The buffer size is expressed in frame count, a frame being composed of samples for all
1.511 +// channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by
1.512 +// definition
1.513 +struct audio_buffer_s {
1.514 + size_t frameCount; // number of frames in buffer
1.515 + union {
1.516 + void* raw; // raw pointer to start of buffer
1.517 + int32_t* s32; // pointer to signed 32 bit data at start of buffer
1.518 + int16_t* s16; // pointer to signed 16 bit data at start of buffer
1.519 + uint8_t* u8; // pointer to unsigned 8 bit data at start of buffer
1.520 + };
1.521 +};
1.522 +
1.523 +// The buffer_provider_s structure contains functions that can be used
1.524 +// by the effect engine process() function to query and release input
1.525 +// or output audio buffer.
1.526 +// The getBuffer() function is called to retrieve a buffer where data
1.527 +// should read from or written to by process() function.
1.528 +// The releaseBuffer() function MUST be called when the buffer retrieved
1.529 +// with getBuffer() is not needed anymore.
1.530 +// The process function should use the buffer provider mechanism to retrieve
1.531 +// input or output buffer if the inBuffer or outBuffer passed as argument is NULL
1.532 +// and the buffer configuration (buffer_config_t) given by the EFFECT_CMD_CONFIGURE
1.533 +// command did not specify an audio buffer.
1.534 +
1.535 +typedef int32_t (* buffer_function_t)(void *cookie, audio_buffer_t *buffer);
1.536 +
1.537 +typedef struct buffer_provider_s {
1.538 + buffer_function_t getBuffer; // retrieve next buffer
1.539 + buffer_function_t releaseBuffer; // release used buffer
1.540 + void *cookie; // for use by client of buffer provider functions
1.541 +} buffer_provider_t;
1.542 +
1.543 +
1.544 +// The buffer_config_s structure specifies the input or output audio format
1.545 +// to be used by the effect engine. It is part of the effect_config_t
1.546 +// structure that defines both input and output buffer configurations and is
1.547 +// passed by the EFFECT_CMD_CONFIGURE command.
1.548 +typedef struct buffer_config_s {
1.549 + audio_buffer_t buffer; // buffer for use by process() function if not passed explicitly
1.550 + uint32_t samplingRate; // sampling rate
1.551 + uint32_t channels; // channel mask (see audio_channels_e)
1.552 + buffer_provider_t bufferProvider; // buffer provider
1.553 + uint8_t format; // Audio format (see audio_format_e)
1.554 + uint8_t accessMode; // read/write or accumulate in buffer (effect_buffer_access_e)
1.555 + uint16_t mask; // indicates which of the above fields is valid
1.556 +} buffer_config_t;
1.557 +
1.558 +// Sample format
1.559 +enum audio_format_e {
1.560 + SAMPLE_FORMAT_PCM_S15, // PCM signed 16 bits
1.561 + SAMPLE_FORMAT_PCM_U8, // PCM unsigned 8 bits
1.562 + SAMPLE_FORMAT_PCM_S7_24, // PCM signed 7.24 fixed point representation
1.563 + SAMPLE_FORMAT_OTHER // other format (e.g. compressed)
1.564 +};
1.565 +
1.566 +// Channel mask
1.567 +enum audio_channels_e {
1.568 + CHANNEL_FRONT_LEFT = 0x1, // front left channel
1.569 + CHANNEL_FRONT_RIGHT = 0x2, // front right channel
1.570 + CHANNEL_FRONT_CENTER = 0x4, // front center channel
1.571 + CHANNEL_LOW_FREQUENCY = 0x8, // low frequency channel
1.572 + CHANNEL_BACK_LEFT = 0x10, // back left channel
1.573 + CHANNEL_BACK_RIGHT = 0x20, // back right channel
1.574 + CHANNEL_FRONT_LEFT_OF_CENTER = 0x40, // front left of center channel
1.575 + CHANNEL_FRONT_RIGHT_OF_CENTER = 0x80, // front right of center channel
1.576 + CHANNEL_BACK_CENTER = 0x100, // back center channel
1.577 + CHANNEL_MONO = CHANNEL_FRONT_LEFT,
1.578 + CHANNEL_STEREO = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT),
1.579 + CHANNEL_QUAD = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
1.580 + CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT),
1.581 + CHANNEL_SURROUND = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
1.582 + CHANNEL_FRONT_CENTER | CHANNEL_BACK_CENTER),
1.583 + CHANNEL_5POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
1.584 + CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT),
1.585 + CHANNEL_7POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
1.586 + CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT |
1.587 + CHANNEL_FRONT_LEFT_OF_CENTER | CHANNEL_FRONT_RIGHT_OF_CENTER),
1.588 +};
1.589 +
1.590 +// Render device
1.591 +enum audio_device_e {
1.592 + DEVICE_EARPIECE = 0x1, // earpiece
1.593 + DEVICE_SPEAKER = 0x2, // speaker
1.594 + DEVICE_WIRED_HEADSET = 0x4, // wired headset, with microphone
1.595 + DEVICE_WIRED_HEADPHONE = 0x8, // wired headphone, without microphone
1.596 + DEVICE_BLUETOOTH_SCO = 0x10, // generic bluetooth SCO
1.597 + DEVICE_BLUETOOTH_SCO_HEADSET = 0x20, // bluetooth SCO headset
1.598 + DEVICE_BLUETOOTH_SCO_CARKIT = 0x40, // bluetooth SCO car kit
1.599 + DEVICE_BLUETOOTH_A2DP = 0x80, // generic bluetooth A2DP
1.600 + DEVICE_BLUETOOTH_A2DP_HEADPHONES = 0x100, // bluetooth A2DP headphones
1.601 + DEVICE_BLUETOOTH_A2DP_SPEAKER = 0x200, // bluetooth A2DP speakers
1.602 + DEVICE_AUX_DIGITAL = 0x400, // digital output
1.603 + DEVICE_EXTERNAL_SPEAKER = 0x800 // external speaker (stereo and High quality)
1.604 +};
1.605 +
1.606 +#if ANDROID_VERSION < 17
1.607 +// Audio mode
1.608 +enum audio_mode_e {
1.609 + AUDIO_MODE_NORMAL, // device idle
1.610 + AUDIO_MODE_RINGTONE, // device ringing
1.611 + AUDIO_MODE_IN_CALL // audio call connected (VoIP or telephony)
1.612 +};
1.613 +#endif
1.614 +
1.615 +// Values for "accessMode" field of buffer_config_t:
1.616 +// overwrite, read only, accumulate (read/modify/write)
1.617 +enum effect_buffer_access_e {
1.618 + EFFECT_BUFFER_ACCESS_WRITE,
1.619 + EFFECT_BUFFER_ACCESS_READ,
1.620 + EFFECT_BUFFER_ACCESS_ACCUMULATE
1.621 +
1.622 +};
1.623 +
1.624 +// Values for bit field "mask" in buffer_config_t. If a bit is set, the corresponding field
1.625 +// in buffer_config_t must be taken into account when executing the EFFECT_CMD_CONFIGURE command
1.626 +#define EFFECT_CONFIG_BUFFER 0x0001 // buffer field must be taken into account
1.627 +#define EFFECT_CONFIG_SMP_RATE 0x0002 // samplingRate field must be taken into account
1.628 +#define EFFECT_CONFIG_CHANNELS 0x0004 // channels field must be taken into account
1.629 +#define EFFECT_CONFIG_FORMAT 0x0008 // format field must be taken into account
1.630 +#define EFFECT_CONFIG_ACC_MODE 0x0010 // accessMode field must be taken into account
1.631 +#define EFFECT_CONFIG_PROVIDER 0x0020 // bufferProvider field must be taken into account
1.632 +#define EFFECT_CONFIG_ALL (EFFECT_CONFIG_BUFFER | EFFECT_CONFIG_SMP_RATE | \
1.633 + EFFECT_CONFIG_CHANNELS | EFFECT_CONFIG_FORMAT | \
1.634 + EFFECT_CONFIG_ACC_MODE | EFFECT_CONFIG_PROVIDER)
1.635 +
1.636 +
1.637 +// effect_config_s structure describes the format of the pCmdData argument of EFFECT_CMD_CONFIGURE
1.638 +// command to configure audio parameters and buffers for effect engine input and output.
1.639 +typedef struct effect_config_s {
1.640 + buffer_config_t inputCfg;
1.641 + buffer_config_t outputCfg;;
1.642 +} effect_config_t;
1.643 +
1.644 +
1.645 +// effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM
1.646 +// command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command.
1.647 +// psize and vsize represent the actual size of parameter and value.
1.648 +//
1.649 +// NOTE: the start of value field inside the data field is always on a 32 bit boundary:
1.650 +//
1.651 +// +-----------+
1.652 +// | status | sizeof(int)
1.653 +// +-----------+
1.654 +// | psize | sizeof(int)
1.655 +// +-----------+
1.656 +// | vsize | sizeof(int)
1.657 +// +-----------+
1.658 +// | | | |
1.659 +// ~ parameter ~ > psize |
1.660 +// | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int)
1.661 +// +-----------+ |
1.662 +// | padding | |
1.663 +// +-----------+
1.664 +// | | |
1.665 +// ~ value ~ > vsize
1.666 +// | | |
1.667 +// +-----------+
1.668 +
1.669 +typedef struct effect_param_s {
1.670 + int32_t status; // Transaction status (unused for command, used for reply)
1.671 + uint32_t psize; // Parameter size
1.672 + uint32_t vsize; // Value size
1.673 + char data[]; // Start of Parameter + Value data
1.674 +} effect_param_t;
1.675 +
1.676 +
1.677 +/////////////////////////////////////////////////
1.678 +// Effect library interface
1.679 +/////////////////////////////////////////////////
1.680 +
1.681 +// An effect library is required to implement and expose the following functions
1.682 +// to enable effect enumeration and instantiation. The name of these functions must be as
1.683 +// specified here as the effect framework will get the function address with dlsym():
1.684 +//
1.685 +// - effect_QueryNumberEffects_t EffectQueryNumberEffects;
1.686 +// - effect_QueryEffect_t EffectQueryEffect;
1.687 +// - effect_CreateEffect_t EffectCreate;
1.688 +// - effect_ReleaseEffect_t EffectRelease;
1.689 +
1.690 +
1.691 +////////////////////////////////////////////////////////////////////////////////
1.692 +//
1.693 +// Function: EffectQueryNumberEffects
1.694 +//
1.695 +// Description: Returns the number of different effects exposed by the
1.696 +// library. Each effect must have a unique effect uuid (see
1.697 +// effect_descriptor_t). This function together with EffectQueryEffect()
1.698 +// is used to enumerate all effects present in the library.
1.699 +//
1.700 +// Input/Output:
1.701 +// pNumEffects: address where the number of effects should be returned.
1.702 +//
1.703 +// Output:
1.704 +// returned value: 0 successful operation.
1.705 +// -ENODEV library failed to initialize
1.706 +// -EINVAL invalid pNumEffects
1.707 +// *pNumEffects: updated with number of effects in library
1.708 +//
1.709 +////////////////////////////////////////////////////////////////////////////////
1.710 +typedef int32_t (*effect_QueryNumberEffects_t)(uint32_t *pNumEffects);
1.711 +
1.712 +////////////////////////////////////////////////////////////////////////////////
1.713 +//
1.714 +// Function: EffectQueryEffect
1.715 +//
1.716 +// Description: Returns the descriptor of the effect engine which index is
1.717 +// given as first argument.
1.718 +// See effect_descriptor_t for details on effect descriptors.
1.719 +// This function together with EffectQueryNumberEffects() is used to enumerate all
1.720 +// effects present in the library. The enumeration sequence is:
1.721 +// EffectQueryNumberEffects(&num_effects);
1.722 +// for (i = 0; i < num_effects; i++)
1.723 +// EffectQueryEffect(i,...);
1.724 +//
1.725 +// Input/Output:
1.726 +// index: index of the effect
1.727 +// pDescriptor: address where to return the effect descriptor.
1.728 +//
1.729 +// Output:
1.730 +// returned value: 0 successful operation.
1.731 +// -ENODEV library failed to initialize
1.732 +// -EINVAL invalid pDescriptor or index
1.733 +// -ENOSYS effect list has changed since last execution of
1.734 +// EffectQueryNumberEffects()
1.735 +// -ENOENT no more effect available
1.736 +// *pDescriptor: updated with the effect descriptor.
1.737 +//
1.738 +////////////////////////////////////////////////////////////////////////////////
1.739 +typedef int32_t (*effect_QueryEffect_t)(uint32_t index,
1.740 + effect_descriptor_t *pDescriptor);
1.741 +
1.742 +////////////////////////////////////////////////////////////////////////////////
1.743 +//
1.744 +// Function: EffectCreate
1.745 +//
1.746 +// Description: Creates an effect engine of the specified type and returns an
1.747 +// effect control interface on this engine. The function will allocate the
1.748 +// resources for an instance of the requested effect engine and return
1.749 +// a handle on the effect control interface.
1.750 +//
1.751 +// Input:
1.752 +// uuid: pointer to the effect uuid.
1.753 +// sessionId: audio session to which this effect instance will be attached. All effects
1.754 +// created with the same session ID are connected in series and process the same signal
1.755 +// stream. Knowing that two effects are part of the same effect chain can help the
1.756 +// library implement some kind of optimizations.
1.757 +// ioId: identifies the output or input stream this effect is directed to at audio HAL.
1.758 +// For future use especially with tunneled HW accelerated effects
1.759 +//
1.760 +// Input/Output:
1.761 +// pInterface: address where to return the effect interface.
1.762 +//
1.763 +// Output:
1.764 +// returned value: 0 successful operation.
1.765 +// -ENODEV library failed to initialize
1.766 +// -EINVAL invalid pEffectUuid or pInterface
1.767 +// -ENOENT no effect with this uuid found
1.768 +// *pInterface: updated with the effect interface handle.
1.769 +//
1.770 +////////////////////////////////////////////////////////////////////////////////
1.771 +typedef int32_t (*effect_CreateEffect_t)(effect_uuid_t *uuid,
1.772 + int32_t sessionId,
1.773 + int32_t ioId,
1.774 + effect_interface_t *pInterface);
1.775 +
1.776 +////////////////////////////////////////////////////////////////////////////////
1.777 +//
1.778 +// Function: EffectRelease
1.779 +//
1.780 +// Description: Releases the effect engine whose handle is given as argument.
1.781 +// All resources allocated to this particular instance of the effect are
1.782 +// released.
1.783 +//
1.784 +// Input:
1.785 +// interface: handle on the effect interface to be released.
1.786 +//
1.787 +// Output:
1.788 +// returned value: 0 successful operation.
1.789 +// -ENODEV library failed to initialize
1.790 +// -EINVAL invalid interface handle
1.791 +//
1.792 +////////////////////////////////////////////////////////////////////////////////
1.793 +typedef int32_t (*effect_ReleaseEffect_t)(effect_interface_t interface);
1.794 +
1.795 +
1.796 +#if __cplusplus
1.797 +} // extern "C"
1.798 +#endif
1.799 +
1.800 +
1.801 +#endif /*ANDROID_EFFECTAPI_H_*/
