1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18 #ifndef ANDROID_AUDIO_EFFECT_CORE_H 19 #define ANDROID_AUDIO_EFFECT_CORE_H 20 21 #include "audio.h" 22 #include "audio_effect-base.h" 23 24 __BEGIN_DECLS 25 26 ///////////////////////////////////////////////// 27 // Common Definitions 28 ///////////////////////////////////////////////// 29 30 // 31 //--- Effect descriptor structure effect_descriptor_t 32 // 33 34 // This format is used for both "type" and "uuid" fields of the effect descriptor structure. 35 // - When used for effect type and the engine is implementing and effect corresponding to a standard 36 // OpenSL ES interface, this ID must be the one defined in OpenSLES_IID.h for that interface. 37 // - When used as uuid, it should be a unique UUID for this particular implementation. 38 typedef audio_uuid_t effect_uuid_t; 39 40 // Maximum length of character strings in structures defines by this API. 41 #define EFFECT_STRING_LEN_MAX 64 42 43 // NULL UUID definition (matches SL_IID_NULL_) 44 #define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \ 45 { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } } 46 static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER; 47 static const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_; 48 static const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210"; 49 50 // The effect descriptor contains necessary information to facilitate the enumeration of the effect 51 // engines present in a library. 52 typedef struct effect_descriptor_s { 53 effect_uuid_t type; // UUID of to the OpenSL ES interface implemented by this effect 54 effect_uuid_t uuid; // UUID for this particular implementation 55 uint32_t apiVersion; // Version of the effect control API implemented 56 uint32_t flags; // effect engine capabilities/requirements flags (see below) 57 uint16_t cpuLoad; // CPU load indication (see below) 58 uint16_t memoryUsage; // Data Memory usage (see below) 59 char name[EFFECT_STRING_LEN_MAX]; // human readable effect name 60 char implementor[EFFECT_STRING_LEN_MAX]; // human readable effect implementor name 61 } effect_descriptor_t; 62 63 #define EFFECT_CONFIG_ALL (EFFECT_CONFIG_BUFFER | \ 64 EFFECT_CONFIG_SMP_RATE | \ 65 EFFECT_CONFIG_CHANNELS | \ 66 EFFECT_CONFIG_FORMAT | \ 67 EFFECT_CONFIG_ACC_MODE) 68 69 ///////////////////////////////////////////////// 70 // Effect control interface 71 ///////////////////////////////////////////////// 72 73 // 74 //--- Standardized command codes for command() function 75 // 76 enum effect_command_e { 77 EFFECT_CMD_INIT, // initialize effect engine 78 EFFECT_CMD_SET_CONFIG, // configure effect engine (see effect_config_t) 79 EFFECT_CMD_RESET, // reset effect engine 80 EFFECT_CMD_ENABLE, // enable effect process 81 EFFECT_CMD_DISABLE, // disable effect process 82 EFFECT_CMD_SET_PARAM, // set parameter immediately (see effect_param_t) 83 EFFECT_CMD_SET_PARAM_DEFERRED, // set parameter deferred 84 EFFECT_CMD_SET_PARAM_COMMIT, // commit previous set parameter deferred 85 EFFECT_CMD_GET_PARAM, // get parameter 86 EFFECT_CMD_SET_DEVICE, // set audio device (see audio.h, audio_devices_t) 87 EFFECT_CMD_SET_VOLUME, // set volume 88 EFFECT_CMD_SET_AUDIO_MODE, // set the audio mode (normal, ring, ...) 89 EFFECT_CMD_SET_CONFIG_REVERSE, // configure effect engine reverse stream(see effect_config_t) 90 EFFECT_CMD_SET_INPUT_DEVICE, // set capture device (see audio.h, audio_devices_t) 91 EFFECT_CMD_GET_CONFIG, // read effect engine configuration 92 EFFECT_CMD_GET_CONFIG_REVERSE, // read configure effect engine reverse stream configuration 93 EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS,// get all supported configurations for a feature. 94 EFFECT_CMD_GET_FEATURE_CONFIG, // get current feature configuration 95 EFFECT_CMD_SET_FEATURE_CONFIG, // set current feature configuration 96 EFFECT_CMD_SET_AUDIO_SOURCE, // set the audio source (see audio.h, audio_source_t) 97 EFFECT_CMD_OFFLOAD, // set if effect thread is an offload one, 98 // send the ioHandle of the effect thread 99 EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code 100 }; 101 102 //================================================================================================== 103 // command: EFFECT_CMD_INIT 104 //-------------------------------------------------------------------------------------------------- 105 // description: 106 // Initialize effect engine: All configurations return to default 107 //-------------------------------------------------------------------------------------------------- 108 // command format: 109 // size: 0 110 // data: N/A 111 //-------------------------------------------------------------------------------------------------- 112 // reply format: 113 // size: sizeof(int) 114 // data: status 115 //================================================================================================== 116 // command: EFFECT_CMD_SET_CONFIG 117 //-------------------------------------------------------------------------------------------------- 118 // description: 119 // Apply new audio parameters configurations for input and output buffers 120 //-------------------------------------------------------------------------------------------------- 121 // command format: 122 // size: sizeof(effect_config_t) 123 // data: effect_config_t 124 //-------------------------------------------------------------------------------------------------- 125 // reply format: 126 // size: sizeof(int) 127 // data: status 128 //================================================================================================== 129 // command: EFFECT_CMD_RESET 130 //-------------------------------------------------------------------------------------------------- 131 // description: 132 // Reset the effect engine. Keep configuration but resets state and buffer content 133 //-------------------------------------------------------------------------------------------------- 134 // command format: 135 // size: 0 136 // data: N/A 137 //-------------------------------------------------------------------------------------------------- 138 // reply format: 139 // size: 0 140 // data: N/A 141 //================================================================================================== 142 // command: EFFECT_CMD_ENABLE 143 //-------------------------------------------------------------------------------------------------- 144 // description: 145 // Enable the process. Called by the framework before the first call to process() 146 //-------------------------------------------------------------------------------------------------- 147 // command format: 148 // size: 0 149 // data: N/A 150 //-------------------------------------------------------------------------------------------------- 151 // reply format: 152 // size: sizeof(int) 153 // data: status 154 //================================================================================================== 155 // command: EFFECT_CMD_DISABLE 156 //-------------------------------------------------------------------------------------------------- 157 // description: 158 // Disable the process. Called by the framework after the last call to process() 159 //-------------------------------------------------------------------------------------------------- 160 // command format: 161 // size: 0 162 // data: N/A 163 //-------------------------------------------------------------------------------------------------- 164 // reply format: 165 // size: sizeof(int) 166 // data: status 167 //================================================================================================== 168 // command: EFFECT_CMD_SET_PARAM 169 //-------------------------------------------------------------------------------------------------- 170 // description: 171 // Set a parameter and apply it immediately 172 //-------------------------------------------------------------------------------------------------- 173 // command format: 174 // size: sizeof(effect_param_t) + size of param and value 175 // data: effect_param_t + param + value. See effect_param_t definition below for value offset 176 //-------------------------------------------------------------------------------------------------- 177 // reply format: 178 // size: sizeof(int) 179 // data: status 180 //================================================================================================== 181 // command: EFFECT_CMD_SET_PARAM_DEFERRED 182 //-------------------------------------------------------------------------------------------------- 183 // description: 184 // Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command 185 //-------------------------------------------------------------------------------------------------- 186 // command format: 187 // size: sizeof(effect_param_t) + size of param and value 188 // data: effect_param_t + param + value. See effect_param_t definition below for value offset 189 //-------------------------------------------------------------------------------------------------- 190 // reply format: 191 // size: 0 192 // data: N/A 193 //================================================================================================== 194 // command: EFFECT_CMD_SET_PARAM_COMMIT 195 //-------------------------------------------------------------------------------------------------- 196 // description: 197 // Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands 198 //-------------------------------------------------------------------------------------------------- 199 // command format: 200 // size: 0 201 // data: N/A 202 //-------------------------------------------------------------------------------------------------- 203 // reply format: 204 // size: sizeof(int) 205 // data: status 206 //================================================================================================== 207 // command: EFFECT_CMD_GET_PARAM 208 //-------------------------------------------------------------------------------------------------- 209 // description: 210 // Get a parameter value 211 //-------------------------------------------------------------------------------------------------- 212 // command format: 213 // size: sizeof(effect_param_t) + size of param 214 // data: effect_param_t + param 215 //-------------------------------------------------------------------------------------------------- 216 // reply format: 217 // size: sizeof(effect_param_t) + size of param and value 218 // data: effect_param_t + param + value. See effect_param_t definition below for value offset 219 //================================================================================================== 220 // command: EFFECT_CMD_SET_DEVICE 221 //-------------------------------------------------------------------------------------------------- 222 // description: 223 // Set the rendering device the audio output path is connected to. See audio.h, audio_devices_t 224 // for device values. 225 // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this 226 // command when the device changes 227 //-------------------------------------------------------------------------------------------------- 228 // command format: 229 // size: sizeof(uint32_t) 230 // data: uint32_t 231 //-------------------------------------------------------------------------------------------------- 232 // reply format: 233 // size: 0 234 // data: N/A 235 //================================================================================================== 236 // command: EFFECT_CMD_SET_VOLUME 237 //-------------------------------------------------------------------------------------------------- 238 // description: 239 // Set and get volume. Used by audio framework to delegate volume control to effect engine. 240 // The effect implementation must set EFFECT_FLAG_VOLUME_IND or EFFECT_FLAG_VOLUME_CTRL flag in 241 // its descriptor to receive this command before every call to process() function 242 // If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return 243 // the volume that should be applied before the effect is processed. The overall volume (the volume 244 // actually applied by the effect engine multiplied by the returned value) should match the value 245 // indicated in the command. 246 //-------------------------------------------------------------------------------------------------- 247 // command format: 248 // size: n * sizeof(uint32_t) 249 // data: volume for each channel defined in effect_config_t for output buffer expressed in 250 // 8.24 fixed point format 251 //-------------------------------------------------------------------------------------------------- 252 // reply format: 253 // size: n * sizeof(uint32_t) / 0 254 // data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor: 255 // volume for each channel defined in effect_config_t for output buffer expressed in 256 // 8.24 fixed point format 257 // - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor: 258 // N/A 259 // It is legal to receive a null pointer as pReplyData in which case the effect framework has 260 // delegated volume control to another effect 261 //================================================================================================== 262 // command: EFFECT_CMD_SET_AUDIO_MODE 263 //-------------------------------------------------------------------------------------------------- 264 // description: 265 // Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its 266 // descriptor to receive this command when the audio mode changes. 267 //-------------------------------------------------------------------------------------------------- 268 // command format: 269 // size: sizeof(uint32_t) 270 // data: audio_mode_t 271 //-------------------------------------------------------------------------------------------------- 272 // reply format: 273 // size: 0 274 // data: N/A 275 //================================================================================================== 276 // command: EFFECT_CMD_SET_CONFIG_REVERSE 277 //-------------------------------------------------------------------------------------------------- 278 // description: 279 // Apply new audio parameters configurations for input and output buffers of reverse stream. 280 // An example of reverse stream is the echo reference supplied to an Acoustic Echo Canceler. 281 //-------------------------------------------------------------------------------------------------- 282 // command format: 283 // size: sizeof(effect_config_t) 284 // data: effect_config_t 285 //-------------------------------------------------------------------------------------------------- 286 // reply format: 287 // size: sizeof(int) 288 // data: status 289 //================================================================================================== 290 // command: EFFECT_CMD_SET_INPUT_DEVICE 291 //-------------------------------------------------------------------------------------------------- 292 // description: 293 // Set the capture device the audio input path is connected to. See audio.h, audio_devices_t 294 // for device values. 295 // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this 296 // command when the device changes 297 //-------------------------------------------------------------------------------------------------- 298 // command format: 299 // size: sizeof(uint32_t) 300 // data: uint32_t 301 //-------------------------------------------------------------------------------------------------- 302 // reply format: 303 // size: 0 304 // data: N/A 305 //================================================================================================== 306 // command: EFFECT_CMD_GET_CONFIG 307 //-------------------------------------------------------------------------------------------------- 308 // description: 309 // Read audio parameters configurations for input and output buffers 310 //-------------------------------------------------------------------------------------------------- 311 // command format: 312 // size: 0 313 // data: N/A 314 //-------------------------------------------------------------------------------------------------- 315 // reply format: 316 // size: sizeof(effect_config_t) 317 // data: effect_config_t 318 //================================================================================================== 319 // command: EFFECT_CMD_GET_CONFIG_REVERSE 320 //-------------------------------------------------------------------------------------------------- 321 // description: 322 // Read audio parameters configurations for input and output buffers of reverse stream 323 //-------------------------------------------------------------------------------------------------- 324 // command format: 325 // size: 0 326 // data: N/A 327 //-------------------------------------------------------------------------------------------------- 328 // reply format: 329 // size: sizeof(effect_config_t) 330 // data: effect_config_t 331 //================================================================================================== 332 // command: EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS 333 //-------------------------------------------------------------------------------------------------- 334 // description: 335 // Queries for supported configurations for a particular feature (e.g. get the supported 336 // combinations of main and auxiliary channels for a noise suppressor). 337 // The command parameter is the feature identifier (See effect_feature_e for a list of defined 338 // features) followed by the maximum number of configuration descriptor to return. 339 // The reply is composed of: 340 // - status (uint32_t): 341 // - 0 if feature is supported 342 // - -ENOSYS if the feature is not supported, 343 // - -ENOMEM if the feature is supported but the total number of supported configurations 344 // exceeds the maximum number indicated by the caller. 345 // - total number of supported configurations (uint32_t) 346 // - an array of configuration descriptors. 347 // The actual number of descriptors returned must not exceed the maximum number indicated by 348 // the caller. 349 //-------------------------------------------------------------------------------------------------- 350 // command format: 351 // size: 2 x sizeof(uint32_t) 352 // data: effect_feature_e + maximum number of configurations to return 353 //-------------------------------------------------------------------------------------------------- 354 // reply format: 355 // size: 2 x sizeof(uint32_t) + n x sizeof (<config descriptor>) 356 // data: status + total number of configurations supported + array of n config descriptors 357 //================================================================================================== 358 // command: EFFECT_CMD_GET_FEATURE_CONFIG 359 //-------------------------------------------------------------------------------------------------- 360 // description: 361 // Retrieves current configuration for a given feature. 362 // The reply status is: 363 // - 0 if feature is supported 364 // - -ENOSYS if the feature is not supported, 365 //-------------------------------------------------------------------------------------------------- 366 // command format: 367 // size: sizeof(uint32_t) 368 // data: effect_feature_e 369 //-------------------------------------------------------------------------------------------------- 370 // reply format: 371 // size: sizeof(uint32_t) + sizeof (<config descriptor>) 372 // data: status + config descriptor 373 //================================================================================================== 374 // command: EFFECT_CMD_SET_FEATURE_CONFIG 375 //-------------------------------------------------------------------------------------------------- 376 // description: 377 // Sets current configuration for a given feature. 378 // The reply status is: 379 // - 0 if feature is supported 380 // - -ENOSYS if the feature is not supported, 381 // - -EINVAL if the configuration is invalid 382 //-------------------------------------------------------------------------------------------------- 383 // command format: 384 // size: sizeof(uint32_t) + sizeof (<config descriptor>) 385 // data: effect_feature_e + config descriptor 386 //-------------------------------------------------------------------------------------------------- 387 // reply format: 388 // size: sizeof(uint32_t) 389 // data: status 390 //================================================================================================== 391 // command: EFFECT_CMD_SET_AUDIO_SOURCE 392 //-------------------------------------------------------------------------------------------------- 393 // description: 394 // Set the audio source the capture path is configured for (Camcorder, voice recognition...). 395 // See audio.h, audio_source_t for values. 396 //-------------------------------------------------------------------------------------------------- 397 // command format: 398 // size: sizeof(uint32_t) 399 // data: uint32_t 400 //-------------------------------------------------------------------------------------------------- 401 // reply format: 402 // size: 0 403 // data: N/A 404 //================================================================================================== 405 // command: EFFECT_CMD_OFFLOAD 406 //-------------------------------------------------------------------------------------------------- 407 // description: 408 // 1.indicate if the playback thread the effect is attached to is offloaded or not 409 // 2.update the io handle of the playback thread the effect is attached to 410 //-------------------------------------------------------------------------------------------------- 411 // command format: 412 // size: sizeof(effect_offload_param_t) 413 // data: effect_offload_param_t 414 //-------------------------------------------------------------------------------------------------- 415 // reply format: 416 // size: sizeof(uint32_t) 417 // data: uint32_t 418 //-------------------------------------------------------------------------------------------------- 419 // command: EFFECT_CMD_FIRST_PROPRIETARY 420 //-------------------------------------------------------------------------------------------------- 421 // description: 422 // All proprietary effect commands must use command codes above this value. The size and format of 423 // command and response fields is free in this case 424 //================================================================================================== 425 426 // Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t 427 // structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with 428 // regard to the channel mask definition in audio.h, audio_channel_mask_t e.g : 429 // Stereo: left, right 430 // 5 point 1: front left, front right, front center, low frequency, back left, back right 431 // The buffer size is expressed in frame count, a frame being composed of samples for all 432 // channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by 433 // definition 434 typedef struct audio_buffer_s { 435 size_t frameCount; // number of frames in buffer 436 union { 437 void* raw; // raw pointer to start of buffer 438 float* f32; // pointer to float 32 bit data at start of buffer 439 int32_t* s32; // pointer to signed 32 bit data at start of buffer 440 int16_t* s16; // pointer to signed 16 bit data at start of buffer 441 uint8_t* u8; // pointer to unsigned 8 bit data at start of buffer 442 }; 443 } audio_buffer_t; 444 445 // The buffer_provider_s structure contains functions that can be used 446 // by the effect engine process() function to query and release input 447 // or output audio buffer. 448 // The getBuffer() function is called to retrieve a buffer where data 449 // should read from or written to by process() function. 450 // The releaseBuffer() function MUST be called when the buffer retrieved 451 // with getBuffer() is not needed anymore. 452 // The process function should use the buffer provider mechanism to retrieve 453 // input or output buffer if the inBuffer or outBuffer passed as argument is NULL 454 // and the buffer configuration (buffer_config_t) given by the EFFECT_CMD_SET_CONFIG 455 // command did not specify an audio buffer. 456 457 typedef int32_t (* buffer_function_t)(void *cookie, audio_buffer_t *buffer); 458 459 typedef struct buffer_provider_s { 460 buffer_function_t getBuffer; // retrieve next buffer 461 buffer_function_t releaseBuffer; // release used buffer 462 void *cookie; // for use by client of buffer provider functions 463 } buffer_provider_t; 464 465 // The buffer_config_s structure specifies the input or output audio format 466 // to be used by the effect engine. 467 typedef struct buffer_config_s { 468 audio_buffer_t buffer; // buffer for use by process() function if not passed explicitly 469 uint32_t samplingRate; // sampling rate 470 uint32_t channels; // channel mask (see audio_channel_mask_t in audio.h) 471 buffer_provider_t bufferProvider; // buffer provider 472 uint8_t format; // Audio format (see audio_format_t in audio.h) 473 uint8_t accessMode; // read/write or accumulate in buffer (effect_buffer_access_e) 474 uint16_t mask; // indicates which of the above fields is valid 475 } buffer_config_t; 476 477 // EFFECT_FEATURE_AUX_CHANNELS feature configuration descriptor. Describe a combination 478 // of main and auxiliary channels supported 479 typedef struct channel_config_s { 480 audio_channel_mask_t main_channels; // channel mask for main channels 481 audio_channel_mask_t aux_channels; // channel mask for auxiliary channels 482 } channel_config_t; 483 484 485 // effect_config_s structure is used to configure audio parameters and buffers for effect engine 486 // input and output. 487 typedef struct effect_config_s { 488 buffer_config_t inputCfg; 489 buffer_config_t outputCfg; 490 } effect_config_t; 491 492 493 // effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM 494 // command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command. 495 // psize and vsize represent the actual size of parameter and value. 496 // 497 // NOTE: the start of value field inside the data field is always on a 32 bit boundary: 498 // 499 // +-----------+ 500 // | status | sizeof(int) 501 // +-----------+ 502 // | psize | sizeof(int) 503 // +-----------+ 504 // | vsize | sizeof(int) 505 // +-----------+ 506 // | | | | 507 // ~ parameter ~ > psize | 508 // | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int) 509 // +-----------+ | 510 // | padding | | 511 // +-----------+ 512 // | | | 513 // ~ value ~ > vsize 514 // | | | 515 // +-----------+ 516 517 typedef struct effect_param_s { 518 int32_t status; // Transaction status (unused for command, used for reply) 519 uint32_t psize; // Parameter size 520 uint32_t vsize; // Value size 521 char data[]; // Start of Parameter + Value data 522 } effect_param_t; 523 524 // Maximum effect_param_t size 525 #define EFFECT_PARAM_SIZE_MAX 65536 526 527 // structure used by EFFECT_CMD_OFFLOAD command 528 typedef struct effect_offload_param_s { 529 bool isOffload; // true if the playback thread the effect is attached to is offloaded 530 int ioHandle; // io handle of the playback thread the effect is attached to 531 } effect_offload_param_t; 532 533 534 __END_DECLS 535 536 #endif // ANDROID_AUDIO_EFFECT_CORE_H 537