AudioEffect.h revision 7c7f10bd4fda9a084e5e7f0eb3a040dfcbf01745
1801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent/* 2801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Copyright (C) 2009 The Android Open Source Project 3801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 4801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Licensed under the Apache License, Version 2.0 (the "License"); 5801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * you may not use this file except in compliance with the License. 6801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * You may obtain a copy of the License at 7801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 8801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * http://www.apache.org/licenses/LICENSE-2.0 9801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 10801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Unless required by applicable law or agreed to in writing, software 11801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * distributed under the License is distributed on an "AS IS" BASIS, 12801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * See the License for the specific language governing permissions and 14801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * limitations under the License. 15801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 16801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 17801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#ifndef ANDROID_AUDIOEFFECT_H 18801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#define ANDROID_AUDIOEFFECT_H 19801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 20801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <stdint.h> 21801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <sys/types.h> 22801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 23801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <media/IAudioFlinger.h> 24801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <media/IEffect.h> 25801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <media/IEffectClient.h> 26e1315cf0b63b4c14a77046519e6b01f6f60d74b0Eric Laurent#include <hardware/audio_effect.h> 27801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <media/AudioSystem.h> 28801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 29801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <utils/RefBase.h> 30801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <utils/Errors.h> 31801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#include <binder/IInterface.h> 32801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 33801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 34801a1186eb1d2ce195b15222701865932e08f3dcEric Laurentnamespace android { 35801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 36801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent// ---------------------------------------------------------------------------- 37801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 38801a1186eb1d2ce195b15222701865932e08f3dcEric Laurentclass effect_param_cblk_t; 39801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 40801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent// ---------------------------------------------------------------------------- 41801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 42801a1186eb1d2ce195b15222701865932e08f3dcEric Laurentclass AudioEffect : public RefBase 43801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent{ 44801a1186eb1d2ce195b15222701865932e08f3dcEric Laurentpublic: 45801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 46801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* 47801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Static methods for effects enumeration. 48801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 49801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 50801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* 51801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returns the number of effects available. This method together 52ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * with queryEffect() is used to enumerate all effects: 53801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * The enumeration sequence is: 54ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * queryNumberEffects(&num_effects); 55ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * for (i = 0; i < num_effects; i++) 56ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * queryEffect(i,...); 57801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 58801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 59ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * numEffects: address where the number of effects should be returned. 60801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 61801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 62801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * NO_ERROR successful operation. 63801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * PERMISSION_DENIED could not get AudioFlinger interface 64801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * NO_INIT effect library failed to initialize 65801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * BAD_VALUE invalid numEffects pointer 66801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 67801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned value 68801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * *numEffects: updated with number of effects available 69801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 70801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent static status_t queryNumberEffects(uint32_t *numEffects); 71801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 72801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* 73ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * Returns an effect descriptor during effect 74801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * enumeration. 75801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 76801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 77ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * index: index of the queried effect. 78ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * descriptor: address where the effect descriptor should be returned. 79801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 80801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 81801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * NO_ERROR successful operation. 82801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * PERMISSION_DENIED could not get AudioFlinger interface 83801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * NO_INIT effect library failed to initialize 84ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent * BAD_VALUE invalid descriptor pointer or index 85801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * INVALID_OPERATION effect list has changed since last execution of queryNumberEffects() 86801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 87801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned value 88801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * *descriptor: updated with effect descriptor 89801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 90ffe9c25ce85e1af55d58ec025adc6367d70db7e8Eric Laurent static status_t queryEffect(uint32_t index, effect_descriptor_t *descriptor); 91801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 92801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 93801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* 94801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returns the descriptor for the specified effect uuid. 95801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 96801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 97801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * uuid: pointer to effect uuid. 98801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * descriptor: address where the effect descriptor should be returned. 99801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 100801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 101801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * NO_ERROR successful operation. 102801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * PERMISSION_DENIED could not get AudioFlinger interface 103801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * NO_INIT effect library failed to initialize 104801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * BAD_VALUE invalid uuid or descriptor pointers 105801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * NAME_NOT_FOUND no effect with this uuid found 106801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 107801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned value 108801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * *descriptor updated with effect descriptor 109801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 110801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent static status_t getEffectDescriptor(effect_uuid_t *uuid, effect_descriptor_t *descriptor); 111801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 112801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 113801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* 114801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Events used by callback function (effect_callback_t). 115801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 116801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent enum event_type { 117801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent EVENT_CONTROL_STATUS_CHANGED = 0, 118801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent EVENT_ENABLE_STATUS_CHANGED = 1, 119801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent EVENT_PARAMETER_CHANGED = 2, 120801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent EVENT_ERROR = 3 121801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent }; 122801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 123801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Callback function notifying client application of a change in effect engine state or 124801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * configuration. 125801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * An effect engine can be shared by several applications but only one has the control 126801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * of the engine activity and configuration at a time. 127801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * The EVENT_CONTROL_STATUS_CHANGED event is received when an application loses or 128801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * retrieves the control of the effect engine. Loss of control happens 129801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * if another application requests the use of the engine by creating an AudioEffect for 130801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * the same effect type but with a higher priority. Control is returned when the 131801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * application having the control deletes its AudioEffect object. 132801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * The EVENT_ENABLE_STATUS_CHANGED event is received by all applications not having the 133801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * control of the effect engine when the effect is enabled or disabled. 134801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * The EVENT_PARAMETER_CHANGED event is received by all applications not having the 135801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * control of the effect engine when an effect parameter is changed. 136801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * The EVENT_ERROR event is received when the media server process dies. 137801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 138801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 139801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 140801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * event: type of event notified (see enum AudioEffect::event_type). 141801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * user: Pointer to context for use by the callback receiver. 142801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * info: Pointer to optional parameter according to event type: 143801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - EVENT_CONTROL_STATUS_CHANGED: boolean indicating if control is granted (true) 144801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * or stolen (false). 145801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - EVENT_ENABLE_STATUS_CHANGED: boolean indicating if effect is now enabled (true) 146801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * or disabled (false). 147801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - EVENT_PARAMETER_CHANGED: pointer to a effect_param_t structure. 148801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - EVENT_ERROR: status_t indicating the error (DEAD_OBJECT when media server dies). 149801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 150801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 151801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent typedef void (*effect_callback_t)(int32_t event, void* user, void *info); 152801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 153801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 154801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Constructor. 155801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * AudioEffect is the base class for creating and controlling an effect engine from 156801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * the application process. Creating an AudioEffect object will create the effect engine 157801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * in the AudioFlinger if no engine of the specified type exists. If one exists, this engine 158801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * will be used. The application creating the AudioEffect object (or a derived class like 159801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Reverb for instance) will either receive control of the effect engine or not, depending 160801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * on the priority parameter. If priority is higher than the priority used by the current 161801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * effect engine owner, the control will be transfered to the new application. Otherwise 162801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * control will remain to the previous application. In this case, the new application will be 163801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * notified of changes in effect engine state or control ownership by the effect callback. 164801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * After creating the AudioEffect, the application must call the initCheck() method and 165801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * check the creation status before trying to control the effect engine (see initCheck()). 166801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * If the effect is to be applied to an AudioTrack or MediaPlayer only the application 167801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * must specify the audio session ID corresponding to this player. 168801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 169801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 170801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Simple Constructor. 171801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 172801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent AudioEffect(); 173801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 174801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 175801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Constructor. 176801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 177801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 178801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 179801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * type: type of effect created: can be null if uuid is specified. This corresponds to 180801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * the OpenSL ES interface implemented by this effect. 181801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * uuid: Uuid of effect created: can be null if type is specified. This uuid corresponds to 182801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * a particular implementation of an effect type. 183801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * priority: requested priority for effect control: the priority level corresponds to the 184801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * value of priority parameter: negative values indicate lower priorities, positive values 185801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * higher priorities, 0 being the normal priority. 186801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * cbf: optional callback function (see effect_callback_t) 187801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * user: pointer to context for use by the callback receiver. 188801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * sessionID: audio session this effect is associated to. If 0, the effect will be global to 189801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * the output mix. If not 0, the effect will be applied to all players 190801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * (AudioTrack or MediaPLayer) within the same audio session. 1917c7f10bd4fda9a084e5e7f0eb3a040dfcbf01745Eric Laurent * io: HAL audio output or input stream to which this effect must be attached. Leave at 0 for 192801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * automatic output selection by AudioFlinger. 193801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 194801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 195801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent AudioEffect(const effect_uuid_t *type, 196801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent const effect_uuid_t *uuid = NULL, 197801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent int32_t priority = 0, 198801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent effect_callback_t cbf = 0, 199801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent void* user = 0, 200801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent int sessionId = 0, 2017c7f10bd4fda9a084e5e7f0eb3a040dfcbf01745Eric Laurent audio_io_handle_t io = 0 202801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent ); 203801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 204801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Constructor. 205801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Same as above but with type and uuid specified by character strings 206801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 207801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent AudioEffect(const char *typeStr, 208801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent const char *uuidStr = NULL, 209801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent int32_t priority = 0, 210801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent effect_callback_t cbf = 0, 211801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent void* user = 0, 212801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent int sessionId = 0, 2137c7f10bd4fda9a084e5e7f0eb3a040dfcbf01745Eric Laurent audio_io_handle_t io = 0 214801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent ); 215801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 216801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Terminates the AudioEffect and unregisters it from AudioFlinger. 217801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * The effect engine is also destroyed if this AudioEffect was the last controlling 218801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * the engine. 219801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 220801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent ~AudioEffect(); 221801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 222801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Initialize an uninitialized AudioEffect. 223801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 224801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_ERROR or ALREADY_EXISTS: successful initialization 225801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - INVALID_OPERATION: AudioEffect is already initialized 226801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - BAD_VALUE: invalid parameter 227801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_INIT: audio flinger or audio hardware not initialized 228801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * */ 229801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent status_t set(const effect_uuid_t *type, 230801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent const effect_uuid_t *uuid = NULL, 231801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent int32_t priority = 0, 232801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent effect_callback_t cbf = 0, 233801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent void* user = 0, 234801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent int sessionId = 0, 2357c7f10bd4fda9a084e5e7f0eb3a040dfcbf01745Eric Laurent audio_io_handle_t io = 0 236801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent ); 237801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 238801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Result of constructing the AudioEffect. This must be checked 239801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * before using any AudioEffect API. 240801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * initCheck() can return: 241801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_ERROR: the effect engine is successfully created and the application has control. 242801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - ALREADY_EXISTS: the effect engine is successfully created but the application does not 243801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * have control. 244801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_INIT: the effect creation failed. 245801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 246801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 247801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent status_t initCheck() const; 248801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 249801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 250801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Returns the unique effect Id for the controlled effect engine. This ID is unique 251801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * system wide and is used for instance in the case of auxiliary effects to attach 252801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * the effect to an AudioTrack or MediaPlayer. 253801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 254801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 255801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent int32_t id() const { return mId; } 256801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 257e1315cf0b63b4c14a77046519e6b01f6f60d74b0Eric Laurent /* Returns a descriptor for the effect (see effect_descriptor_t in audio_effect.h). 258801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 259801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent effect_descriptor_t descriptor() const; 260801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 261801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Returns effect control priority of this AudioEffect object. 262801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 263801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent int32_t priority() const { return mPriority; } 264801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 265801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 266da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent /* Enables or disables the effect engine. 267801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 268801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 269da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent * enabled: requested enable state. 270801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 271801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 272801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_ERROR: successful operation 273da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent * - INVALID_OPERATION: the application does not have control of the effect engine or the 274da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent * effect is already in the requested state. 275801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 276da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent virtual status_t setEnabled(bool enabled); 277da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent bool getEnabled() const; 278801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 279801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Sets a parameter value. 280801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 281801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 282801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * param: pointer to effect_param_t structure containing the parameter 283e1315cf0b63b4c14a77046519e6b01f6f60d74b0Eric Laurent * and its value (See audio_effect.h). 284801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 285801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_ERROR: successful operation. 286801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - INVALID_OPERATION: the application does not have control of the effect engine. 287801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - BAD_VALUE: invalid parameter identifier or value. 288801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - DEAD_OBJECT: the effect engine has been deleted. 289801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 290da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent virtual status_t setParameter(effect_param_t *param); 291801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 292801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Prepare a new parameter value that will be set by next call to 293801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * setParameterCommit(). This method can be used to set multiple parameters 294801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * in a synchronous manner or to avoid multiple binder calls for each 295801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * parameter. 296801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 297801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 298801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * param: pointer to effect_param_t structure containing the parameter 299e1315cf0b63b4c14a77046519e6b01f6f60d74b0Eric Laurent * and its value (See audio_effect.h). 300801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 301801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 302801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_ERROR: successful operation. 303801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - INVALID_OPERATION: the application does not have control of the effect engine. 304801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_MEMORY: no more space available in shared memory used for deferred parameter 305801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * setting. 306801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 307da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent virtual status_t setParameterDeferred(effect_param_t *param); 308801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 309801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Commit all parameter values previously prepared by setParameterDeferred(). 310801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 311801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 312801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * none 313801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 314801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 315801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_ERROR: successful operation. 316801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - INVALID_OPERATION: No new parameter values ready for commit. 317801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - BAD_VALUE: invalid parameter identifier or value: there is no indication 318801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * as to which of the parameters caused this error. 319801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - DEAD_OBJECT: the effect engine has been deleted. 320801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 321da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent virtual status_t setParameterCommit(); 322801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 323801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Gets a parameter value. 324801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 325801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Parameters: 326801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * param: pointer to effect_param_t structure containing the parameter 327e1315cf0b63b4c14a77046519e6b01f6f60d74b0Eric Laurent * and the returned value (See audio_effect.h). 328801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * 329801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Returned status (from utils/Errors.h) can be: 330801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - NO_ERROR: successful operation. 331801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - INVALID_OPERATION: the AudioEffect was not successfully initialized. 332801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - BAD_VALUE: invalid parameter identifier. 333801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * - DEAD_OBJECT: the effect engine has been deleted. 334801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 335da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent virtual status_t getParameter(effect_param_t *param); 336801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 337801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Sends a command and receives a response to/from effect engine. 338e1315cf0b63b4c14a77046519e6b01f6f60d74b0Eric Laurent * See audio_effect.h for details on effect command() function, valid command codes 339801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * and formats. 340801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 34125f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent virtual status_t command(uint32_t cmdCode, 34225f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent uint32_t cmdSize, 343da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent void *cmdData, 34425f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent uint32_t *replySize, 345da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent void *replyData); 346801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 347801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 348801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* 349801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * Utility functions. 350801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 351801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 352801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Converts the string passed as first argument to the effect_uuid_t 353801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * pointed to by second argument 354801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 355801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent static status_t stringToGuid(const char *str, effect_uuid_t *guid); 356801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent /* Converts the effect_uuid_t pointed to by first argument to the 357801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent * string passed as second argument 358801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent */ 359801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent static status_t guidToString(const effect_uuid_t *guid, char *str, size_t maxLen); 360801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 361da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurentprotected: 362f5aafb209d01ba2ab6cb55d1a12cfc653e2b4be0Eric Laurent bool mEnabled; // enable state 363da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent int32_t mSessionId; // audio session ID 364da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent int32_t mPriority; // priority for effect control 365da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent status_t mStatus; // effect status 366da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent effect_callback_t mCbf; // callback function for status, control and 367da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent // parameter changes notifications 368da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent void* mUserData; // client context for callback function 369da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent effect_descriptor_t mDescriptor; // effect descriptor 370da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent int32_t mId; // system wide unique effect engine instance ID 371f5aafb209d01ba2ab6cb55d1a12cfc653e2b4be0Eric Laurent Mutex mLock; // Mutex for mEnabled access 372da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent 373801a1186eb1d2ce195b15222701865932e08f3dcEric Laurentprivate: 374801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 375801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent // Implements the IEffectClient interface 376801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent class EffectClient : public android::BnEffectClient, public android::IBinder::DeathRecipient 377801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent { 378801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent public: 379801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 380801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent EffectClient(AudioEffect *effect) : mEffect(effect){} 381801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 382801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent // IEffectClient 383da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent virtual void controlStatusChanged(bool controlGranted) { 384da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent mEffect->controlStatusChanged(controlGranted); 385da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent } 386da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent virtual void enableStatusChanged(bool enabled) { 387da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent mEffect->enableStatusChanged(enabled); 388da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent } 38925f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent virtual void commandExecuted(uint32_t cmdCode, 39025f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent uint32_t cmdSize, 391da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent void *pCmdData, 39225f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent uint32_t replySize, 393da7581b7b61b84f15e8d671c86fd117c322b009eEric Laurent void *pReplyData) { 394801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent mEffect->commandExecuted(cmdCode, cmdSize, pCmdData, replySize, pReplyData); 395801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent } 396801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 397801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent // IBinder::DeathRecipient 398801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent virtual void binderDied(const wp<IBinder>& who) {mEffect->binderDied();} 399801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 400801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent private: 401801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent AudioEffect *mEffect; 402801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent }; 403801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 404801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 405801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent friend class EffectClient; 406801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 407801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent // IEffectClient 408801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent void controlStatusChanged(bool controlGranted); 409801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent void enableStatusChanged(bool enabled); 41025f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent void commandExecuted(uint32_t cmdCode, 41125f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent uint32_t cmdSize, 41225f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent void *pCmdData, 41325f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent uint32_t replySize, 41425f4395b932fa9859a6e91ba77c5d20d009da64aEric Laurent void *pReplyData); 415801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent void binderDied(); 416801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 417801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 418801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent sp<IEffect> mIEffect; // IEffect binder interface 419801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent sp<EffectClient> mIEffectClient; // IEffectClient implementation 420801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent sp<IMemory> mCblkMemory; // shared memory for deferred parameter setting 421801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent effect_param_cblk_t* mCblk; // control block for deferred parameter setting 422801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent}; 423801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 424801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 425801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent}; // namespace android 426801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent 427801a1186eb1d2ce195b15222701865932e08f3dcEric Laurent#endif // ANDROID_AUDIOEFFECT_H 428