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 78 // EffectQueryNumberEffects() 79 // *pDescriptor: updated with the effect descriptor. 80 // 81 //////////////////////////////////////////////////////////////////////////////// 82 int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor); 83 84 //////////////////////////////////////////////////////////////////////////////// 85 // 86 // Function: EffectCreate 87 // 88 // Description: Creates an effect engine of the specified type and returns an 89 // effect control interface on this engine. The function will allocate the 90 // resources for an instance of the requested effect engine and return 91 // a handle on the effect control interface. 92 // 93 // Input: 94 // pEffectUuid: pointer to the effect uuid. 95 // sessionId: audio session to which this effect instance will be attached. All effects 96 // created with the same session ID are connected in series and process the same signal 97 // stream. Knowing that two effects are part of the same effect chain can help the 98 // library implement some kind of optimizations. 99 // ioId: identifies the output or input stream this effect is directed to at audio HAL. 100 // For future use especially with tunneled HW accelerated effects 101 // 102 // Input/Output: 103 // pHandle: address where to return the effect handle. 104 // 105 // Output: 106 // returned value: 0 successful operation. 107 // -ENODEV factory failed to initialize 108 // -EINVAL invalid pEffectUuid or pHandle 109 // -ENOENT no effect with this uuid found 110 // *pHandle: updated with the effect handle. 111 // 112 //////////////////////////////////////////////////////////////////////////////// 113 int EffectCreate(const effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, 114 effect_handle_t *pHandle); 115 116 //////////////////////////////////////////////////////////////////////////////// 117 // 118 // Function: EffectRelease 119 // 120 // Description: Releases the effect engine whose handle is given as argument. 121 // All resources allocated to this particular instance of the effect are 122 // released. 123 // 124 // Input: 125 // handle: handle on the effect interface to be released. 126 // 127 // Output: 128 // returned value: 0 successful operation. 129 // -ENODEV factory failed to initialize 130 // -EINVAL invalid interface handle 131 // 132 //////////////////////////////////////////////////////////////////////////////// 133 int EffectRelease(effect_handle_t handle); 134 135 //////////////////////////////////////////////////////////////////////////////// 136 // 137 // Function: EffectGetDescriptor 138 // 139 // Description: Returns the descriptor of the effect which uuid is pointed 140 // to by first argument. 141 // 142 // Input: 143 // pEffectUuid: pointer to the effect uuid. 144 // 145 // Input/Output: 146 // pDescriptor: address where to return the effect descriptor. 147 // 148 // Output: 149 // returned value: 0 successful operation. 150 // -ENODEV factory failed to initialize 151 // -EINVAL invalid pEffectUuid or pDescriptor 152 // -ENOENT no effect with this uuid found 153 // *pDescriptor: updated with the effect descriptor. 154 // 155 //////////////////////////////////////////////////////////////////////////////// 156 int EffectGetDescriptor(const effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor); 157 158 //////////////////////////////////////////////////////////////////////////////// 159 // 160 // Function: EffectIsNullUuid 161 // 162 // Description: Helper function to compare effect uuid to EFFECT_UUID_NULL 163 // 164 // Input: 165 // pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL. 166 // 167 // Output: 168 // returned value: 0 if uuid is different from EFFECT_UUID_NULL. 169 // 1 if uuid is equal to EFFECT_UUID_NULL. 170 // 171 //////////////////////////////////////////////////////////////////////////////// 172 int EffectIsNullUuid(const effect_uuid_t *pEffectUuid); 173 174 int EffectDumpEffects(int fd); 175 176 #if __cplusplus 177 } // extern "C" 178 #endif 179 180 181 #endif /*ANDROID_EFFECTSFACTORYAPI_H_*/ 182