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