EffectsFactoryApi.h revision 284c17e73bbff51cb5b1adcee98386d47733757a
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 26extern "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//////////////////////////////////////////////////////////////////////////////// 55int 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//////////////////////////////////////////////////////////////////////////////// 82int 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//////////////////////////////////////////////////////////////////////////////// 113int 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//////////////////////////////////////////////////////////////////////////////// 133int 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//////////////////////////////////////////////////////////////////////////////// 156int 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//////////////////////////////////////////////////////////////////////////////// 172int EffectIsNullUuid(const effect_uuid_t *pEffectUuid); 173 174//////////////////////////////////////////////////////////////////////////////// 175// 176// Function: EffectGetSubEffects 177// 178// Description: Returns the descriptors of the sub effects of the effect 179// whose uuid is pointed to by first argument. 180// 181// Input: 182// pEffectUuid: pointer to the effect uuid. 183// size: size of the buffer pointed by pDescriptor. 184// 185// Input/Output: 186// pDescriptor: address where to return the sub effect descriptors. 187// 188// Output: 189// returned value: 0 successful operation. 190// -ENODEV factory failed to initialize 191// -EINVAL invalid pEffectUuid or pDescriptor 192// -ENOENT no effect with this uuid found 193// *pDescriptor: updated with the sub effect descriptors. 194// 195//////////////////////////////////////////////////////////////////////////////// 196int EffectGetSubEffects(const effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptors, size_t size); 197 198#if __cplusplus 199} // extern "C" 200#endif 201 202 203#endif /*ANDROID_EFFECTSFACTORYAPI_H_*/ 204