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_EFFECTSFACTORYAPI_H_
18#define ANDROID_EFFECTSFACTORYAPI_H_
19
20#include <cutils/compiler.h>
21#include <errno.h>
22#include <stdint.h>
23#include <sys/types.h>
24#include <hardware/audio_effect.h>
25
26#if __cplusplus
27extern "C" {
28#endif
29
30/////////////////////////////////////////////////
31//      Effect factory interface
32/////////////////////////////////////////////////
33
34////////////////////////////////////////////////////////////////////////////////
35//
36//    Function:       EffectQueryNumberEffects
37//
38//    Description:    Returns the number of different effects in all loaded libraries.
39//          Each effect must have a different effect uuid (see
40//          effect_descriptor_t). This function together with EffectQueryEffect()
41//          is used to enumerate all effects present in all loaded libraries.
42//          Each time EffectQueryNumberEffects() is called, the factory must
43//          reset the index of the effect descriptor returned by next call to
44//          EffectQueryEffect() to restart enumeration from the beginning.
45//
46//    Input/Output:
47//          pNumEffects:    address where the number of effects should be returned.
48//
49//    Output:
50//        returned value:    0          successful operation.
51//                          -ENODEV     factory failed to initialize
52//                          -EINVAL     invalid pNumEffects
53//        *pNumEffects:     updated with number of effects in factory
54//
55////////////////////////////////////////////////////////////////////////////////
56ANDROID_API
57int EffectQueryNumberEffects(uint32_t *pNumEffects);
58
59////////////////////////////////////////////////////////////////////////////////
60//
61//    Function:       EffectQueryEffect
62//
63//    Description:    Returns a descriptor of the next available effect.
64//          See effect_descriptor_t for a details on effect descriptor.
65//          This function together with EffectQueryNumberEffects() is used to enumerate all
66//          effects present in all loaded libraries. The enumeration sequence is:
67//              EffectQueryNumberEffects(&num_effects);
68//              for (i = 0; i < num_effects; i++)
69//                  EffectQueryEffect(i,...);
70//
71//    Input/Output:
72//          pDescriptor:    address where to return the effect descriptor.
73//
74//    Output:
75//        returned value:    0          successful operation.
76//                          -ENOENT     no more effect available
77//                          -ENODEV     factory failed to initialize
78//                          -EINVAL     invalid pDescriptor
79//                          -ENOSYS     effect list has changed since last execution of
80//                                      EffectQueryNumberEffects()
81//        *pDescriptor:     updated with the effect descriptor.
82//
83////////////////////////////////////////////////////////////////////////////////
84ANDROID_API
85int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor);
86
87////////////////////////////////////////////////////////////////////////////////
88//
89//    Function:       EffectCreate
90//
91//    Description:    Creates an effect engine of the specified type and returns an
92//          effect control interface on this engine. The function will allocate the
93//          resources for an instance of the requested effect engine and return
94//          a handle on the effect control interface.
95//
96//    Input:
97//          pEffectUuid:    pointer to the effect uuid.
98//          sessionId:  audio session to which this effect instance will be attached. All effects
99//              created with the same session ID are connected in series and process the same signal
100//              stream.  Knowing that two effects are part of the same effect chain can help the
101//              library implement some kind of optimizations.
102//          ioId:   identifies the output or input stream this effect is directed to at audio HAL.
103//              For future use especially with tunneled HW accelerated effects
104//
105//    Input/Output:
106//          pHandle:        address where to return the effect handle.
107//
108//    Output:
109//        returned value:    0          successful operation.
110//                          -ENODEV     factory failed to initialize
111//                          -EINVAL     invalid pEffectUuid or pHandle
112//                          -ENOENT     no effect with this uuid found
113//        *pHandle:         updated with the effect handle.
114//
115////////////////////////////////////////////////////////////////////////////////
116ANDROID_API
117int EffectCreate(const effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId,
118        effect_handle_t *pHandle);
119
120////////////////////////////////////////////////////////////////////////////////
121//
122//    Function:       EffectRelease
123//
124//    Description:    Releases the effect engine whose handle is given as argument.
125//          All resources allocated to this particular instance of the effect are
126//          released.
127//
128//    Input:
129//          handle:    handle on the effect interface to be released.
130//
131//    Output:
132//        returned value:    0          successful operation.
133//                          -ENODEV     factory failed to initialize
134//                          -EINVAL     invalid interface handle
135//
136////////////////////////////////////////////////////////////////////////////////
137ANDROID_API
138int EffectRelease(effect_handle_t handle);
139
140////////////////////////////////////////////////////////////////////////////////
141//
142//    Function:       EffectGetDescriptor
143//
144//    Description:    Returns the descriptor of the effect which uuid is pointed
145//          to by first argument.
146//
147//    Input:
148//          pEffectUuid:    pointer to the effect uuid.
149//
150//    Input/Output:
151//          pDescriptor:    address where to return the effect descriptor.
152//
153//    Output:
154//        returned value:    0          successful operation.
155//                          -ENODEV     factory failed to initialize
156//                          -EINVAL     invalid pEffectUuid or pDescriptor
157//                          -ENOENT     no effect with this uuid found
158//        *pDescriptor:     updated with the effect descriptor.
159//
160////////////////////////////////////////////////////////////////////////////////
161ANDROID_API
162int EffectGetDescriptor(const effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor);
163
164////////////////////////////////////////////////////////////////////////////////
165//
166//    Function:       EffectIsNullUuid
167//
168//    Description:    Helper function to compare effect uuid to EFFECT_UUID_NULL
169//
170//    Input:
171//          pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL.
172//
173//    Output:
174//        returned value:    0 if uuid is different from EFFECT_UUID_NULL.
175//                           1 if uuid is equal to EFFECT_UUID_NULL.
176//
177////////////////////////////////////////////////////////////////////////////////
178ANDROID_API
179int EffectIsNullUuid(const effect_uuid_t *pEffectUuid);
180
181ANDROID_API
182int EffectDumpEffects(int fd);
183
184#if __cplusplus
185}  // extern "C"
186#endif
187
188
189#endif /*ANDROID_EFFECTSFACTORYAPI_H_*/
190