1e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman/* 2e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * Copyright (C) 2010 The Android Open Source Project 3e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * 4e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * Licensed under the Apache License, Version 2.0 (the "License"); 5e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * you may not use this file except in compliance with the License. 6e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * You may obtain a copy of the License at 7e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * 8e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * http://www.apache.org/licenses/LICENSE-2.0 9e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * 10e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * Unless required by applicable law or agreed to in writing, software 11e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * distributed under the License is distributed on an "AS IS" BASIS, 12e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * See the License for the specific language governing permissions and 14e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman * limitations under the License. 15e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman */ 16e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 17e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#ifndef ANDROID_EFFECTSFACTORYAPI_H_ 18e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#define ANDROID_EFFECTSFACTORYAPI_H_ 19e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 20007709c5eb305b1ac3fcaaf35fbd7eb5aa8e672aKevin Rocard#include <cutils/compiler.h> 21e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#include <errno.h> 22e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#include <stdint.h> 23e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#include <sys/types.h> 24e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#include <hardware/audio_effect.h> 25e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 26e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#if __cplusplus 27e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatramanextern "C" { 28e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#endif 29e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 30e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman///////////////////////////////////////////////// 31e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Effect factory interface 32e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman///////////////////////////////////////////////// 33e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 34e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 35e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 36e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Function: EffectQueryNumberEffects 37e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 38e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Description: Returns the number of different effects in all loaded libraries. 39e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Each effect must have a different effect uuid (see 40e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// effect_descriptor_t). This function together with EffectQueryEffect() 41e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// is used to enumerate all effects present in all loaded libraries. 42e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Each time EffectQueryNumberEffects() is called, the factory must 43e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// reset the index of the effect descriptor returned by next call to 44e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// EffectQueryEffect() to restart enumeration from the beginning. 45e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 46e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Input/Output: 47e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// pNumEffects: address where the number of effects should be returned. 48e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 49e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Output: 50e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// returned value: 0 successful operation. 51e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENODEV factory failed to initialize 52e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -EINVAL invalid pNumEffects 53e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// *pNumEffects: updated with number of effects in factory 54e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 55e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 56007709c5eb305b1ac3fcaaf35fbd7eb5aa8e672aKevin RocardANDROID_API 57e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatramanint EffectQueryNumberEffects(uint32_t *pNumEffects); 58e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 59e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 60e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 61e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Function: EffectQueryEffect 62e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 63e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Description: Returns a descriptor of the next available effect. 64e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// See effect_descriptor_t for a details on effect descriptor. 65e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// This function together with EffectQueryNumberEffects() is used to enumerate all 66e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// effects present in all loaded libraries. The enumeration sequence is: 67e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// EffectQueryNumberEffects(&num_effects); 68e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// for (i = 0; i < num_effects; i++) 69e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// EffectQueryEffect(i,...); 70e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 71e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Input/Output: 72e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// pDescriptor: address where to return the effect descriptor. 73e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 74e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Output: 75e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// returned value: 0 successful operation. 76e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENOENT no more effect available 77e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENODEV factory failed to initialize 78e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -EINVAL invalid pDescriptor 79e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENOSYS effect list has changed since last execution of 80e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// EffectQueryNumberEffects() 81e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// *pDescriptor: updated with the effect descriptor. 82e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 83e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 84007709c5eb305b1ac3fcaaf35fbd7eb5aa8e672aKevin RocardANDROID_API 85e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatramanint EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor); 86e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 87e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 88e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 89e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Function: EffectCreate 90e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 91e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Description: Creates an effect engine of the specified type and returns an 92e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// effect control interface on this engine. The function will allocate the 93e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// resources for an instance of the requested effect engine and return 94e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// a handle on the effect control interface. 95e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 96e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Input: 97e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// pEffectUuid: pointer to the effect uuid. 98e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// sessionId: audio session to which this effect instance will be attached. All effects 99e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// created with the same session ID are connected in series and process the same signal 100e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// stream. Knowing that two effects are part of the same effect chain can help the 101e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// library implement some kind of optimizations. 102e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// ioId: identifies the output or input stream this effect is directed to at audio HAL. 103e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// For future use especially with tunneled HW accelerated effects 104e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 105e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Input/Output: 106e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// pHandle: address where to return the effect handle. 107e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 108e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Output: 109e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// returned value: 0 successful operation. 110e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENODEV factory failed to initialize 111e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -EINVAL invalid pEffectUuid or pHandle 112e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENOENT no effect with this uuid found 113e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// *pHandle: updated with the effect handle. 114e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 115e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 116007709c5eb305b1ac3fcaaf35fbd7eb5aa8e672aKevin RocardANDROID_API 117e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatramanint EffectCreate(const effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, 118e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman effect_handle_t *pHandle); 119e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 120e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 121e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 122e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Function: EffectRelease 123e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 124e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Description: Releases the effect engine whose handle is given as argument. 125e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// All resources allocated to this particular instance of the effect are 126e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// released. 127e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 128e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Input: 129e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// handle: handle on the effect interface to be released. 130e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 131e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Output: 132e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// returned value: 0 successful operation. 133e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENODEV factory failed to initialize 134e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -EINVAL invalid interface handle 135e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 136e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 137007709c5eb305b1ac3fcaaf35fbd7eb5aa8e672aKevin RocardANDROID_API 138e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatramanint EffectRelease(effect_handle_t handle); 139e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 140e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 141e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 142e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Function: EffectGetDescriptor 143e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 144e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Description: Returns the descriptor of the effect which uuid is pointed 145e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// to by first argument. 146e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 147e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Input: 148e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// pEffectUuid: pointer to the effect uuid. 149e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 150e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Input/Output: 151e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// pDescriptor: address where to return the effect descriptor. 152e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 153e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Output: 154e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// returned value: 0 successful operation. 155e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENODEV factory failed to initialize 156e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -EINVAL invalid pEffectUuid or pDescriptor 157e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// -ENOENT no effect with this uuid found 158e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// *pDescriptor: updated with the effect descriptor. 159e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 160e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 161007709c5eb305b1ac3fcaaf35fbd7eb5aa8e672aKevin RocardANDROID_API 162e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatramanint EffectGetDescriptor(const effect_uuid_t *pEffectUuid, effect_descriptor_t *pDescriptor); 163e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 164e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 165e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 166e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Function: EffectIsNullUuid 167e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 168e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Description: Helper function to compare effect uuid to EFFECT_UUID_NULL 169e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 170e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Input: 171e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// pEffectUuid: pointer to effect uuid to compare to EFFECT_UUID_NULL. 172e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 173e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// Output: 174e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// returned value: 0 if uuid is different from EFFECT_UUID_NULL. 175e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 1 if uuid is equal to EFFECT_UUID_NULL. 176e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman// 177e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman//////////////////////////////////////////////////////////////////////////////// 178007709c5eb305b1ac3fcaaf35fbd7eb5aa8e672aKevin RocardANDROID_API 179e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatramanint EffectIsNullUuid(const effect_uuid_t *pEffectUuid); 180e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 181007709c5eb305b1ac3fcaaf35fbd7eb5aa8e672aKevin RocardANDROID_API 182e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatramanint EffectDumpEffects(int fd); 183e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 184e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#if __cplusplus 185e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman} // extern "C" 186e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#endif 187e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 188e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman 189e2b43843fd12783188edd2c54188ea8d26864788Vijay Venkatraman#endif /*ANDROID_EFFECTSFACTORYAPI_H_*/ 190