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