125a9e5561a7f14e79b04f713a515a9464b9ea077Steven Moreland/* 2 * Copyright (C) 2009 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_AUDIOEFFECT_H 18#define ANDROID_AUDIOEFFECT_H 19 20#include <stdint.h> 21#include <sys/types.h> 22 23#include <media/IAudioFlinger.h> 24#include <media/IAudioPolicyService.h> 25#include <media/IEffect.h> 26#include <media/IEffectClient.h> 27#include <media/AudioSystem.h> 28#include <system/audio_effect.h> 29 30#include <utils/RefBase.h> 31#include <utils/Errors.h> 32#include <binder/IInterface.h> 33 34 35namespace android { 36 37// ---------------------------------------------------------------------------- 38 39struct effect_param_cblk_t; 40 41// ---------------------------------------------------------------------------- 42 43class AudioEffect : public RefBase 44{ 45public: 46 47 /* 48 * Static methods for effects enumeration. 49 */ 50 51 /* 52 * Returns the number of effects available. This method together 53 * with queryEffect() is used to enumerate all effects: 54 * The enumeration sequence is: 55 * queryNumberEffects(&num_effects); 56 * for (i = 0; i < num_effects; i++) 57 * queryEffect(i,...); 58 * 59 * Parameters: 60 * numEffects: address where the number of effects should be returned. 61 * 62 * Returned status (from utils/Errors.h) can be: 63 * NO_ERROR successful operation. 64 * PERMISSION_DENIED could not get AudioFlinger interface 65 * NO_INIT effect library failed to initialize 66 * BAD_VALUE invalid numEffects pointer 67 * 68 * Returned value 69 * *numEffects: updated with number of effects available 70 */ 71 static status_t queryNumberEffects(uint32_t *numEffects); 72 73 /* 74 * Returns an effect descriptor during effect 75 * enumeration. 76 * 77 * Parameters: 78 * index: index of the queried effect. 79 * descriptor: address where the effect descriptor should be returned. 80 * 81 * Returned status (from utils/Errors.h) can be: 82 * NO_ERROR successful operation. 83 * PERMISSION_DENIED could not get AudioFlinger interface 84 * NO_INIT effect library failed to initialize 85 * BAD_VALUE invalid descriptor pointer or index 86 * INVALID_OPERATION effect list has changed since last execution of queryNumberEffects() 87 * 88 * Returned value 89 * *descriptor: updated with effect descriptor 90 */ 91 static status_t queryEffect(uint32_t index, effect_descriptor_t *descriptor); 92 93 94 /* 95 * Returns the descriptor for the specified effect uuid. 96 * 97 * Parameters: 98 * uuid: pointer to effect uuid. 99 * descriptor: address where the effect descriptor should be returned. 100 * 101 * Returned status (from utils/Errors.h) can be: 102 * NO_ERROR successful operation. 103 * PERMISSION_DENIED could not get AudioFlinger interface 104 * NO_INIT effect library failed to initialize 105 * BAD_VALUE invalid uuid or descriptor pointers 106 * NAME_NOT_FOUND no effect with this uuid found 107 * 108 * Returned value 109 * *descriptor updated with effect descriptor 110 */ 111 static status_t getEffectDescriptor(const effect_uuid_t *uuid, 112 effect_descriptor_t *descriptor) /*const*/; 113 114 115 /* 116 * Returns a list of descriptors corresponding to the pre processings enabled by default 117 * on an AudioRecord with the supplied audio session ID. 118 * 119 * Parameters: 120 * audioSession: audio session ID. 121 * descriptors: address where the effect descriptors should be returned. 122 * count: as input, the maximum number of descriptor than should be returned 123 * as output, the number of descriptor returned if status is NO_ERROR or the actual 124 * number of enabled pre processings if status is NO_MEMORY 125 * 126 * Returned status (from utils/Errors.h) can be: 127 * NO_ERROR successful operation. 128 * NO_MEMORY the number of descriptor to return is more than the maximum number 129 * indicated by count. 130 * PERMISSION_DENIED could not get AudioFlinger interface 131 * NO_INIT effect library failed to initialize 132 * BAD_VALUE invalid audio session or descriptor pointers 133 * 134 * Returned value 135 * *descriptor updated with descriptors of pre processings enabled by default 136 * *count number of descriptors returned if returned status is NO_ERROR. 137 * total number of pre processing enabled by default if returned status is 138 * NO_MEMORY. This happens if the count passed as input is less than the number 139 * of descriptors to return. 140 * *count is limited to kMaxPreProcessing on return. 141 */ 142 static status_t queryDefaultPreProcessing(audio_session_t audioSession, 143 effect_descriptor_t *descriptors, 144 uint32_t *count); 145 146 /* 147 * Events used by callback function (effect_callback_t). 148 */ 149 enum event_type { 150 EVENT_CONTROL_STATUS_CHANGED = 0, 151 EVENT_ENABLE_STATUS_CHANGED = 1, 152 EVENT_PARAMETER_CHANGED = 2, 153 EVENT_ERROR = 3 154 }; 155 156 /* Callback function notifying client application of a change in effect engine state or 157 * configuration. 158 * An effect engine can be shared by several applications but only one has the control 159 * of the engine activity and configuration at a time. 160 * The EVENT_CONTROL_STATUS_CHANGED event is received when an application loses or 161 * retrieves the control of the effect engine. Loss of control happens 162 * if another application requests the use of the engine by creating an AudioEffect for 163 * the same effect type but with a higher priority. Control is returned when the 164 * application having the control deletes its AudioEffect object. 165 * The EVENT_ENABLE_STATUS_CHANGED event is received by all applications not having the 166 * control of the effect engine when the effect is enabled or disabled. 167 * The EVENT_PARAMETER_CHANGED event is received by all applications not having the 168 * control of the effect engine when an effect parameter is changed. 169 * The EVENT_ERROR event is received when the media server process dies. 170 * 171 * Parameters: 172 * 173 * event: type of event notified (see enum AudioEffect::event_type). 174 * user: Pointer to context for use by the callback receiver. 175 * info: Pointer to optional parameter according to event type: 176 * - EVENT_CONTROL_STATUS_CHANGED: boolean indicating if control is granted (true) 177 * or stolen (false). 178 * - EVENT_ENABLE_STATUS_CHANGED: boolean indicating if effect is now enabled (true) 179 * or disabled (false). 180 * - EVENT_PARAMETER_CHANGED: pointer to a effect_param_t structure. 181 * - EVENT_ERROR: status_t indicating the error (DEAD_OBJECT when media server dies). 182 */ 183 184 typedef void (*effect_callback_t)(int32_t event, void* user, void *info); 185 186 187 /* Constructor. 188 * AudioEffect is the base class for creating and controlling an effect engine from 189 * the application process. Creating an AudioEffect object will create the effect engine 190 * in the AudioFlinger if no engine of the specified type exists. If one exists, this engine 191 * will be used. The application creating the AudioEffect object (or a derived class like 192 * Reverb for instance) will either receive control of the effect engine or not, depending 193 * on the priority parameter. If priority is higher than the priority used by the current 194 * effect engine owner, the control will be transfered to the new application. Otherwise 195 * control will remain to the previous application. In this case, the new application will be 196 * notified of changes in effect engine state or control ownership by the effect callback. 197 * After creating the AudioEffect, the application must call the initCheck() method and 198 * check the creation status before trying to control the effect engine (see initCheck()). 199 * If the effect is to be applied to an AudioTrack or MediaPlayer only the application 200 * must specify the audio session ID corresponding to this player. 201 */ 202 203 /* Simple Constructor. 204 * 205 * Parameters: 206 * 207 * opPackageName: The package name used for app op checks. 208 */ 209 AudioEffect(const String16& opPackageName); 210 211 212 /* Constructor. 213 * 214 * Parameters: 215 * 216 * type: type of effect created: can be null if uuid is specified. This corresponds to 217 * the OpenSL ES interface implemented by this effect. 218 * opPackageName: The package name used for app op checks. 219 * uuid: Uuid of effect created: can be null if type is specified. This uuid corresponds to 220 * a particular implementation of an effect type. 221 * priority: requested priority for effect control: the priority level corresponds to the 222 * value of priority parameter: negative values indicate lower priorities, positive values 223 * higher priorities, 0 being the normal priority. 224 * cbf: optional callback function (see effect_callback_t) 225 * user: pointer to context for use by the callback receiver. 226 * sessionID: audio session this effect is associated to. 227 * If equal to AUDIO_SESSION_OUTPUT_MIX, the effect will be global to 228 * the output mix. Otherwise, the effect will be applied to all players 229 * (AudioTrack or MediaPLayer) within the same audio session. 230 * io: HAL audio output or input stream to which this effect must be attached. Leave at 0 for 231 * automatic output selection by AudioFlinger. 232 */ 233 234 AudioEffect(const effect_uuid_t *type, 235 const String16& opPackageName, 236 const effect_uuid_t *uuid = NULL, 237 int32_t priority = 0, 238 effect_callback_t cbf = NULL, 239 void* user = NULL, 240 audio_session_t sessionId = AUDIO_SESSION_OUTPUT_MIX, 241 audio_io_handle_t io = AUDIO_IO_HANDLE_NONE 242 ); 243 244 /* Constructor. 245 * Same as above but with type and uuid specified by character strings 246 */ 247 AudioEffect(const char *typeStr, 248 const String16& opPackageName, 249 const char *uuidStr = NULL, 250 int32_t priority = 0, 251 effect_callback_t cbf = NULL, 252 void* user = NULL, 253 audio_session_t sessionId = AUDIO_SESSION_OUTPUT_MIX, 254 audio_io_handle_t io = AUDIO_IO_HANDLE_NONE 255 ); 256 257 /* Terminates the AudioEffect and unregisters it from AudioFlinger. 258 * The effect engine is also destroyed if this AudioEffect was the last controlling 259 * the engine. 260 */ 261 ~AudioEffect(); 262 263 /* Initialize an uninitialized AudioEffect. 264 * Returned status (from utils/Errors.h) can be: 265 * - NO_ERROR or ALREADY_EXISTS: successful initialization 266 * - INVALID_OPERATION: AudioEffect is already initialized 267 * - BAD_VALUE: invalid parameter 268 * - NO_INIT: audio flinger or audio hardware not initialized 269 * */ 270 status_t set(const effect_uuid_t *type, 271 const effect_uuid_t *uuid = NULL, 272 int32_t priority = 0, 273 effect_callback_t cbf = NULL, 274 void* user = NULL, 275 audio_session_t sessionId = AUDIO_SESSION_OUTPUT_MIX, 276 audio_io_handle_t io = AUDIO_IO_HANDLE_NONE 277 ); 278 279 /* Result of constructing the AudioEffect. This must be checked 280 * before using any AudioEffect API. 281 * initCheck() can return: 282 * - NO_ERROR: the effect engine is successfully created and the application has control. 283 * - ALREADY_EXISTS: the effect engine is successfully created but the application does not 284 * have control. 285 * - NO_INIT: the effect creation failed. 286 * 287 */ 288 status_t initCheck() const; 289 290 291 /* Returns the unique effect Id for the controlled effect engine. This ID is unique 292 * system wide and is used for instance in the case of auxiliary effects to attach 293 * the effect to an AudioTrack or MediaPlayer. 294 * 295 */ 296 int32_t id() const { return mId; } 297 298 /* Returns a descriptor for the effect (see effect_descriptor_t in audio_effect.h). 299 */ 300 effect_descriptor_t descriptor() const; 301 302 /* Returns effect control priority of this AudioEffect object. 303 */ 304 int32_t priority() const { return mPriority; } 305 306 307 /* Enables or disables the effect engine. 308 * 309 * Parameters: 310 * enabled: requested enable state. 311 * 312 * Returned status (from utils/Errors.h) can be: 313 * - NO_ERROR: successful operation 314 * - INVALID_OPERATION: the application does not have control of the effect engine or the 315 * effect is already in the requested state. 316 */ 317 virtual status_t setEnabled(bool enabled); 318 bool getEnabled() const; 319 320 /* Sets a parameter value. 321 * 322 * Parameters: 323 * param: pointer to effect_param_t structure containing the parameter 324 * and its value (See audio_effect.h). 325 * Returned status (from utils/Errors.h) can be: 326 * - NO_ERROR: successful operation. 327 * - INVALID_OPERATION: the application does not have control of the effect engine. 328 * - BAD_VALUE: invalid parameter identifier or value. 329 * - DEAD_OBJECT: the effect engine has been deleted. 330 */ 331 virtual status_t setParameter(effect_param_t *param); 332 333 /* Prepare a new parameter value that will be set by next call to 334 * setParameterCommit(). This method can be used to set multiple parameters 335 * in a synchronous manner or to avoid multiple binder calls for each 336 * parameter. 337 * 338 * Parameters: 339 * param: pointer to effect_param_t structure containing the parameter 340 * and its value (See audio_effect.h). 341 * 342 * Returned status (from utils/Errors.h) can be: 343 * - NO_ERROR: successful operation. 344 * - INVALID_OPERATION: the application does not have control of the effect engine. 345 * - NO_MEMORY: no more space available in shared memory used for deferred parameter 346 * setting. 347 */ 348 virtual status_t setParameterDeferred(effect_param_t *param); 349 350 /* Commit all parameter values previously prepared by setParameterDeferred(). 351 * 352 * Parameters: 353 * none 354 * 355 * Returned status (from utils/Errors.h) can be: 356 * - NO_ERROR: successful operation. 357 * - INVALID_OPERATION: No new parameter values ready for commit. 358 * - BAD_VALUE: invalid parameter identifier or value: there is no indication 359 * as to which of the parameters caused this error. 360 * - DEAD_OBJECT: the effect engine has been deleted. 361 */ 362 virtual status_t setParameterCommit(); 363 364 /* Gets a parameter value. 365 * 366 * Parameters: 367 * param: pointer to effect_param_t structure containing the parameter 368 * and the returned value (See audio_effect.h). 369 * 370 * Returned status (from utils/Errors.h) can be: 371 * - NO_ERROR: successful operation. 372 * - INVALID_OPERATION: the AudioEffect was not successfully initialized. 373 * - BAD_VALUE: invalid parameter identifier. 374 * - DEAD_OBJECT: the effect engine has been deleted. 375 */ 376 virtual status_t getParameter(effect_param_t *param); 377 378 /* Sends a command and receives a response to/from effect engine. 379 * See audio_effect.h for details on effect command() function, valid command codes 380 * and formats. 381 */ 382 virtual status_t command(uint32_t cmdCode, 383 uint32_t cmdSize, 384 void *cmdData, 385 uint32_t *replySize, 386 void *replyData); 387 388 389 /* 390 * Utility functions. 391 */ 392 393 /* Converts the string passed as first argument to the effect_uuid_t 394 * pointed to by second argument 395 */ 396 static status_t stringToGuid(const char *str, effect_uuid_t *guid); 397 /* Converts the effect_uuid_t pointed to by first argument to the 398 * string passed as second argument 399 */ 400 static status_t guidToString(const effect_uuid_t *guid, char *str, size_t maxLen); 401 402 // kMaxPreProcessing is a reasonable value for the maximum number of preprocessing effects 403 // that can be applied simultaneously. 404 static const uint32_t kMaxPreProcessing = 10; 405 406protected: 407 bool mEnabled; // enable state 408 audio_session_t mSessionId; // audio session ID 409 int32_t mPriority; // priority for effect control 410 status_t mStatus; // effect status 411 effect_callback_t mCbf; // callback function for status, control and 412 // parameter changes notifications 413 void* mUserData; // client context for callback function 414 effect_descriptor_t mDescriptor; // effect descriptor 415 int32_t mId; // system wide unique effect engine instance ID 416 Mutex mLock; // Mutex for mEnabled access 417 418 String16 mOpPackageName; // The package name used for app op checks. 419 420 // IEffectClient 421 virtual void controlStatusChanged(bool controlGranted); 422 virtual void enableStatusChanged(bool enabled); 423 virtual void commandExecuted(uint32_t cmdCode, 424 uint32_t cmdSize, 425 void *pCmdData, 426 uint32_t replySize, 427 void *pReplyData); 428 429private: 430 431 // Implements the IEffectClient interface 432 class EffectClient : 433 public android::BnEffectClient, public android::IBinder::DeathRecipient 434 { 435 public: 436 437 EffectClient(AudioEffect *effect) : mEffect(effect){} 438 439 // IEffectClient 440 virtual void controlStatusChanged(bool controlGranted) { 441 sp<AudioEffect> effect = mEffect.promote(); 442 if (effect != 0) { 443 effect->controlStatusChanged(controlGranted); 444 } 445 } 446 virtual void enableStatusChanged(bool enabled) { 447 sp<AudioEffect> effect = mEffect.promote(); 448 if (effect != 0) { 449 effect->enableStatusChanged(enabled); 450 } 451 } 452 virtual void commandExecuted(uint32_t cmdCode, 453 uint32_t cmdSize, 454 void *pCmdData, 455 uint32_t replySize, 456 void *pReplyData) { 457 sp<AudioEffect> effect = mEffect.promote(); 458 if (effect != 0) { 459 effect->commandExecuted( 460 cmdCode, cmdSize, pCmdData, replySize, pReplyData); 461 } 462 } 463 464 // IBinder::DeathRecipient 465 virtual void binderDied(const wp<IBinder>& /*who*/) { 466 sp<AudioEffect> effect = mEffect.promote(); 467 if (effect != 0) { 468 effect->binderDied(); 469 } 470 } 471 472 private: 473 wp<AudioEffect> mEffect; 474 }; 475 476 void binderDied(); 477 478 sp<IEffect> mIEffect; // IEffect binder interface 479 sp<EffectClient> mIEffectClient; // IEffectClient implementation 480 sp<IMemory> mCblkMemory; // shared memory for deferred parameter setting 481 effect_param_cblk_t* mCblk; // control block for deferred parameter setting 482 pid_t mClientPid; 483}; 484 485 486}; // namespace android 487 488#endif // ANDROID_AUDIOEFFECT_H 489