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: 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 //////////////////////////////////////////////////////////////////////////////// 137 ANDROID_API 138 int 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 //////////////////////////////////////////////////////////////////////////////// 161 ANDROID_API 162 int 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 //////////////////////////////////////////////////////////////////////////////// 178 ANDROID_API 179 int EffectIsNullUuid(const effect_uuid_t *pEffectUuid); 180 181 ANDROID_API 182 int EffectDumpEffects(int fd); 183 184 #if __cplusplus 185 } // extern "C" 186 #endif 187 188 189 #endif /*ANDROID_EFFECTSFACTORYAPI_H_*/ 190
