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