1 /* ----------------------------------------------------------------------------- 2 Software License for The Fraunhofer FDK AAC Codec Library for Android 3 4 © Copyright 1995 - 2018 Fraunhofer-Gesellschaft zur Förderung der angewandten 5 Forschung e.V. All rights reserved. 6 7 1. INTRODUCTION 8 The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software 9 that implements the MPEG Advanced Audio Coding ("AAC") encoding and decoding 10 scheme for digital audio. This FDK AAC Codec software is intended to be used on 11 a wide variety of Android devices. 12 13 AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient 14 general perceptual audio codecs. AAC-ELD is considered the best-performing 15 full-bandwidth communications codec by independent studies and is widely 16 deployed. AAC has been standardized by ISO and IEC as part of the MPEG 17 specifications. 18 19 Patent licenses for necessary patent claims for the FDK AAC Codec (including 20 those of Fraunhofer) may be obtained through Via Licensing 21 (www.vialicensing.com) or through the respective patent owners individually for 22 the purpose of encoding or decoding bit streams in products that are compliant 23 with the ISO/IEC MPEG audio standards. Please note that most manufacturers of 24 Android devices already license these patent claims through Via Licensing or 25 directly from the patent owners, and therefore FDK AAC Codec software may 26 already be covered under those patent licenses when it is used for those 27 licensed purposes only. 28 29 Commercially-licensed AAC software libraries, including floating-point versions 30 with enhanced sound quality, are also available from Fraunhofer. Users are 31 encouraged to check the Fraunhofer website for additional applications 32 information and documentation. 33 34 2. COPYRIGHT LICENSE 35 36 Redistribution and use in source and binary forms, with or without modification, 37 are permitted without payment of copyright license fees provided that you 38 satisfy the following conditions: 39 40 You must retain the complete text of this software license in redistributions of 41 the FDK AAC Codec or your modifications thereto in source code form. 42 43 You must retain the complete text of this software license in the documentation 44 and/or other materials provided with redistributions of the FDK AAC Codec or 45 your modifications thereto in binary form. You must make available free of 46 charge copies of the complete source code of the FDK AAC Codec and your 47 modifications thereto to recipients of copies in binary form. 48 49 The name of Fraunhofer may not be used to endorse or promote products derived 50 from this library without prior written permission. 51 52 You may not charge copyright license fees for anyone to use, copy or distribute 53 the FDK AAC Codec software or your modifications thereto. 54 55 Your modified versions of the FDK AAC Codec must carry prominent notices stating 56 that you changed the software and the date of any change. For modified versions 57 of the FDK AAC Codec, the term "Fraunhofer FDK AAC Codec Library for Android" 58 must be replaced by the term "Third-Party Modified Version of the Fraunhofer FDK 59 AAC Codec Library for Android." 60 61 3. NO PATENT LICENSE 62 63 NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without 64 limitation the patents of Fraunhofer, ARE GRANTED BY THIS SOFTWARE LICENSE. 65 Fraunhofer provides no warranty of patent non-infringement with respect to this 66 software. 67 68 You may use this FDK AAC Codec software or modifications thereto only for 69 purposes that are authorized by appropriate patent licenses. 70 71 4. DISCLAIMER 72 73 This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright 74 holders and contributors "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, 75 including but not limited to the implied warranties of merchantability and 76 fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 77 CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary, 78 or consequential damages, including but not limited to procurement of substitute 79 goods or services; loss of use, data, or profits, or business interruption, 80 however caused and on any theory of liability, whether in contract, strict 81 liability, or tort (including negligence), arising in any way out of the use of 82 this software, even if advised of the possibility of such damage. 83 84 5. CONTACT INFORMATION 85 86 Fraunhofer Institute for Integrated Circuits IIS 87 Attention: Audio and Multimedia Departments - FDK AAC LL 88 Am Wolfsmantel 33 89 91058 Erlangen, Germany 90 91 www.iis.fraunhofer.de/amm 92 amm-info@iis.fraunhofer.de 93 ----------------------------------------------------------------------------- */ 94 95 /******************* Library for basic calculation routines ******************** 96 97 Author(s): Matthias Hildenbrand 98 99 Description: Module to efficiently handle QMF data for multiple channels and 100 to share the data between e.g. SBR and MPS 101 102 *******************************************************************************/ 103 104 #ifndef FDK_QMF_DOMAIN_H 105 #define FDK_QMF_DOMAIN_H 106 107 #include "qmf.h" 108 109 typedef enum { 110 QMF_DOMAIN_OK = 0x0, /*!< No error occurred. */ 111 QMF_DOMAIN_OUT_OF_MEMORY = 112 0x1, /*!< QMF-Configuration demands for more memory than allocated on 113 heap. */ 114 QMF_DOMAIN_INIT_ERROR = 115 0x2, /*!< An error during filterbank-setup occurred. */ 116 QMF_DOMAIN_RESAMPLER_INIT_ERROR = 117 0x3 /*!< An error during QMF-resampler-setup occurred. */ 118 } QMF_DOMAIN_ERROR; 119 120 #define CMPLX_MOD (2) 121 122 #define QMF_MAX_WB_SECTIONS (5) /* maximum number of workbuffer sections */ 123 #define QMF_WB_SECTION_SIZE (1024 * 2) 124 125 H_ALLOC_MEM_OVERLAY(QmfWorkBufferCore1, FIXP_DBL) 126 H_ALLOC_MEM_OVERLAY(QmfWorkBufferCore2, FIXP_DBL) 127 H_ALLOC_MEM_OVERLAY(QmfWorkBufferCore3, FIXP_DBL) 128 H_ALLOC_MEM_OVERLAY(QmfWorkBufferCore4, FIXP_DBL) 129 H_ALLOC_MEM_OVERLAY(QmfWorkBufferCore5, FIXP_DBL) 130 H_ALLOC_MEM_OVERLAY(QmfWorkBufferCore6, FIXP_DBL) 131 132 #define QMF_DOMAIN_MAX_ANALYSIS_QMF_BANDS (64) 133 #define QMF_DOMAIN_MAX_SYNTHESIS_QMF_BANDS (QMF_MAX_SYNTHESIS_BANDS) 134 #define QMF_DOMAIN_MAX_QMF_PROC_BANDS (64) 135 #define QMF_DOMAIN_MAX_TIMESLOTS (64) 136 #define QMF_DOMAIN_MAX_OV_TIMESLOTS (12) 137 138 #define QMF_DOMAIN_ANALYSIS_QMF_BANDS_16 (16) 139 #define QMF_DOMAIN_ANALYSIS_QMF_BANDS_24 (24) 140 #define QMF_DOMAIN_ANALYSIS_QMF_BANDS_32 (32) 141 142 #define QMF_DOMAIN_TIMESLOTS_16 (16) 143 #define QMF_DOMAIN_TIMESLOTS_32 (32) 144 145 #define QMF_DOMAIN_OV_TIMESLOTS_16 (3) 146 #define QMF_DOMAIN_OV_TIMESLOTS_32 (6) 147 148 H_ALLOC_MEM(AnaQmfStates, FIXP_QAS) 149 H_ALLOC_MEM(SynQmfStates, FIXP_QSS) 150 H_ALLOC_MEM(QmfSlotsReal, FIXP_DBL *) 151 H_ALLOC_MEM(QmfSlotsImag, FIXP_DBL *) 152 H_ALLOC_MEM(QmfOverlapBuffer, FIXP_DBL) 153 154 H_ALLOC_MEM(AnaQmfStates16, FIXP_QAS) 155 H_ALLOC_MEM(AnaQmfStates24, FIXP_QAS) 156 H_ALLOC_MEM(AnaQmfStates32, FIXP_QAS) 157 H_ALLOC_MEM(QmfSlotsReal16, FIXP_DBL *) 158 H_ALLOC_MEM(QmfSlotsReal32, FIXP_DBL *) 159 H_ALLOC_MEM(QmfSlotsImag16, FIXP_DBL *) 160 H_ALLOC_MEM(QmfSlotsImag32, FIXP_DBL *) 161 H_ALLOC_MEM(QmfOverlapBuffer16, FIXP_DBL) 162 H_ALLOC_MEM(QmfOverlapBuffer32, FIXP_DBL) 163 164 #define QDOM_PCM INT_PCM 165 166 /** 167 * Structure to hold the configuration data which is global whithin a QMF domain 168 * instance. 169 */ 170 typedef struct { 171 UCHAR qmfDomainExplicitConfig; /*!< Flag to signal that QMF domain is set 172 explicitly instead of SBR and MPS init 173 routines. */ 174 UCHAR nInputChannels; /*!< Number of QMF input channels. */ 175 UCHAR nInputChannels_requested; /*!< Corresponding requested not yet active 176 configuration parameter. */ 177 UCHAR nOutputChannels; /*!< Number of QMF output channels. */ 178 UCHAR nOutputChannels_requested; /*!< Corresponding requested not yet active 179 configuration parameter. */ 180 UCHAR 181 parkChannel; /*!< signal to automatically allocate additional memory to 182 park a channel if only one processing channel is 183 available. */ 184 UCHAR parkChannel_requested; 185 QDOM_PCM 186 *TDinput; /*!< Pointer to time domain data used as input for the QMF 187 analysis. */ 188 FIXP_DBL * 189 pWorkBuffer[QMF_MAX_WB_SECTIONS]; /*!< Pointerarray to volatile memory. */ 190 UINT flags; /*!< Flags to be set on all QMF analysis/synthesis filter 191 instances. */ 192 UINT flags_requested; /*!< Corresponding requested not yet active 193 configuration parameter. */ 194 UCHAR nBandsAnalysis; /*!< Number of QMF analysis bands for all input 195 channels. */ 196 UCHAR nBandsAnalysis_requested; /*!< Corresponding requested not yet active 197 configuration parameter. */ 198 USHORT nBandsSynthesis; /*!< Number of QMF synthesis bands for all output 199 channels. */ 200 USHORT 201 nBandsSynthesis_requested; /*!< Corresponding requested not yet active 202 configuration parameter. */ 203 UCHAR nQmfTimeSlots; /*!< Number of QMF time slots (stored in work buffer 204 memory). */ 205 UCHAR nQmfTimeSlots_requested; /*!< Corresponding requested not yet active 206 configuration parameter. */ 207 UCHAR 208 nQmfOvTimeSlots; /*!< Number of QMF overlap/delay time slots (stored in 209 persistent memory). */ 210 UCHAR nQmfOvTimeSlots_requested; /*!< Corresponding requested not yet active 211 configuration parameter. */ 212 UCHAR nQmfProcBands; /*!< Number of QMF bands which are processed by the 213 decoder. Typically this is equal to nBandsSynthesis 214 but it may differ if the QMF based resampler is being 215 used. */ 216 UCHAR nQmfProcBands_requested; /*!< Corresponding requested not yet active 217 configuration parameter. */ 218 UCHAR 219 nQmfProcChannels; /*!< Number of complete QMF channels which need to 220 coexist in memory at the same time. For most cases 221 this is 1 which means the work buffer can be shared 222 between audio channels. */ 223 UCHAR 224 nQmfProcChannels_requested; /*!< Corresponding requested not yet active 225 configuration parameter. */ 226 } FDK_QMF_DOMAIN_GC; 227 typedef FDK_QMF_DOMAIN_GC *HANDLE_FDK_QMF_DOMAIN_GC; 228 229 /** 230 * Structure representing one QMF input channel. This includes the QMF analysis 231 * and the QMF domain data representation needed by the codec. Work buffer data 232 * may be shared between channels if the codec processes all QMF channels in a 233 * consecutive order. 234 */ 235 typedef struct { 236 HANDLE_FDK_QMF_DOMAIN_GC 237 pGlobalConf; /*!< Pointer to global configuration structure. */ 238 QMF_FILTER_BANK fb; /*!< QMF (analysis) filter bank structure. */ 239 QMF_SCALE_FACTOR scaling; /*!< Structure with scaling information. */ 240 UCHAR workBuf_nTimeSlots; /*!< Work buffer dimension for this channel is 241 (workBuf_nTimeSlots * workBuf_nBands * 242 CMPLX_MOD). */ 243 UCHAR workBuf_nBands; /*!< Work buffer dimension for this channel is 244 (workBuf_nTimeSlots * workBuf_nBands * CMPLX_MOD). */ 245 USHORT workBufferOffset; /*!< Offset within work buffer. */ 246 USHORT workBufferSectSize; /*!< Size of work buffer section. */ 247 FIXP_QAS * 248 pAnaQmfStates; /*!< Pointer to QMF analysis states (persistent memory). */ 249 FIXP_DBL 250 *pOverlapBuffer; /*!< Pointer to QMF overlap/delay memory (persistent 251 memory). */ 252 FIXP_DBL **pWorkBuffer; /*!< Pointer array to available work buffers. */ 253 FIXP_DBL * 254 *hQmfSlotsReal; /*!< Handle for QMF real data time slot pointer array. */ 255 FIXP_DBL **hQmfSlotsImag; /*!< Handle for QMF imaginary data time slot pointer 256 array. */ 257 } FDK_QMF_DOMAIN_IN; 258 typedef FDK_QMF_DOMAIN_IN *HANDLE_FDK_QMF_DOMAIN_IN; 259 260 /** 261 * Structure representing one QMF output channel. 262 */ 263 typedef struct { 264 QMF_FILTER_BANK fb; /*!< QMF (synthesis) filter bank structure. */ 265 FIXP_QSS *pSynQmfStates; /*!< Pointer to QMF synthesis states (persistent 266 memory). */ 267 } FDK_QMF_DOMAIN_OUT; 268 typedef FDK_QMF_DOMAIN_OUT *HANDLE_FDK_QMF_DOMAIN_OUT; 269 270 /** 271 * Structure representing the QMF domain for multiple channels. 272 */ 273 typedef struct { 274 FDK_QMF_DOMAIN_GC globalConf; /*!< Global configuration structure. */ 275 FDK_QMF_DOMAIN_IN 276 QmfDomainIn[((8) + (1))]; /*!< Array of QMF domain input structures */ 277 FDK_QMF_DOMAIN_OUT 278 QmfDomainOut[((8) + (1))]; /*!< Array of QMF domain output structures */ 279 } FDK_QMF_DOMAIN; 280 typedef FDK_QMF_DOMAIN *HANDLE_FDK_QMF_DOMAIN; 281 282 /** 283 * \brief Check whether analysis- and synthesis-filterbank-states have been 284 * initialized. 285 * 286 * \param qd Pointer to QMF domain structure. 287 * 288 * \return 1 if initialized, 0 else 289 */ 290 int FDK_QmfDomain_IsInitialized(const HANDLE_FDK_QMF_DOMAIN qd); 291 292 /** 293 * \brief Initialize QMF analysis and synthesis filter banks and set up QMF data 294 * representation. 295 * 296 * \param qd Pointer to QMF domain structure. 297 * \param extra_flags Initialize filter banks with extra flags which were not 298 * set in the global config flags field. 299 * 300 * \return 0 on success. 301 */ 302 int FDK_QmfDomain_InitFilterBank(HANDLE_FDK_QMF_DOMAIN qd, UINT extra_flags); 303 304 /** 305 * \brief When QMF processing of one channel is finished copy the overlap/delay 306 * part into the persistent memory to be used in the next frame. 307 * 308 * \param qd_ch Pointer to a QMF domain input channel. 309 * \param offset 310 * 311 * \return void 312 */ 313 void FDK_QmfDomain_SaveOverlap(HANDLE_FDK_QMF_DOMAIN_IN qd_ch, int offset); 314 315 /** 316 * \brief Get one slot of QMF data and adapt the scaling. 317 * 318 * \param qd_ch Pointer to a QMF domain input channel. 319 * \param ts Time slot number to be obtained. 320 * \param start_band Start index of QMF bands to be obtained. 321 * \param stop_band Stop index of QMF band to be obtained. 322 * \param pQmfOutReal Output buffer (real QMF data). 323 * \param pQmfOutImag Output buffer (imag QMF data). 324 * \param exp_out Target exponent (scaling) of data. 325 * 326 * \return void 327 */ 328 void FDK_QmfDomain_GetSlot(const HANDLE_FDK_QMF_DOMAIN_IN qd_ch, const int ts, 329 const int start_band, const int stop_band, 330 FIXP_DBL *pQmfOutReal, FIXP_DBL *pQmfOutImag, 331 const int exp_out); 332 333 /** 334 * \brief Direct access to the work buffer associated with a certain channel (no 335 * time slot pointer array is used). 336 * 337 * \param qd_ch Pointer to a QMF domain input channel. 338 * \param ts Time slot number to be obtained. 339 * \param ppQmfReal Returns the pointer to the requested part of the work buffer 340 * (real time slot). 341 * \param ppQmfImag Returns the pointer to the requested part of the work buffer 342 * (imag time slot). 343 * 344 * \return void 345 */ 346 void FDK_QmfDomain_GetWorkBuffer(const HANDLE_FDK_QMF_DOMAIN_IN qd_ch, 347 const int ts, FIXP_DBL **ppQmfReal, 348 FIXP_DBL **ppQmfImag); 349 350 /** 351 * \brief For the case that the work buffer associated to this channel is not 352 * identical to the processing channel work buffer copy the data into the 353 * processing channel. 354 * 355 * \param qd_ch Pointer to a QMF domain input channel. 356 * \return void 357 */ 358 void FDK_QmfDomain_WorkBuffer2ProcChannel(const HANDLE_FDK_QMF_DOMAIN_IN qd_ch); 359 360 /** 361 * \brief For the case of stereoCfgIndex3 with HBE the HBE buffer is copied into 362 * the processing channel work buffer and the processing channel work buffer is 363 * copied into the HBE buffer. 364 * 365 * \param qd_ch Pointer to a QMF domain input channel. 366 * \param ppQmfReal Pointer to a HBE QMF data buffer (real). 367 * \param ppQmfImag Pointer to a HBE QMF data buffer (imag). 368 * 369 * \return void 370 */ 371 void FDK_QmfDomain_QmfData2HBE(HANDLE_FDK_QMF_DOMAIN_IN qd_ch, 372 FIXP_DBL **ppQmfReal, FIXP_DBL **ppQmfImag); 373 374 /** 375 * \brief Set all fields for requested parametervalues in global config struct 376 * FDK_QMF_DOMAIN_GC to 0. 377 * 378 * \param hgc Pointer to a QMF domain global config struct. 379 */ 380 void FDK_QmfDomain_ClearRequested(HANDLE_FDK_QMF_DOMAIN_GC hgc); 381 382 /** 383 * \brief Check for parameter-change requests in global config and 384 * (re-)configure QMF domain accordingly. 385 * 386 * \param hqd Pointer to QMF domain 387 * 388 * \return errorcode 389 */ 390 QMF_DOMAIN_ERROR FDK_QmfDomain_Configure(HANDLE_FDK_QMF_DOMAIN hqd); 391 392 /** 393 * \brief Free QMF workbuffer, QMF persistent memory and configuration 394 * variables. 395 * 396 * \param hqd Pointer to QMF domain 397 */ 398 void FDK_QmfDomain_FreeMem(HANDLE_FDK_QMF_DOMAIN hqd); 399 400 /** 401 * \brief Clear QMF overlap buffers and QMF filter bank states. 402 * 403 * \param hqd Pointer to QMF domain 404 */ 405 QMF_DOMAIN_ERROR FDK_QmfDomain_ClearPersistentMemory(HANDLE_FDK_QMF_DOMAIN hqd); 406 407 /** 408 * \brief Free QMF workbuffer and QMF persistent memory. 409 * 410 * \param hqd Pointer to QMF domain 411 * 412 * \param dmx_lp_mode downmix low power mode flag 413 */ 414 void FDK_QmfDomain_Close(HANDLE_FDK_QMF_DOMAIN hqd); 415 416 #endif /* FDK_QMF_DOMAIN_H */ 417