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 <media/EffectApi.h> 24 25 #if __cplusplus 26 extern "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 //////////////////////////////////////////////////////////////////////////////// 55 int 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 //////////////////////////////////////////////////////////////////////////////// 81 int 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 handler 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 // pInterface: address where to return the effect interface. 103 // 104 // Output: 105 // returned value: 0 successful operation. 106 // -ENODEV factory failed to initialize 107 // -EINVAL invalid pEffectUuid or pInterface 108 // -ENOENT no effect with this uuid found 109 // *pInterface: updated with the effect interface. 110 // 111 //////////////////////////////////////////////////////////////////////////////// 112 int EffectCreate(effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, effect_interface_t *pInterface); 113 114 //////////////////////////////////////////////////////////////////////////////// 115 // 116 // Function: EffectRelease 117 // 118 // Description: Releases the effect engine whose handler is given as argument. 119 // All resources allocated to this particular instance of the effect are 120 // released. 121 // 122 // Input: 123 // interface: handler 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 handler 129 // 130 //////////////////////////////////////////////////////////////////////////////// 131 int EffectRelease(effect_interface_t interface); 132 133 //////////////////////////////////////////////////////////////////////////////// 134 // 135 // Function: EffectLoadLibrary 136 // 137 // Description: Loads the effect library which path is given as first argument. 138 // This must be the full path of a dynamic library (.so) implementing one or 139 // more effect engines and exposing the effect library interface described in 140 // EffectApi.h. The function returns a handle on the library for used by 141 // further call to EffectUnloadLibrary() to unload the library. 142 // 143 // Input: 144 // libPath: full path of the dynamic library file in the file system. 145 // 146 // handle: address where to return the library handle 147 // 148 // Output: 149 // returned value: 0 successful operation. 150 // -ENODEV effect factory not initialized or 151 // library could not be loaded or 152 // library does not implement required functions 153 // -EINVAL invalid libPath string or handle 154 // 155 //////////////////////////////////////////////////////////////////////////////// 156 int EffectLoadLibrary(const char *libPath, int *handle); 157 158 //////////////////////////////////////////////////////////////////////////////// 159 // 160 // Function: EffectUnloadLibrary 161 // 162 // Description: Unloads the effect library which handle is given as argument. 163 // 164 // Input: 165 // handle: library handle 166 // 167 // Output: 168 // returned value: 0 successful operation. 169 // -ENODEV effect factory not initialized 170 // -ENOENT invalid handle 171 // 172 //////////////////////////////////////////////////////////////////////////////// 173 int EffectUnloadLibrary(int handle); 174 175 176 177 //////////////////////////////////////////////////////////////////////////////// 178 // 179 // Function: EffectGetDescriptor 180 // 181 // Description: Returns the descriptor of the effect which uuid is pointed 182 // to by first argument. 183 // 184 // Input: 185 // pEffectUuid: pointer to the effect uuid. 186 // 187 // Input/Output: 188 // pDescriptor: address where to return the effect descriptor. 189 // 190 // Output: 191 // returned value: 0 successful operation. 192 // -ENODEV factory failed to initialize 193 // -EINVAL invalid pEffectUuid or pDescriptor 194 // -ENOENT no effect with this uuid found 195 // *pDescriptor: updated with the effect descriptor. 196 // 197 //////////////////////////////////////////////////////////////////////////////// 198 int EffectGetDescriptor(effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor); 199 200 //////////////////////////////////////////////////////////////////////////////// 201 // 202 // Function: EffectIsNullUuid 203 // 204 // Description: Helper function to compare effect uuid to EFFECT_UUID_NULL 205 // 206 // Input: 207 // pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL. 208 // 209 // Output: 210 // returned value: 0 if uuid is different from EFFECT_UUID_NULL. 211 // 1 if uuid is equal to EFFECT_UUID_NULL. 212 // 213 //////////////////////////////////////////////////////////////////////////////// 214 int EffectIsNullUuid(effect_uuid_t *pEffectUuid); 215 216 #if __cplusplus 217 } // extern "C" 218 #endif 219 220 221 #endif /*ANDROID_EFFECTSFACTORYAPI_H_*/ 222
