1/* 2 * Copyright (C) 2010 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#ifndef ANDROID_EFFECTAPI_H_ 18#define ANDROID_EFFECTAPI_H_ 19 20#include <errno.h> 21#include <stdint.h> 22#include <sys/types.h> 23 24#if __cplusplus 25extern "C" { 26#endif 27 28///////////////////////////////////////////////// 29// Effect control interface 30///////////////////////////////////////////////// 31 32// The effect control interface is exposed by each effect engine implementation. It consists of 33// a set of functions controlling the configuration, activation and process of the engine. 34// The functions are grouped in a structure of type effect_interface_s: 35// struct effect_interface_s { 36// effect_process_t process; 37// effect_command_t command; 38// }; 39 40 41// effect_interface_t: Effect control interface handle. 42// The effect_interface_t serves two purposes regarding the implementation of the effect engine: 43// - 1 it is the address of a pointer to an effect_interface_s structure where the functions 44// of the effect control API for a particular effect are located. 45// - 2 it is the address of the context of a particular effect instance. 46// A typical implementation in the effect library would define a structure as follows: 47// struct effect_module_s { 48// const struct effect_interface_s *itfe; 49// effect_config_t config; 50// effect_context_t context; 51// } 52// The implementation of EffectCreate() function would then allocate a structure of this 53// type and return its address as effect_interface_t 54typedef struct effect_interface_s **effect_interface_t; 55 56 57// Effect API version 1.0 58#define EFFECT_API_VERSION 0x0100 // Format 0xMMmm MM: Major version, mm: minor version 59 60// Maximum length of character strings in structures defines by this API. 61#define EFFECT_STRING_LEN_MAX 64 62 63// 64//--- Effect descriptor structure effect_descriptor_t 65// 66 67// Unique effect ID (can be generated from the following site: 68// http://www.itu.int/ITU-T/asn1/uuid.html) 69// This format is used for both "type" and "uuid" fields of the effect descriptor structure. 70// - When used for effect type and the engine is implementing and effect corresponding to a standard 71// OpenSL ES interface, this ID must be the one defined in OpenSLES_IID.h for that interface. 72// - When used as uuid, it should be a unique UUID for this particular implementation. 73typedef struct effect_uuid_s { 74 uint32_t timeLow; 75 uint16_t timeMid; 76 uint16_t timeHiAndVersion; 77 uint16_t clockSeq; 78 uint8_t node[6]; 79} effect_uuid_t; 80 81// NULL UUID definition (matches SL_IID_NULL_) 82#define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \ 83 { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } } 84static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER; 85const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_; 86const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210"; 87 88// The effect descriptor contains necessary information to facilitate the enumeration of the effect 89// engines present in a library. 90typedef struct effect_descriptor_s { 91 effect_uuid_t type; // UUID of to the OpenSL ES interface implemented by this effect 92 effect_uuid_t uuid; // UUID for this particular implementation 93 uint16_t apiVersion; // Version of the effect API implemented: matches EFFECT_API_VERSION 94 uint32_t flags; // effect engine capabilities/requirements flags (see below) 95 uint16_t cpuLoad; // CPU load indication (see below) 96 uint16_t memoryUsage; // Data Memory usage (see below) 97 char name[EFFECT_STRING_LEN_MAX]; // human readable effect name 98 char implementor[EFFECT_STRING_LEN_MAX]; // human readable effect implementor name 99} effect_descriptor_t; 100 101// CPU load and memory usage indication: each effect implementation must provide an indication of 102// its CPU and memory usage for the audio effect framework to limit the number of effects 103// instantiated at a given time on a given platform. 104// The CPU load is expressed in 0.1 MIPS units as estimated on an ARM9E core (ARMv5TE) with 0 WS. 105// The memory usage is expressed in KB and includes only dynamically allocated memory 106 107// Definitions for flags field of effect descriptor. 108// +---------------------------+-----------+----------------------------------- 109// | description | bits | values 110// +---------------------------+-----------+----------------------------------- 111// | connection mode | 0..1 | 0 insert: after track process 112// | | | 1 auxiliary: connect to track auxiliary 113// | | | output and use send level 114// | | | 2 replace: replaces track process function; 115// | | | must implement SRC, volume and mono to stereo. 116// | | | 3 reserved 117// +---------------------------+-----------+----------------------------------- 118// | insertion preference | 2..4 | 0 none 119// | | | 1 first of the chain 120// | | | 2 last of the chain 121// | | | 3 exclusive (only effect in the insert chain) 122// | | | 4..7 reserved 123// +---------------------------+-----------+----------------------------------- 124// | Volume management | 5..6 | 0 none 125// | | | 1 implements volume control 126// | | | 2 requires volume indication 127// | | | 3 reserved 128// +---------------------------+-----------+----------------------------------- 129// | Device indication | 7..8 | 0 none 130// | | | 1 requires device updates 131// | | | 2..3 reserved 132// +---------------------------+-----------+----------------------------------- 133// | Sample input mode | 9..10 | 0 direct: process() function or EFFECT_CMD_CONFIGURE 134// | | | command must specify a buffer descriptor 135// | | | 1 provider: process() function uses the 136// | | | bufferProvider indicated by the 137// | | | EFFECT_CMD_CONFIGURE command to request input. 138// | | | buffers. 139// | | | 2 both: both input modes are supported 140// | | | 3 reserved 141// +---------------------------+-----------+----------------------------------- 142// | Sample output mode | 11..12 | 0 direct: process() function or EFFECT_CMD_CONFIGURE 143// | | | command must specify a buffer descriptor 144// | | | 1 provider: process() function uses the 145// | | | bufferProvider indicated by the 146// | | | EFFECT_CMD_CONFIGURE command to request output 147// | | | buffers. 148// | | | 2 both: both output modes are supported 149// | | | 3 reserved 150// +---------------------------+-----------+----------------------------------- 151// | Hardware acceleration | 13..15 | 0 No hardware acceleration 152// | | | 1 non tunneled hw acceleration: the process() function 153// | | | reads the samples, send them to HW accelerated 154// | | | effect processor, reads back the processed samples 155// | | | and returns them to the output buffer. 156// | | | 2 tunneled hw acceleration: the process() function is 157// | | | transparent. The effect interface is only used to 158// | | | control the effect engine. This mode is relevant for 159// | | | global effects actually applied by the audio 160// | | | hardware on the output stream. 161// +---------------------------+-----------+----------------------------------- 162// | Audio Mode indication | 16..17 | 0 none 163// | | | 1 requires audio mode updates 164// | | | 2..3 reserved 165// +---------------------------+-----------+----------------------------------- 166 167// Insert mode 168#define EFFECT_FLAG_TYPE_MASK 0x00000003 169#define EFFECT_FLAG_TYPE_INSERT 0x00000000 170#define EFFECT_FLAG_TYPE_AUXILIARY 0x00000001 171#define EFFECT_FLAG_TYPE_REPLACE 0x00000002 172 173// Insert preference 174#define EFFECT_FLAG_INSERT_MASK 0x0000001C 175#define EFFECT_FLAG_INSERT_ANY 0x00000000 176#define EFFECT_FLAG_INSERT_FIRST 0x00000004 177#define EFFECT_FLAG_INSERT_LAST 0x00000008 178#define EFFECT_FLAG_INSERT_EXCLUSIVE 0x0000000C 179 180 181// Volume control 182#define EFFECT_FLAG_VOLUME_MASK 0x00000060 183#define EFFECT_FLAG_VOLUME_CTRL 0x00000020 184#define EFFECT_FLAG_VOLUME_IND 0x00000040 185#define EFFECT_FLAG_VOLUME_NONE 0x00000000 186 187// Device indication 188#define EFFECT_FLAG_DEVICE_MASK 0x00000180 189#define EFFECT_FLAG_DEVICE_IND 0x00000080 190#define EFFECT_FLAG_DEVICE_NONE 0x00000000 191 192// Sample input modes 193#define EFFECT_FLAG_INPUT_MASK 0x00000600 194#define EFFECT_FLAG_INPUT_DIRECT 0x00000000 195#define EFFECT_FLAG_INPUT_PROVIDER 0x00000200 196#define EFFECT_FLAG_INPUT_BOTH 0x00000400 197 198// Sample output modes 199#define EFFECT_FLAG_OUTPUT_MASK 0x00001800 200#define EFFECT_FLAG_OUTPUT_DIRECT 0x00000000 201#define EFFECT_FLAG_OUTPUT_PROVIDER 0x00000800 202#define EFFECT_FLAG_OUTPUT_BOTH 0x00001000 203 204// Hardware acceleration mode 205#define EFFECT_FLAG_HW_ACC_MASK 0x00006000 206#define EFFECT_FLAG_HW_ACC_SIMPLE 0x00002000 207#define EFFECT_FLAG_HW_ACC_TUNNEL 0x00004000 208 209// Audio mode indication 210#define EFFECT_FLAG_AUDIO_MODE_MASK 0x00018000 211#define EFFECT_FLAG_AUDIO_MODE_IND 0x00008000 212#define EFFECT_FLAG_AUDIO_MODE_NONE 0x00000000 213 214// Forward definition of type audio_buffer_t 215typedef struct audio_buffer_s audio_buffer_t; 216 217//////////////////////////////////////////////////////////////////////////////// 218// 219// Function: process 220// 221// Description: Effect process function. Takes input samples as specified 222// (count and location) in input buffer descriptor and output processed 223// samples as specified in output buffer descriptor. If the buffer descriptor 224// is not specified the function must use either the buffer or the 225// buffer provider function installed by the EFFECT_CMD_CONFIGURE command. 226// The effect framework will call the process() function after the EFFECT_CMD_ENABLE 227// command is received and until the EFFECT_CMD_DISABLE is received. When the engine 228// receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully 229// and when done indicate that it is OK to stop calling the process() function by 230// returning the -ENODATA status. 231// 232// NOTE: the process() function implementation should be "real-time safe" that is 233// it should not perform blocking calls: malloc/free, sleep, read/write/open/close, 234// pthread_cond_wait/pthread_mutex_lock... 235// 236// Input: 237// effect_interface_t: handle to the effect interface this function 238// is called on. 239// inBuffer: buffer descriptor indicating where to read samples to process. 240// If NULL, use the configuration passed by EFFECT_CMD_CONFIGURE command. 241// 242// inBuffer: buffer descriptor indicating where to write processed samples. 243// If NULL, use the configuration passed by EFFECT_CMD_CONFIGURE command. 244// 245// Output: 246// returned value: 0 successful operation 247// -ENODATA the engine has finished the disable phase and the framework 248// can stop calling process() 249// -EINVAL invalid interface handle or 250// invalid input/output buffer description 251//////////////////////////////////////////////////////////////////////////////// 252typedef int32_t (*effect_process_t)(effect_interface_t self, 253 audio_buffer_t *inBuffer, 254 audio_buffer_t *outBuffer); 255 256//////////////////////////////////////////////////////////////////////////////// 257// 258// Function: command 259// 260// Description: Send a command and receive a response to/from effect engine. 261// 262// Input: 263// effect_interface_t: handle to the effect interface this function 264// is called on. 265// cmdCode: command code: the command can be a standardized command defined in 266// effect_command_e (see below) or a proprietary command. 267// cmdSize: size of command in bytes 268// pCmdData: pointer to command data 269// pReplyData: pointer to reply data 270// 271// Input/Output: 272// replySize: maximum size of reply data as input 273// actual size of reply data as output 274// 275// Output: 276// returned value: 0 successful operation 277// -EINVAL invalid interface handle or 278// invalid command/reply size or format according to command code 279// The return code should be restricted to indicate problems related to the this 280// API specification. Status related to the execution of a particular command should be 281// indicated as part of the reply field. 282// 283// *pReplyData updated with command response 284// 285//////////////////////////////////////////////////////////////////////////////// 286typedef int32_t (*effect_command_t)(effect_interface_t self, 287 uint32_t cmdCode, 288 uint32_t cmdSize, 289 void *pCmdData, 290 uint32_t *replySize, 291 void *pReplyData); 292 293 294// Effect control interface definition 295struct effect_interface_s { 296 effect_process_t process; 297 effect_command_t command; 298}; 299 300 301// 302//--- Standardized command codes for command() function 303// 304enum effect_command_e { 305 EFFECT_CMD_INIT, // initialize effect engine 306 EFFECT_CMD_CONFIGURE, // configure effect engine (see effect_config_t) 307 EFFECT_CMD_RESET, // reset effect engine 308 EFFECT_CMD_ENABLE, // enable effect process 309 EFFECT_CMD_DISABLE, // disable effect process 310 EFFECT_CMD_SET_PARAM, // set parameter immediately (see effect_param_t) 311 EFFECT_CMD_SET_PARAM_DEFERRED, // set parameter deferred 312 EFFECT_CMD_SET_PARAM_COMMIT, // commit previous set parameter deferred 313 EFFECT_CMD_GET_PARAM, // get parameter 314 EFFECT_CMD_SET_DEVICE, // set audio device (see audio_device_e) 315 EFFECT_CMD_SET_VOLUME, // set volume 316 EFFECT_CMD_SET_AUDIO_MODE, // set the audio mode (normal, ring, ...) 317 EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code 318}; 319 320//================================================================================================== 321// command: EFFECT_CMD_INIT 322//-------------------------------------------------------------------------------------------------- 323// description: 324// Initialize effect engine: All configurations return to default 325//-------------------------------------------------------------------------------------------------- 326// command format: 327// size: 0 328// data: N/A 329//-------------------------------------------------------------------------------------------------- 330// reply format: 331// size: sizeof(int) 332// data: status 333//================================================================================================== 334// command: EFFECT_CMD_CONFIGURE 335//-------------------------------------------------------------------------------------------------- 336// description: 337// Apply new audio parameters configurations for input and output buffers 338//-------------------------------------------------------------------------------------------------- 339// command format: 340// size: sizeof(effect_config_t) 341// data: effect_config_t 342//-------------------------------------------------------------------------------------------------- 343// reply format: 344// size: sizeof(int) 345// data: status 346//================================================================================================== 347// command: EFFECT_CMD_RESET 348//-------------------------------------------------------------------------------------------------- 349// description: 350// Reset the effect engine. Keep configuration but resets state and buffer content 351//-------------------------------------------------------------------------------------------------- 352// command format: 353// size: 0 354// data: N/A 355//-------------------------------------------------------------------------------------------------- 356// reply format: 357// size: 0 358// data: N/A 359//================================================================================================== 360// command: EFFECT_CMD_ENABLE 361//-------------------------------------------------------------------------------------------------- 362// description: 363// Enable the process. Called by the framework before the first call to process() 364//-------------------------------------------------------------------------------------------------- 365// command format: 366// size: 0 367// data: N/A 368//-------------------------------------------------------------------------------------------------- 369// reply format: 370// size: sizeof(int) 371// data: status 372//================================================================================================== 373// command: EFFECT_CMD_DISABLE 374//-------------------------------------------------------------------------------------------------- 375// description: 376// Disable the process. Called by the framework after the last call to process() 377//-------------------------------------------------------------------------------------------------- 378// command format: 379// size: 0 380// data: N/A 381//-------------------------------------------------------------------------------------------------- 382// reply format: 383// size: sizeof(int) 384// data: status 385//================================================================================================== 386// command: EFFECT_CMD_SET_PARAM 387//-------------------------------------------------------------------------------------------------- 388// description: 389// Set a parameter and apply it immediately 390//-------------------------------------------------------------------------------------------------- 391// command format: 392// size: sizeof(effect_param_t) + size of param and value 393// data: effect_param_t + param + value. See effect_param_t definition below for value offset 394//-------------------------------------------------------------------------------------------------- 395// reply format: 396// size: sizeof(int) 397// data: status 398//================================================================================================== 399// command: EFFECT_CMD_SET_PARAM_DEFERRED 400//-------------------------------------------------------------------------------------------------- 401// description: 402// Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command 403//-------------------------------------------------------------------------------------------------- 404// command format: 405// size: sizeof(effect_param_t) + size of param and value 406// data: effect_param_t + param + value. See effect_param_t definition below for value offset 407//-------------------------------------------------------------------------------------------------- 408// reply format: 409// size: 0 410// data: N/A 411//================================================================================================== 412// command: EFFECT_CMD_SET_PARAM_COMMIT 413//-------------------------------------------------------------------------------------------------- 414// description: 415// Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands 416//-------------------------------------------------------------------------------------------------- 417// command format: 418// size: 0 419// data: N/A 420//-------------------------------------------------------------------------------------------------- 421// reply format: 422// size: sizeof(int) 423// data: status 424//================================================================================================== 425// command: EFFECT_CMD_GET_PARAM 426//-------------------------------------------------------------------------------------------------- 427// description: 428// Get a parameter value 429//-------------------------------------------------------------------------------------------------- 430// command format: 431// size: sizeof(effect_param_t) + size of param 432// data: effect_param_t + param 433//-------------------------------------------------------------------------------------------------- 434// reply format: 435// size: sizeof(effect_param_t) + size of param and value 436// data: effect_param_t + param + value. See effect_param_t definition below for value offset 437//================================================================================================== 438// command: EFFECT_CMD_SET_DEVICE 439//-------------------------------------------------------------------------------------------------- 440// description: 441// Set the rendering device the audio output path is connected to. See audio_device_e for device 442// values. 443// The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this 444// command when the device changes 445//-------------------------------------------------------------------------------------------------- 446// command format: 447// size: sizeof(uint32_t) 448// data: audio_device_e 449//-------------------------------------------------------------------------------------------------- 450// reply format: 451// size: 0 452// data: N/A 453//================================================================================================== 454// command: EFFECT_CMD_SET_VOLUME 455//-------------------------------------------------------------------------------------------------- 456// description: 457// Set and get volume. Used by audio framework to delegate volume control to effect engine. 458// The effect implementation must set EFFECT_FLAG_VOLUME_IND or EFFECT_FLAG_VOLUME_CTRL flag in 459// its descriptor to receive this command before every call to process() function 460// If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return 461// the volume that should be applied before the effect is processed. The overall volume (the volume 462// actually applied by the effect engine multiplied by the returned value) should match the value 463// indicated in the command. 464//-------------------------------------------------------------------------------------------------- 465// command format: 466// size: n * sizeof(uint32_t) 467// data: volume for each channel defined in effect_config_t for output buffer expressed in 468// 8.24 fixed point format 469//-------------------------------------------------------------------------------------------------- 470// reply format: 471// size: n * sizeof(uint32_t) / 0 472// data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor: 473// volume for each channel defined in effect_config_t for output buffer expressed in 474// 8.24 fixed point format 475// - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor: 476// N/A 477// It is legal to receive a null pointer as pReplyData in which case the effect framework has 478// delegated volume control to another effect 479//================================================================================================== 480// command: EFFECT_CMD_SET_AUDIO_MODE 481//-------------------------------------------------------------------------------------------------- 482// description: 483// Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its 484// descriptor to receive this command when the audio mode changes. 485//-------------------------------------------------------------------------------------------------- 486// command format: 487// size: sizeof(uint32_t) 488// data: audio_mode_e 489//-------------------------------------------------------------------------------------------------- 490// reply format: 491// size: 0 492// data: N/A 493//================================================================================================== 494// command: EFFECT_CMD_FIRST_PROPRIETARY 495//-------------------------------------------------------------------------------------------------- 496// description: 497// All proprietary effect commands must use command codes above this value. The size and format of 498// command and response fields is free in this case 499//================================================================================================== 500 501 502// Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t 503// structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with 504// regard to the channel mask definition in audio_channels_e e.g : 505// Stereo: left, right 506// 5 point 1: front left, front right, front center, low frequency, back left, back right 507// The buffer size is expressed in frame count, a frame being composed of samples for all 508// channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by 509// definition 510struct audio_buffer_s { 511 size_t frameCount; // number of frames in buffer 512 union { 513 void* raw; // raw pointer to start of buffer 514 int32_t* s32; // pointer to signed 32 bit data at start of buffer 515 int16_t* s16; // pointer to signed 16 bit data at start of buffer 516 uint8_t* u8; // pointer to unsigned 8 bit data at start of buffer 517 }; 518}; 519 520// The buffer_provider_s structure contains functions that can be used 521// by the effect engine process() function to query and release input 522// or output audio buffer. 523// The getBuffer() function is called to retrieve a buffer where data 524// should read from or written to by process() function. 525// The releaseBuffer() function MUST be called when the buffer retrieved 526// with getBuffer() is not needed anymore. 527// The process function should use the buffer provider mechanism to retrieve 528// input or output buffer if the inBuffer or outBuffer passed as argument is NULL 529// and the buffer configuration (buffer_config_t) given by the EFFECT_CMD_CONFIGURE 530// command did not specify an audio buffer. 531 532typedef int32_t (* buffer_function_t)(void *cookie, audio_buffer_t *buffer); 533 534typedef struct buffer_provider_s { 535 buffer_function_t getBuffer; // retrieve next buffer 536 buffer_function_t releaseBuffer; // release used buffer 537 void *cookie; // for use by client of buffer provider functions 538} buffer_provider_t; 539 540 541// The buffer_config_s structure specifies the input or output audio format 542// to be used by the effect engine. It is part of the effect_config_t 543// structure that defines both input and output buffer configurations and is 544// passed by the EFFECT_CMD_CONFIGURE command. 545typedef struct buffer_config_s { 546 audio_buffer_t buffer; // buffer for use by process() function if not passed explicitly 547 uint32_t samplingRate; // sampling rate 548 uint32_t channels; // channel mask (see audio_channels_e) 549 buffer_provider_t bufferProvider; // buffer provider 550 uint8_t format; // Audio format (see audio_format_e) 551 uint8_t accessMode; // read/write or accumulate in buffer (effect_buffer_access_e) 552 uint16_t mask; // indicates which of the above fields is valid 553} buffer_config_t; 554 555// Sample format 556enum audio_format_e { 557 SAMPLE_FORMAT_PCM_S15, // PCM signed 16 bits 558 SAMPLE_FORMAT_PCM_U8, // PCM unsigned 8 bits 559 SAMPLE_FORMAT_PCM_S7_24, // PCM signed 7.24 fixed point representation 560 SAMPLE_FORMAT_OTHER // other format (e.g. compressed) 561}; 562 563// Channel mask 564enum audio_channels_e { 565 CHANNEL_FRONT_LEFT = 0x1, // front left channel 566 CHANNEL_FRONT_RIGHT = 0x2, // front right channel 567 CHANNEL_FRONT_CENTER = 0x4, // front center channel 568 CHANNEL_LOW_FREQUENCY = 0x8, // low frequency channel 569 CHANNEL_BACK_LEFT = 0x10, // back left channel 570 CHANNEL_BACK_RIGHT = 0x20, // back right channel 571 CHANNEL_FRONT_LEFT_OF_CENTER = 0x40, // front left of center channel 572 CHANNEL_FRONT_RIGHT_OF_CENTER = 0x80, // front right of center channel 573 CHANNEL_BACK_CENTER = 0x100, // back center channel 574 CHANNEL_MONO = CHANNEL_FRONT_LEFT, 575 CHANNEL_STEREO = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT), 576 CHANNEL_QUAD = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 577 CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT), 578 CHANNEL_SURROUND = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 579 CHANNEL_FRONT_CENTER | CHANNEL_BACK_CENTER), 580 CHANNEL_5POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 581 CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT), 582 CHANNEL_7POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 583 CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT | 584 CHANNEL_FRONT_LEFT_OF_CENTER | CHANNEL_FRONT_RIGHT_OF_CENTER), 585}; 586 587// Render device 588enum audio_device_e { 589 DEVICE_EARPIECE = 0x1, // earpiece 590 DEVICE_SPEAKER = 0x2, // speaker 591 DEVICE_WIRED_HEADSET = 0x4, // wired headset, with microphone 592 DEVICE_WIRED_HEADPHONE = 0x8, // wired headphone, without microphone 593 DEVICE_BLUETOOTH_SCO = 0x10, // generic bluetooth SCO 594 DEVICE_BLUETOOTH_SCO_HEADSET = 0x20, // bluetooth SCO headset 595 DEVICE_BLUETOOTH_SCO_CARKIT = 0x40, // bluetooth SCO car kit 596 DEVICE_BLUETOOTH_A2DP = 0x80, // generic bluetooth A2DP 597 DEVICE_BLUETOOTH_A2DP_HEADPHONES = 0x100, // bluetooth A2DP headphones 598 DEVICE_BLUETOOTH_A2DP_SPEAKER = 0x200, // bluetooth A2DP speakers 599 DEVICE_AUX_DIGITAL = 0x400, // digital output 600 DEVICE_EXTERNAL_SPEAKER = 0x800 // external speaker (stereo and High quality) 601}; 602 603// Audio mode 604enum audio_mode_e { 605 AUDIO_MODE_NORMAL, // device idle 606 AUDIO_MODE_RINGTONE, // device ringing 607 AUDIO_MODE_IN_CALL // audio call connected (VoIP or telephony) 608}; 609 610// Values for "accessMode" field of buffer_config_t: 611// overwrite, read only, accumulate (read/modify/write) 612enum effect_buffer_access_e { 613 EFFECT_BUFFER_ACCESS_WRITE, 614 EFFECT_BUFFER_ACCESS_READ, 615 EFFECT_BUFFER_ACCESS_ACCUMULATE 616 617}; 618 619// Values for bit field "mask" in buffer_config_t. If a bit is set, the corresponding field 620// in buffer_config_t must be taken into account when executing the EFFECT_CMD_CONFIGURE command 621#define EFFECT_CONFIG_BUFFER 0x0001 // buffer field must be taken into account 622#define EFFECT_CONFIG_SMP_RATE 0x0002 // samplingRate field must be taken into account 623#define EFFECT_CONFIG_CHANNELS 0x0004 // channels field must be taken into account 624#define EFFECT_CONFIG_FORMAT 0x0008 // format field must be taken into account 625#define EFFECT_CONFIG_ACC_MODE 0x0010 // accessMode field must be taken into account 626#define EFFECT_CONFIG_PROVIDER 0x0020 // bufferProvider field must be taken into account 627#define EFFECT_CONFIG_ALL (EFFECT_CONFIG_BUFFER | EFFECT_CONFIG_SMP_RATE | \ 628 EFFECT_CONFIG_CHANNELS | EFFECT_CONFIG_FORMAT | \ 629 EFFECT_CONFIG_ACC_MODE | EFFECT_CONFIG_PROVIDER) 630 631 632// effect_config_s structure describes the format of the pCmdData argument of EFFECT_CMD_CONFIGURE 633// command to configure audio parameters and buffers for effect engine input and output. 634typedef struct effect_config_s { 635 buffer_config_t inputCfg; 636 buffer_config_t outputCfg;; 637} effect_config_t; 638 639 640// effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM 641// command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command. 642// psize and vsize represent the actual size of parameter and value. 643// 644// NOTE: the start of value field inside the data field is always on a 32 bit boundary: 645// 646// +-----------+ 647// | status | sizeof(int) 648// +-----------+ 649// | psize | sizeof(int) 650// +-----------+ 651// | vsize | sizeof(int) 652// +-----------+ 653// | | | | 654// ~ parameter ~ > psize | 655// | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int) 656// +-----------+ | 657// | padding | | 658// +-----------+ 659// | | | 660// ~ value ~ > vsize 661// | | | 662// +-----------+ 663 664typedef struct effect_param_s { 665 int32_t status; // Transaction status (unused for command, used for reply) 666 uint32_t psize; // Parameter size 667 uint32_t vsize; // Value size 668 char data[]; // Start of Parameter + Value data 669} effect_param_t; 670 671 672///////////////////////////////////////////////// 673// Effect library interface 674///////////////////////////////////////////////// 675 676// An effect library is required to implement and expose the following functions 677// to enable effect enumeration and instantiation. The name of these functions must be as 678// specified here as the effect framework will get the function address with dlsym(): 679// 680// - effect_QueryNumberEffects_t EffectQueryNumberEffects; 681// - effect_QueryEffect_t EffectQueryEffect; 682// - effect_CreateEffect_t EffectCreate; 683// - effect_ReleaseEffect_t EffectRelease; 684 685 686//////////////////////////////////////////////////////////////////////////////// 687// 688// Function: EffectQueryNumberEffects 689// 690// Description: Returns the number of different effects exposed by the 691// library. Each effect must have a unique effect uuid (see 692// effect_descriptor_t). This function together with EffectQueryEffect() 693// is used to enumerate all effects present in the library. 694// 695// Input/Output: 696// pNumEffects: address where the number of effects should be returned. 697// 698// Output: 699// returned value: 0 successful operation. 700// -ENODEV library failed to initialize 701// -EINVAL invalid pNumEffects 702// *pNumEffects: updated with number of effects in library 703// 704//////////////////////////////////////////////////////////////////////////////// 705typedef int32_t (*effect_QueryNumberEffects_t)(uint32_t *pNumEffects); 706 707//////////////////////////////////////////////////////////////////////////////// 708// 709// Function: EffectQueryEffect 710// 711// Description: Returns the descriptor of the effect engine which index is 712// given as first argument. 713// See effect_descriptor_t for details on effect descriptors. 714// This function together with EffectQueryNumberEffects() is used to enumerate all 715// effects present in the library. The enumeration sequence is: 716// EffectQueryNumberEffects(&num_effects); 717// for (i = 0; i < num_effects; i++) 718// EffectQueryEffect(i,...); 719// 720// Input/Output: 721// index: index of the effect 722// pDescriptor: address where to return the effect descriptor. 723// 724// Output: 725// returned value: 0 successful operation. 726// -ENODEV library failed to initialize 727// -EINVAL invalid pDescriptor or index 728// -ENOSYS effect list has changed since last execution of 729// EffectQueryNumberEffects() 730// -ENOENT no more effect available 731// *pDescriptor: updated with the effect descriptor. 732// 733//////////////////////////////////////////////////////////////////////////////// 734typedef int32_t (*effect_QueryEffect_t)(uint32_t index, 735 effect_descriptor_t *pDescriptor); 736 737//////////////////////////////////////////////////////////////////////////////// 738// 739// Function: EffectCreate 740// 741// Description: Creates an effect engine of the specified type and returns an 742// effect control interface on this engine. The function will allocate the 743// resources for an instance of the requested effect engine and return 744// a handle on the effect control interface. 745// 746// Input: 747// uuid: pointer to the effect uuid. 748// sessionId: audio session to which this effect instance will be attached. All effects 749// created with the same session ID are connected in series and process the same signal 750// stream. Knowing that two effects are part of the same effect chain can help the 751// library implement some kind of optimizations. 752// ioId: identifies the output or input stream this effect is directed to at audio HAL. 753// For future use especially with tunneled HW accelerated effects 754// 755// Input/Output: 756// pInterface: address where to return the effect interface. 757// 758// Output: 759// returned value: 0 successful operation. 760// -ENODEV library failed to initialize 761// -EINVAL invalid pEffectUuid or pInterface 762// -ENOENT no effect with this uuid found 763// *pInterface: updated with the effect interface handle. 764// 765//////////////////////////////////////////////////////////////////////////////// 766typedef int32_t (*effect_CreateEffect_t)(effect_uuid_t *uuid, 767 int32_t sessionId, 768 int32_t ioId, 769 effect_interface_t *pInterface); 770 771//////////////////////////////////////////////////////////////////////////////// 772// 773// Function: EffectRelease 774// 775// Description: Releases the effect engine whose handle is given as argument. 776// All resources allocated to this particular instance of the effect are 777// released. 778// 779// Input: 780// interface: handle on the effect interface to be released. 781// 782// Output: 783// returned value: 0 successful operation. 784// -ENODEV library failed to initialize 785// -EINVAL invalid interface handle 786// 787//////////////////////////////////////////////////////////////////////////////// 788typedef int32_t (*effect_ReleaseEffect_t)(effect_interface_t interface); 789 790 791#if __cplusplus 792} // extern "C" 793#endif 794 795 796#endif /*ANDROID_EFFECTAPI_H_*/ 797