1/* 2 * Copyright (C) 2018 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 17package [email protected]; 18 19import [email protected]; 20import IEffectBufferProviderCallback; 21 22interface IEffect { 23 /** 24 * Initialize effect engine--all configurations return to default. 25 * 26 * @return retval operation completion status. 27 */ 28 @entry 29 init() generates (Result retval); 30 31 /** 32 * Apply new audio parameters configurations for input and output buffers. 33 * The provider callbacks may be empty, but in this case the buffer 34 * must be provided in the EffectConfig structure. 35 * 36 * @param config configuration descriptor. 37 * @param inputBufferProvider optional buffer provider reference. 38 * @param outputBufferProvider optional buffer provider reference. 39 * @return retval operation completion status. 40 */ 41 setConfig(EffectConfig config, 42 IEffectBufferProviderCallback inputBufferProvider, 43 IEffectBufferProviderCallback outputBufferProvider) 44 generates (Result retval); 45 46 /** 47 * Reset the effect engine. Keep configuration but resets state and buffer 48 * content. 49 * 50 * @return retval operation completion status. 51 */ 52 reset() generates (Result retval); 53 54 /** 55 * Enable processing. 56 * 57 * @return retval operation completion status. 58 */ 59 @callflow(next={"prepareForProcessing"}) 60 enable() generates (Result retval); 61 62 /** 63 * Disable processing. 64 * 65 * @return retval operation completion status. 66 */ 67 @callflow(next={"close"}) 68 disable() generates (Result retval); 69 70 /** 71 * Set the rendering device the audio output path is connected to. The 72 * effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its 73 * descriptor to receive this command when the device changes. 74 * 75 * Note: this method is only supported for effects inserted into 76 * the output chain. 77 * 78 * @param device output device specification. 79 * @return retval operation completion status. 80 */ 81 setDevice(bitfield<AudioDevice> device) generates (Result retval); 82 83 /** 84 * Set and get volume. Used by audio framework to delegate volume control to 85 * effect engine. The effect implementation must set EFFECT_FLAG_VOLUME_CTRL 86 * flag in its descriptor to receive this command. The effect engine must 87 * return the volume that should be applied before the effect is 88 * processed. The overall volume (the volume actually applied by the effect 89 * engine multiplied by the returned value) should match the value indicated 90 * in the command. 91 * 92 * @param volumes vector containing volume for each channel defined in 93 * EffectConfig for output buffer expressed in 8.24 fixed 94 * point format. 95 * @return result updated volume values. 96 * @return retval operation completion status. 97 */ 98 setAndGetVolume(vec<uint32_t> volumes) 99 generates (Result retval, vec<uint32_t> result); 100 101 /** 102 * Notify the effect of the volume change. The effect implementation must 103 * set EFFECT_FLAG_VOLUME_IND flag in its descriptor to receive this 104 * command. 105 * 106 * @param volumes vector containing volume for each channel defined in 107 * EffectConfig for output buffer expressed in 8.24 fixed 108 * point format. 109 * @return retval operation completion status. 110 */ 111 volumeChangeNotification(vec<uint32_t> volumes) 112 generates (Result retval); 113 114 /** 115 * Set the audio mode. The effect implementation must set 116 * EFFECT_FLAG_AUDIO_MODE_IND flag in its descriptor to receive this command 117 * when the audio mode changes. 118 * 119 * @param mode desired audio mode. 120 * @return retval operation completion status. 121 */ 122 setAudioMode(AudioMode mode) generates (Result retval); 123 124 /** 125 * Apply new audio parameters configurations for input and output buffers of 126 * reverse stream. An example of reverse stream is the echo reference 127 * supplied to an Acoustic Echo Canceler. 128 * 129 * @param config configuration descriptor. 130 * @param inputBufferProvider optional buffer provider reference. 131 * @param outputBufferProvider optional buffer provider reference. 132 * @return retval operation completion status. 133 */ 134 setConfigReverse(EffectConfig config, 135 IEffectBufferProviderCallback inputBufferProvider, 136 IEffectBufferProviderCallback outputBufferProvider) 137 generates (Result retval); 138 139 /** 140 * Set the capture device the audio input path is connected to. The effect 141 * implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to 142 * receive this command when the device changes. 143 * 144 * Note: this method is only supported for effects inserted into 145 * the input chain. 146 * 147 * @param device input device specification. 148 * @return retval operation completion status. 149 */ 150 setInputDevice(bitfield<AudioDevice> device) generates (Result retval); 151 152 /** 153 * Read audio parameters configurations for input and output buffers. 154 * 155 * @return retval operation completion status. 156 * @return config configuration descriptor. 157 */ 158 getConfig() generates (Result retval, EffectConfig config); 159 160 /** 161 * Read audio parameters configurations for input and output buffers of 162 * reverse stream. 163 * 164 * @return retval operation completion status. 165 * @return config configuration descriptor. 166 */ 167 getConfigReverse() generates (Result retval, EffectConfig config); 168 169 /** 170 * Queries for supported combinations of main and auxiliary channels 171 * (e.g. for a multi-microphone noise suppressor). 172 * 173 * @param maxConfigs maximum number of the combinations to return. 174 * @return retval absence of the feature support is indicated using 175 * NOT_SUPPORTED code. RESULT_TOO_BIG is returned if 176 * the number of supported combinations exceeds 'maxConfigs'. 177 * @return result list of configuration descriptors. 178 */ 179 getSupportedAuxChannelsConfigs(uint32_t maxConfigs) 180 generates (Result retval, vec<EffectAuxChannelsConfig> result); 181 182 /** 183 * Retrieves the current configuration of main and auxiliary channels. 184 * 185 * @return retval absence of the feature support is indicated using 186 * NOT_SUPPORTED code. 187 * @return result configuration descriptor. 188 */ 189 getAuxChannelsConfig() 190 generates (Result retval, EffectAuxChannelsConfig result); 191 192 /** 193 * Sets the current configuration of main and auxiliary channels. 194 * 195 * @return retval operation completion status; absence of the feature 196 * support is indicated using NOT_SUPPORTED code. 197 */ 198 setAuxChannelsConfig(EffectAuxChannelsConfig config) 199 generates (Result retval); 200 201 /** 202 * Set the audio source the capture path is configured for (Camcorder, voice 203 * recognition...). 204 * 205 * Note: this method is only supported for effects inserted into 206 * the input chain. 207 * 208 * @param source source descriptor. 209 * @return retval operation completion status. 210 */ 211 setAudioSource(AudioSource source) generates (Result retval); 212 213 /** 214 * This command indicates if the playback thread the effect is attached to 215 * is offloaded or not, and updates the I/O handle of the playback thread 216 * the effect is attached to. 217 * 218 * @param param effect offload descriptor. 219 * @return retval operation completion status. 220 */ 221 offload(EffectOffloadParameter param) generates (Result retval); 222 223 /** 224 * Returns the effect descriptor. 225 * 226 * @return retval operation completion status. 227 * @return descriptor effect descriptor. 228 */ 229 getDescriptor() generates (Result retval, EffectDescriptor descriptor); 230 231 /** 232 * Set up required transports for passing audio buffers to the effect. 233 * 234 * The transport consists of shared memory and a message queue for reporting 235 * effect processing operation status. The shared memory is set up 236 * separately using 'setProcessBuffers' method. 237 * 238 * Processing is requested by setting 'REQUEST_PROCESS' or 239 * 'REQUEST_PROCESS_REVERSE' EventFlags associated with the status message 240 * queue. The result of processing may be one of the following: 241 * OK if there were no errors during processing; 242 * INVALID_ARGUMENTS if audio buffers are invalid; 243 * INVALID_STATE if the engine has finished the disable phase; 244 * NOT_INITIALIZED if the audio buffers were not set; 245 * NOT_SUPPORTED if the requested processing type is not supported by 246 * the effect. 247 * 248 * @return retval OK if both message queues were created successfully. 249 * INVALID_STATE if the method was already called. 250 * INVALID_ARGUMENTS if there was a problem setting up 251 * the queue. 252 * @return statusMQ a message queue used for passing status from the effect. 253 */ 254 @callflow(next={"setProcessBuffers"}) 255 prepareForProcessing() generates (Result retval, fmq_sync<Result> statusMQ); 256 257 /** 258 * Set up input and output buffers for processing audio data. The effect 259 * may modify both the input and the output buffer during the operation. 260 * Buffers may be set multiple times during effect lifetime. 261 * 262 * The input and the output buffer may be reused between different effects, 263 * and the input buffer may be used as an output buffer. Buffers are 264 * distinguished using 'AudioBuffer.id' field. 265 * 266 * @param inBuffer input audio buffer. 267 * @param outBuffer output audio buffer. 268 * @return retval OK if both buffers were mapped successfully. 269 * INVALID_ARGUMENTS if there was a problem with mapping 270 * any of the buffers. 271 */ 272 setProcessBuffers(AudioBuffer inBuffer, AudioBuffer outBuffer) 273 generates (Result retval); 274 275 /** 276 * Execute a vendor specific command on the effect. The command code 277 * and data, as well as result data are not interpreted by Android 278 * Framework and are passed as-is between the application and the effect. 279 * 280 * The effect must use standard POSIX.1-2001 error codes for the operation 281 * completion status. 282 * 283 * Use this method only if the effect is provided by a third party, and 284 * there is no interface defined for it. This method only works for effects 285 * implemented in software. 286 * 287 * @param commandId the ID of the command. 288 * @param data command data. 289 * @param resultMaxSize maximum size in bytes of the result; can be 0. 290 * @return status command completion status. 291 * @return result result data. 292 */ 293 command(uint32_t commandId, vec<uint8_t> data, uint32_t resultMaxSize) 294 generates (int32_t status, vec<uint8_t> result); 295 296 /** 297 * Set a vendor-specific parameter and apply it immediately. The parameter 298 * code and data are not interpreted by Android Framework and are passed 299 * as-is between the application and the effect. 300 * 301 * The effect must use INVALID_ARGUMENTS return code if the parameter ID is 302 * unknown or if provided parameter data is invalid. If the effect does not 303 * support setting vendor-specific parameters, it must return NOT_SUPPORTED. 304 * 305 * Use this method only if the effect is provided by a third party, and 306 * there is no interface defined for it. This method only works for effects 307 * implemented in software. 308 * 309 * @param parameter identifying data of the parameter. 310 * @param value the value of the parameter. 311 * @return retval operation completion status. 312 */ 313 setParameter(vec<uint8_t> parameter, vec<uint8_t> value) 314 generates (Result retval); 315 316 /** 317 * Get a vendor-specific parameter value. The parameter code and returned 318 * data are not interpreted by Android Framework and are passed as-is 319 * between the application and the effect. 320 * 321 * The effect must use INVALID_ARGUMENTS return code if the parameter ID is 322 * unknown. If the effect does not support setting vendor-specific 323 * parameters, it must return NOT_SUPPORTED. 324 * 325 * Use this method only if the effect is provided by a third party, and 326 * there is no interface defined for it. This method only works for effects 327 * implemented in software. 328 * 329 * @param parameter identifying data of the parameter. 330 * @param valueMaxSize maximum size in bytes of the value. 331 * @return retval operation completion status. 332 * @return result the value of the parameter. 333 */ 334 getParameter(vec<uint8_t> parameter, uint32_t valueMaxSize) 335 generates (Result retval, vec<uint8_t> value); 336 337 /** 338 * Get supported configs for a vendor-specific feature. The configs returned 339 * are not interpreted by Android Framework and are passed as-is between the 340 * application and the effect. 341 * 342 * The effect must use INVALID_ARGUMENTS return code if the feature ID is 343 * unknown. If the effect does not support getting vendor-specific feature 344 * configs, it must return NOT_SUPPORTED. If the feature is supported but 345 * the total number of supported configurations exceeds the maximum number 346 * indicated by the caller, the method must return RESULT_TOO_BIG. 347 * 348 * Use this method only if the effect is provided by a third party, and 349 * there is no interface defined for it. This method only works for effects 350 * implemented in software. 351 * 352 * @param featureId feature identifier. 353 * @param maxConfigs maximum number of configs to return. 354 * @param configSize size of each config in bytes. 355 * @return retval operation completion status. 356 * @return configsCount number of configs returned. 357 * @return configsData data for all the configs returned. 358 */ 359 getSupportedConfigsForFeature( 360 uint32_t featureId, 361 uint32_t maxConfigs, 362 uint32_t configSize) generates ( 363 Result retval, 364 uint32_t configsCount, 365 vec<uint8_t> configsData); 366 367 /** 368 * Get the current config for a vendor-specific feature. The config returned 369 * is not interpreted by Android Framework and is passed as-is between the 370 * application and the effect. 371 * 372 * The effect must use INVALID_ARGUMENTS return code if the feature ID is 373 * unknown. If the effect does not support getting vendor-specific 374 * feature configs, it must return NOT_SUPPORTED. 375 * 376 * Use this method only if the effect is provided by a third party, and 377 * there is no interface defined for it. This method only works for effects 378 * implemented in software. 379 * 380 * @param featureId feature identifier. 381 * @param configSize size of the config in bytes. 382 * @return retval operation completion status. 383 * @return configData config data. 384 */ 385 getCurrentConfigForFeature(uint32_t featureId, uint32_t configSize) 386 generates (Result retval, vec<uint8_t> configData); 387 388 /** 389 * Set the current config for a vendor-specific feature. The config data 390 * is not interpreted by Android Framework and is passed as-is between the 391 * application and the effect. 392 * 393 * The effect must use INVALID_ARGUMENTS return code if the feature ID is 394 * unknown. If the effect does not support getting vendor-specific 395 * feature configs, it must return NOT_SUPPORTED. 396 * 397 * Use this method only if the effect is provided by a third party, and 398 * there is no interface defined for it. This method only works for effects 399 * implemented in software. 400 * 401 * @param featureId feature identifier. 402 * @param configData config data. 403 * @return retval operation completion status. 404 */ 405 setCurrentConfigForFeature(uint32_t featureId, vec<uint8_t> configData) 406 generates (Result retval); 407 408 /** 409 * Called by the framework to deinitialize the effect and free up 410 * all the currently allocated resources. It is recommended to close 411 * the effect on the client side as soon as it is becomes unused. 412 * 413 * @return retval OK in case the success. 414 * INVALID_STATE if the effect was already closed. 415 */ 416 @exit 417 close() generates (Result retval); 418}; 419