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