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 27 extern "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 //////////////////////////////////////////////////////////////////////////////// 56 ANDROID_API 57 int 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 //////////////////////////////////////////////////////////////////////////////// 84 ANDROID_API 85 int 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 //////////////////////////////////////////////////////////////////////////////// 116 ANDROID_API 117 int EffectCreate(const effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, 118 effect_handle_t *pHandle); 119 120 //////////////////////////////////////////////////////////////////////////////// 121 // 122 // Function: EffectCreateOnDevice 123 // 124 // Description: Same as EffectCreate but uesed when creating an effect attached to a 125 // particular audio device instance 126 // 127 // Input: 128 // pEffectUuid: pointer to the effect uuid. 129 // deviceId: identifies the sink or source device this effect is directed to in 130 // audio HAL. Must be specified if sessionId is AUDIO_SESSION_DEVICE. 131 // deviceId is the audio_port_handle_t used for the device when the audio 132 // patch is created at the audio HAL.// 133 // ioId: identifies the output or input stream this effect is directed to at audio HAL. 134 // For future use especially with tunneled HW accelerated effects 135 // Input/Output: 136 // pHandle: address where to return the effect handle. 137 // 138 // Output: 139 // returned value: 0 successful operation. 140 // -ENODEV factory failed to initialize 141 // -EINVAL invalid pEffectUuid or pHandle 142 // -ENOENT no effect with this uuid found 143 // *pHandle: updated with the effect handle. 144 // 145 //////////////////////////////////////////////////////////////////////////////// 146 ANDROID_API 147 int EffectCreateOnDevice(const effect_uuid_t *pEffectUuid, int32_t deviceId, int32_t ioId, 148 effect_handle_t *pHandle); 149 150 //////////////////////////////////////////////////////////////////////////////// 151 // 152 // Function: EffectRelease 153 // 154 // Description: Releases the effect engine whose handle is given as argument. 155 // All resources allocated to this particular instance of the effect are 156 // released. 157 // 158 // Input: 159 // handle: handle on the effect interface to be released. 160 // 161 // Output: 162 // returned value: 0 successful operation. 163 // -ENODEV factory failed to initialize 164 // -EINVAL invalid interface handle 165 // 166 //////////////////////////////////////////////////////////////////////////////// 167 ANDROID_API 168 int EffectRelease(effect_handle_t handle); 169 170 //////////////////////////////////////////////////////////////////////////////// 171 // 172 // Function: EffectGetDescriptor 173 // 174 // Description: Returns the descriptor of the effect which uuid is pointed 175 // to by first argument. 176 // 177 // Input: 178 // pEffectUuid: pointer to the effect uuid. 179 // 180 // Input/Output: 181 // pDescriptor: address where to return the effect descriptor. 182 // 183 // Output: 184 // returned value: 0 successful operation. 185 // -ENODEV factory failed to initialize 186 // -EINVAL invalid pEffectUuid or pDescriptor 187 // -ENOENT no effect with this uuid found 188 // *pDescriptor: updated with the effect descriptor. 189 // 190 //////////////////////////////////////////////////////////////////////////////// 191 ANDROID_API 192 int EffectGetDescriptor(const effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor); 193 194 //////////////////////////////////////////////////////////////////////////////// 195 // 196 // Function: EffectIsNullUuid 197 // 198 // Description: Helper function to compare effect uuid to EFFECT_UUID_NULL 199 // 200 // Input: 201 // pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL. 202 // 203 // Output: 204 // returned value: 0 if uuid is different from EFFECT_UUID_NULL. 205 // 1 if uuid is equal to EFFECT_UUID_NULL. 206 // 207 //////////////////////////////////////////////////////////////////////////////// 208 ANDROID_API 209 int EffectIsNullUuid(const effect_uuid_t *pEffectUuid); 210 211 ANDROID_API 212 int EffectDumpEffects(int fd); 213 214 #if __cplusplus 215 } // extern "C" 216 #endif 217 218 219 #endif /*ANDROID_EFFECTSFACTORYAPI_H_*/ 220