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 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 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 //////////////////////////////////////////////////////////////////////////////// 112 int 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 //////////////////////////////////////////////////////////////////////////////// 131 int 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 //////////////////////////////////////////////////////////////////////////////// 154 int 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 //////////////////////////////////////////////////////////////////////////////// 170 int EffectIsNullUuid(const effect_uuid_t *pEffectUuid); 171 172 #if __cplusplus 173 } // extern "C" 174 #endif 175 176 177 #endif /*ANDROID_EFFECTSFACTORYAPI_H_*/ 178