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 EffectQueryNumberEffects() 78// *pDescriptor: updated with the effect descriptor. 79// 80//////////////////////////////////////////////////////////////////////////////// 81int 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//////////////////////////////////////////////////////////////////////////////// 112int 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//////////////////////////////////////////////////////////////////////////////// 131int 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//////////////////////////////////////////////////////////////////////////////// 154int 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//////////////////////////////////////////////////////////////////////////////// 170int EffectIsNullUuid(const effect_uuid_t *pEffectUuid); 171 172#if __cplusplus 173} // extern "C" 174#endif 175 176 177#endif /*ANDROID_EFFECTSFACTORYAPI_H_*/ 178