1 /* 2 * Copyright (C) 2004-2010 NXP Software 3 * Copyright (C) 2010 The Android Open Source Project 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /****************************************************************************************/ 19 /* */ 20 /* Header file for the application layer interface of Concert Sound, Bass Enhancement, */ 21 /* Equalizer, Power Spectrum Analyzer, Trebble Enhancement and volume management */ 22 /* bundle. */ 23 /* */ 24 /* This files includes all definitions, types, structures and function */ 25 /* prototypes required by the calling layer. All other types, structures and */ 26 /* functions are private. */ 27 /* */ 28 /****************************************************************************************/ 29 /* */ 30 /* Note: 1 */ 31 /* ======= */ 32 /* The algorithm can execute either with separate input and output buffers or with */ 33 /* a common buffer, i.e. the data is processed in-place. */ 34 /* */ 35 /****************************************************************************************/ 36 /* */ 37 /* Note: 2 */ 38 /* ======= */ 39 /* Three data formats are support Stereo,Mono-In-Stereo and Mono. The data is */ 40 /* interleaved as follows: */ 41 /* */ 42 /* Byte Offset Stereo Input Mono-In-Stereo Input Mono Input */ 43 /* =========== ============ ==================== ============== */ 44 /* 0 Left Sample #1 Mono Sample #1 Mono Sample #1 */ 45 /* 2 Right Sample #1 Mono Sample #1 Mono Sample #2 */ 46 /* 4 Left Sample #2 Mono Sample #2 Mono Sample #3 */ 47 /* 6 Right Sample #2 Mono Sample #2 Mono Sample #4 */ 48 /* . . . . */ 49 /* . . . . */ 50 /* */ 51 /****************************************************************************************/ 52 53 #ifndef __LVM_H__ 54 #define __LVM_H__ 55 56 /****************************************************************************************/ 57 /* */ 58 /* Includes */ 59 /* */ 60 /****************************************************************************************/ 61 62 #include "LVM_Types.h" 63 64 /****************************************************************************************/ 65 /* */ 66 /* Definitions */ 67 /* */ 68 /****************************************************************************************/ 69 70 /* Concert Sound effect level presets */ 71 #define LVM_CS_EFFECT_NONE 0 /* 0% effect, minimum value */ 72 #define LVM_CS_EFFECT_LOW 16384 /* 50% effect */ 73 #define LVM_CS_EFFECT_MED 24576 /* 75% effect */ 74 #define LVM_CS_EFFECT_HIGH 32767 /* 100% effect, maximum value */ 75 76 /* Treble enhancement */ 77 #define LVM_TE_LOW_MIPS 32767 78 79 /* Bass enhancement effect level presets */ 80 #define LVM_BE_0DB 0 /* 0dB boost, no effect */ 81 #define LVM_BE_3DB 3 /* +3dB boost */ 82 #define LVM_BE_6DB 6 /* +6dB boost */ 83 #define LVM_BE_9DB 9 /* +9dB boost */ 84 #define LVM_BE_12DB 12 /* +12dB boost */ 85 #define LVM_BE_15DB 15 /* +15dB boost */ 86 87 /* N-Band Equalizer */ 88 #define LVM_EQ_NBANDS 5 /* Number of bands for equalizer */ 89 90 /* Headroom management */ 91 #define LVM_HEADROOM_MAX_NBANDS 5 92 93 /****************************************************************************************/ 94 /* */ 95 /* Types */ 96 /* */ 97 /****************************************************************************************/ 98 99 /* Instance handle */ 100 typedef void* LVM_Handle_t; 101 102 /* Status return values */ 103 typedef enum { 104 LVM_SUCCESS = 0, /* Successful return from a routine */ 105 LVM_ALIGNMENTERROR = 1, /* Memory alignment error */ 106 LVM_NULLADDRESS = 2, /* NULL allocation address */ 107 LVM_OUTOFRANGE = 3, /* Out of range control parameter */ 108 LVM_INVALIDNUMSAMPLES = 4, /* Invalid number of samples */ 109 LVM_WRONGAUDIOTIME = 5, /* Wrong time value for audio time*/ 110 LVM_ALGORITHMDISABLED = 6, /* Algorithm is disabled*/ 111 LVM_ALGORITHMPSA = 7, /* Algorithm PSA returns an error */ 112 LVM_RETURNSTATUS_DUMMY = LVM_MAXENUM 113 } LVM_ReturnStatus_en; 114 115 /* Buffer Management mode */ 116 typedef enum { 117 LVM_MANAGED_BUFFERS = 0, 118 LVM_UNMANAGED_BUFFERS = 1, 119 LVM_BUFFERS_DUMMY = LVM_MAXENUM 120 } LVM_BufferMode_en; 121 122 /* Output device type */ 123 typedef enum { 124 LVM_HEADPHONES = 0, 125 LVM_EX_HEADPHONES = 1, 126 LVM_SPEAKERTYPE_MAX = LVM_MAXENUM 127 } LVM_OutputDeviceType_en; 128 129 /* Virtualizer mode selection*/ 130 typedef enum { 131 LVM_CONCERTSOUND = 0, 132 LVM_VIRTUALIZERTYPE_DUMMY = LVM_MAXENUM 133 } LVM_VirtualizerType_en; 134 135 /* N-Band Equaliser operating mode */ 136 typedef enum { LVM_EQNB_OFF = 0, LVM_EQNB_ON = 1, LVM_EQNB_DUMMY = LVM_MAXENUM } LVM_EQNB_Mode_en; 137 138 /* Bass Enhancement operating mode */ 139 typedef enum { LVM_BE_OFF = 0, LVM_BE_ON = 1, LVM_BE_DUMMY = LVM_MAXENUM } LVM_BE_Mode_en; 140 141 /* Bass Enhancement centre frequency selection control */ 142 typedef enum { 143 LVM_BE_CENTRE_55Hz = 0, 144 LVM_BE_CENTRE_66Hz = 1, 145 LVM_BE_CENTRE_78Hz = 2, 146 LVM_BE_CENTRE_90Hz = 3, 147 LVM_BE_CENTRE_DUMMY = LVM_MAXENUM 148 } LVM_BE_CentreFreq_en; 149 150 /* Bass Enhancement HPF selection control */ 151 typedef enum { 152 LVM_BE_HPF_OFF = 0, 153 LVM_BE_HPF_ON = 1, 154 LVM_BE_HPF_DUMMY = LVM_MAXENUM 155 } LVM_BE_FilterSelect_en; 156 157 /* Volume Control operating mode */ 158 typedef enum { LVM_VC_OFF = 0, LVM_VC_ON = 1, LVM_VC_DUMMY = LVM_MAXENUM } LVM_VC_Mode_en; 159 160 /* Treble Enhancement operating mode */ 161 typedef enum { LVM_TE_OFF = 0, LVM_TE_ON = 1, LVM_TE_DUMMY = LVM_MAXENUM } LVM_TE_Mode_en; 162 163 /* Headroom management operating mode */ 164 typedef enum { 165 LVM_HEADROOM_OFF = 0, 166 LVM_HEADROOM_ON = 1, 167 LVM_Headroom_DUMMY = LVM_MAXENUM 168 } LVM_Headroom_Mode_en; 169 170 typedef enum { 171 LVM_PSA_SPEED_SLOW, /* Peak decaying at slow speed */ 172 LVM_PSA_SPEED_MEDIUM, /* Peak decaying at medium speed */ 173 LVM_PSA_SPEED_FAST, /* Peak decaying at fast speed */ 174 LVM_PSA_SPEED_DUMMY = LVM_MAXENUM 175 } LVM_PSA_DecaySpeed_en; 176 177 typedef enum { LVM_PSA_OFF = 0, LVM_PSA_ON = 1, LVM_PSA_DUMMY = LVM_MAXENUM } LVM_PSA_Mode_en; 178 179 /* Version information */ 180 typedef struct { 181 LVM_CHAR* pVersionNumber; /* Pointer to the version number in the format X.YY.ZZ */ 182 LVM_CHAR* pPlatform; /* Pointer to the library platform type */ 183 } LVM_VersionInfo_st; 184 185 /****************************************************************************************/ 186 /* */ 187 /* Structures */ 188 /* */ 189 /****************************************************************************************/ 190 191 /* N-Band equaliser band definition */ 192 typedef struct { 193 LVM_INT16 Gain; /* Band gain in dB */ 194 LVM_UINT16 Frequency; /* Band centre frequency in Hz */ 195 LVM_UINT16 QFactor; /* Band quality factor (x100) */ 196 } LVM_EQNB_BandDef_t; 197 198 /* Headroom band definition */ 199 typedef struct { 200 LVM_UINT16 Limit_Low; /* Low frequency limit of the band in Hertz */ 201 LVM_UINT16 Limit_High; /* High frequency limit of the band in Hertz */ 202 LVM_INT16 Headroom_Offset; /* Headroom = biggest band gain - Headroom_Offset */ 203 } LVM_HeadroomBandDef_t; 204 205 /* Control Parameter structure */ 206 typedef struct { 207 /* General parameters */ 208 LVM_Mode_en OperatingMode; /* Bundle operating mode On/Bypass */ 209 LVM_Fs_en SampleRate; /* Sample rate */ 210 LVM_Format_en SourceFormat; /* Input data format */ 211 LVM_OutputDeviceType_en SpeakerType; /* Output device type */ 212 213 /* Concert Sound Virtualizer parameters*/ 214 LVM_Mode_en VirtualizerOperatingMode; /* Virtualizer operating mode On/Off */ 215 LVM_VirtualizerType_en VirtualizerType; /* Virtualizer type: ConcertSound */ 216 LVM_UINT16 VirtualizerReverbLevel; /* Virtualizer reverb level in % */ 217 LVM_INT16 CS_EffectLevel; /* Concert Sound effect level */ 218 219 /* N-Band Equaliser parameters */ 220 LVM_EQNB_Mode_en EQNB_OperatingMode; /* N-Band Equaliser operating mode */ 221 LVM_UINT16 EQNB_NBands; /* Number of bands */ 222 LVM_EQNB_BandDef_t* pEQNB_BandDefinition; /* Pointer to equaliser definitions */ 223 224 /* Bass Enhancement parameters */ 225 LVM_BE_Mode_en BE_OperatingMode; /* Bass Enhancement operating mode */ 226 LVM_INT16 BE_EffectLevel; /* Bass Enhancement effect level */ 227 LVM_BE_CentreFreq_en BE_CentreFreq; /* Bass Enhancement centre frequency */ 228 LVM_BE_FilterSelect_en BE_HPF; /* Bass Enhancement high pass filter selector */ 229 230 /* Volume Control parameters */ 231 LVM_INT16 VC_EffectLevel; /* Volume Control setting in dBs */ 232 LVM_INT16 VC_Balance; /* Left Right Balance control in dB (-96 to 96 dB), -ve values reduce 233 Right channel while +ve value reduces Left channel*/ 234 235 /* Treble Enhancement parameters */ 236 LVM_TE_Mode_en TE_OperatingMode; /* Treble Enhancement On/Off */ 237 LVM_INT16 TE_EffectLevel; /* Treble Enhancement gain dBs */ 238 239 /* Spectrum Analyzer parameters Control */ 240 LVM_PSA_Mode_en PSA_Enable; 241 LVM_PSA_DecaySpeed_en PSA_PeakDecayRate; /* Peak value decay rate*/ 242 LVM_INT32 NrChannels; 243 LVM_INT32 ChMask; 244 245 } LVM_ControlParams_t; 246 247 /* Instance Parameter structure */ 248 typedef struct { 249 /* General */ 250 LVM_BufferMode_en BufferMode; /* Buffer management mode */ 251 LVM_UINT16 MaxBlockSize; /* Maximum processing block size */ 252 253 /* N-Band Equaliser */ 254 LVM_UINT16 EQNB_NumBands; /* Maximum number of equaliser bands */ 255 256 /* PSA */ 257 LVM_PSA_Mode_en PSA_Included; /* Controls the instance memory allocation for PSA: ON/OFF */ 258 } LVM_InstParams_t; 259 260 /* Headroom management parameter structure */ 261 typedef struct { 262 LVM_Headroom_Mode_en Headroom_OperatingMode; /* Headroom Control On/Off */ 263 LVM_HeadroomBandDef_t* pHeadroomDefinition; /* Pointer to headroom bands definition */ 264 LVM_UINT16 NHeadroomBands; /* Number of headroom bands */ 265 266 } LVM_HeadroomParams_t; 267 268 /****************************************************************************************/ 269 /* */ 270 /* Function Prototypes */ 271 /* */ 272 /****************************************************************************************/ 273 274 /****************************************************************************************/ 275 /* */ 276 /* FUNCTION: LVM_GetVersionInfo */ 277 /* */ 278 /* DESCRIPTION: */ 279 /* This function is used to retrieve information about the library's version. */ 280 /* */ 281 /* PARAMETERS: */ 282 /* pVersion Pointer to an empty version info structure */ 283 /* */ 284 /* RETURNS: */ 285 /* LVM_SUCCESS Succeeded */ 286 /* LVM_NULLADDRESS when pVersion is NULL */ 287 /* */ 288 /* NOTES: */ 289 /* 1. This function may be interrupted by the LVM_Process function */ 290 /* */ 291 /****************************************************************************************/ 292 LVM_ReturnStatus_en LVM_GetVersionInfo(LVM_VersionInfo_st* pVersion); 293 294 /****************************************************************************************/ 295 /* */ 296 /* FUNCTION: LVM_GetInstanceHandle */ 297 /* */ 298 /* DESCRIPTION: */ 299 /* This function is used to create a bundle instance. */ 300 /* All parameters are set to their default, inactive state. */ 301 /* */ 302 /* PARAMETERS: */ 303 /* phInstance Pointer to the instance handle */ 304 /* pInstParams Pointer to the instance parameters */ 305 /* */ 306 /* RETURNS: */ 307 /* LVM_SUCCESS Initialisation succeeded */ 308 /* LVM_NULLADDRESS One or more memory has a NULL pointer */ 309 /* LVM_OUTOFRANGE When any of the Instance parameters are out of range */ 310 /* */ 311 /* NOTES: */ 312 /* 1. This function must not be interrupted by the LVM_Process function */ 313 /* */ 314 /****************************************************************************************/ 315 LVM_ReturnStatus_en LVM_GetInstanceHandle(LVM_Handle_t* phInstance, LVM_InstParams_t* pInstParams); 316 317 /****************************************************************************************/ 318 /* */ 319 /* FUNCTION: LVM_DelInstanceHandle */ 320 /* */ 321 /* DESCRIPTION: */ 322 /* This function is used to create a bundle instance. It returns the created instance */ 323 /* handle through phInstance. All parameters are set to their default, inactive state. */ 324 /* */ 325 /* PARAMETERS: */ 326 /* phInstance Pointer to the instance handle */ 327 /* */ 328 /* NOTES: */ 329 /* 1. This function must not be interrupted by the LVM_Process function */ 330 /* */ 331 /****************************************************************************************/ 332 void LVM_DelInstanceHandle(LVM_Handle_t* phInstance); 333 334 /****************************************************************************************/ 335 /* */ 336 /* FUNCTION: LVM_ClearAudioBuffers */ 337 /* */ 338 /* DESCRIPTION: */ 339 /* This function is used to clear the internal audio buffers of the bundle. */ 340 /* */ 341 /* PARAMETERS: */ 342 /* hInstance Instance handle */ 343 /* */ 344 /* RETURNS: */ 345 /* LVM_SUCCESS Initialisation succeeded */ 346 /* LVM_NULLADDRESS Instance memory has a NULL pointer */ 347 /* */ 348 /* NOTES: */ 349 /* 1. This function must not be interrupted by the LVM_Process function */ 350 /* */ 351 /****************************************************************************************/ 352 LVM_ReturnStatus_en LVM_ClearAudioBuffers(LVM_Handle_t hInstance); 353 354 /****************************************************************************************/ 355 /* */ 356 /* FUNCTION: LVM_GetControlParameters */ 357 /* */ 358 /* DESCRIPTION: */ 359 /* Request the LifeVibes module parameters. The current parameter set is returned */ 360 /* via the parameter pointer. */ 361 /* */ 362 /* PARAMETERS: */ 363 /* hInstance Instance handle */ 364 /* pParams Pointer to an empty parameter structure */ 365 /* */ 366 /* RETURNS: */ 367 /* LVM_SUCCESS Succeeded */ 368 /* LVM_NULLADDRESS when any of hInstance or pParams is NULL */ 369 /* */ 370 /* NOTES: */ 371 /* 1. This function may be interrupted by the LVM_Process function */ 372 /* */ 373 /****************************************************************************************/ 374 LVM_ReturnStatus_en LVM_GetControlParameters(LVM_Handle_t hInstance, LVM_ControlParams_t* pParams); 375 376 /****************************************************************************************/ 377 /* */ 378 /* FUNCTION: LVM_SetControlParameters */ 379 /* */ 380 /* DESCRIPTION: */ 381 /* Sets or changes the LifeVibes module parameters. */ 382 /* */ 383 /* PARAMETERS: */ 384 /* hInstance Instance handle */ 385 /* pParams Pointer to a parameter structure */ 386 /* */ 387 /* RETURNS: */ 388 /* LVM_SUCCESS Succeeded */ 389 /* LVM_NULLADDRESS When hInstance, pParams or any control pointers are NULL */ 390 /* LVM_OUTOFRANGE When any of the control parameters are out of range */ 391 /* */ 392 /* NOTES: */ 393 /* 1. This function may be interrupted by the LVM_Process function */ 394 /* */ 395 /****************************************************************************************/ 396 LVM_ReturnStatus_en LVM_SetControlParameters(LVM_Handle_t hInstance, LVM_ControlParams_t* pParams); 397 398 /****************************************************************************************/ 399 /* */ 400 /* FUNCTION: LVM_Process */ 401 /* */ 402 /* DESCRIPTION: */ 403 /* Process function for the LifeVibes module. */ 404 /* */ 405 /* PARAMETERS: */ 406 /* hInstance Instance handle */ 407 /* pInData Pointer to the input data */ 408 /* pOutData Pointer to the output data */ 409 /* NumSamples Number of samples in the input buffer */ 410 /* AudioTime Audio Time of the current input data in milli-seconds */ 411 /* */ 412 /* RETURNS: */ 413 /* LVM_SUCCESS Succeeded */ 414 /* LVM_INVALIDNUMSAMPLES When the NumSamples is not a valied multiple in unmanaged */ 415 /* buffer mode */ 416 /* LVM_ALIGNMENTERROR When either the input our output buffers are not 32-bit */ 417 /* aligned in unmanaged mode */ 418 /* LVM_NULLADDRESS When one of hInstance, pInData or pOutData is NULL */ 419 /* */ 420 /* NOTES: */ 421 /* 1. The input and output buffers must be 32-bit aligned */ 422 /* 2. Number of samples is defined as follows: */ 423 /* MONO the number of samples in the block */ 424 /* MONOINSTEREO the number of sample pairs in the block */ 425 /* STEREO the number of sample pairs in the block */ 426 /* */ 427 /****************************************************************************************/ 428 LVM_ReturnStatus_en LVM_Process(LVM_Handle_t hInstance, const LVM_FLOAT* pInData, 429 LVM_FLOAT* pOutData, LVM_UINT16 NumSamples, LVM_UINT32 AudioTime); 430 431 /****************************************************************************************/ 432 /* */ 433 /* FUNCTION: LVM_SetHeadroomParams */ 434 /* */ 435 /* DESCRIPTION: */ 436 /* This function is used to set the automatic headroom management parameters. */ 437 /* */ 438 /* PARAMETERS: */ 439 /* hInstance Instance Handle */ 440 /* pHeadroomParams Pointer to headroom parameter structure */ 441 /* */ 442 /* RETURNS: */ 443 /* LVM_NULLADDRESS When hInstance or pHeadroomParams is NULL */ 444 /* LVM_SUCCESS Succeeded */ 445 /* */ 446 /* NOTES: */ 447 /* 1. This function may be interrupted by the LVM_Process function */ 448 /* */ 449 /****************************************************************************************/ 450 LVM_ReturnStatus_en LVM_SetHeadroomParams(LVM_Handle_t hInstance, 451 LVM_HeadroomParams_t* pHeadroomParams); 452 453 /****************************************************************************************/ 454 /* */ 455 /* FUNCTION: LVM_GetHeadroomParams */ 456 /* */ 457 /* DESCRIPTION: */ 458 /* This function is used to get the automatic headroom management parameters. */ 459 /* */ 460 /* PARAMETERS: */ 461 /* hInstance Instance Handle */ 462 /* pHeadroomParams Pointer to headroom parameter structure (output) */ 463 /* */ 464 /* RETURNS: */ 465 /* LVM_SUCCESS Succeeded */ 466 /* LVM_NULLADDRESS When hInstance or pHeadroomParams are NULL */ 467 /* */ 468 /* NOTES: */ 469 /* 1. This function may be interrupted by the LVM_Process function */ 470 /* */ 471 /****************************************************************************************/ 472 LVM_ReturnStatus_en LVM_GetHeadroomParams(LVM_Handle_t hInstance, 473 LVM_HeadroomParams_t* pHeadroomParams); 474 475 /****************************************************************************************/ 476 /* */ 477 /* FUNCTION: LVM_GetSpectrum */ 478 /* */ 479 /* DESCRIPTION: */ 480 /* This function is used to retrieve Spectral information at a given Audio time */ 481 /* for display usage */ 482 /* */ 483 /* PARAMETERS: */ 484 /* hInstance Instance Handle */ 485 /* pCurrentPeaks Pointer to location where currents peaks are to be saved */ 486 /* pPastPeaks Pointer to location where past peaks are to be saved */ 487 /* pCentreFreqs Pointer to location where centre frequency of each band is */ 488 /* to be saved */ 489 /* AudioTime Audio time at which the spectral information is needed */ 490 /* */ 491 /* RETURNS: */ 492 /* LVM_SUCCESS Succeeded */ 493 /* LVM_NULLADDRESS If any of input addresses are NULL */ 494 /* LVM_WRONGAUDIOTIME Failure due to audio time error */ 495 /* */ 496 /* NOTES: */ 497 /* 1. This function may be interrupted by the LVM_Process function */ 498 /* */ 499 /****************************************************************************************/ 500 LVM_ReturnStatus_en LVM_GetSpectrum(LVM_Handle_t hInstance, LVM_UINT8* pCurrentPeaks, 501 LVM_UINT8* pPastPeaks, LVM_INT32 AudioTime); 502 503 /****************************************************************************************/ 504 /* */ 505 /* FUNCTION: LVM_SetVolumeNoSmoothing */ 506 /* */ 507 /* DESCRIPTION: */ 508 /* This function is used to set output volume without any smoothing */ 509 /* */ 510 /* PARAMETERS: */ 511 /* hInstance Instance Handle */ 512 /* pParams Control Parameters, only volume value is used here */ 513 /* */ 514 /* RETURNS: */ 515 /* LVM_SUCCESS Succeeded */ 516 /* LVM_NULLADDRESS If any of input addresses are NULL */ 517 /* LVM_OUTOFRANGE When any of the control parameters are out of range */ 518 /* */ 519 /* NOTES: */ 520 /* 1. This function may be interrupted by the LVM_Process function */ 521 /* */ 522 /****************************************************************************************/ 523 LVM_ReturnStatus_en LVM_SetVolumeNoSmoothing(LVM_Handle_t hInstance, LVM_ControlParams_t* pParams); 524 525 #endif /* __LVM_H__ */ 526