Revise and straighten out useless references from decoder documentation.

Bug: 149481606
Test: doc update in header, so just make
Change-Id: I656e76762ee336931d4f1938e5c39c8ad7f65954

libAACdec/include/aacdecoder_lib.h

@@ -164,9 +164,6 @@ The contents of each file is described in detail in this document. All header
 files are provided for usage in specific C/C++ programs. The main AAC decoder
 library API functions are located in aacdecoder_lib.h header file.
 
-In binary releases the decoder core resides in statically linkable libraries,
-for example libAACdec.a.
-
 
 \section Calling_Sequence Calling Sequence
 
@@ -174,19 +171,7 @@ The following sequence is necessary for proper decoding of ISO/MPEG-2/4 AAC,
 HE-AAC v2, or MPEG-D USAC bitstreams. In the following description, input stream
 read and output write function details are left out, since they may be
 implemented in a variety of configurations depending on the user's specific
-requirements. The example implementation uses file-based input/output, and in
+requirements.
-such case one may call mpegFileRead_Open() to open an input file and to allocate
-memory for the required structures, and the corresponding mpegFileRead_Close()
-to close opened files and to de-allocate associated structures.
-mpegFileRead_Open() will attempt to detect the bitstream format and in case of
-MPEG-4 file format or Raw Packets file format (a proprietary Fraunhofer IIS file
-format suitable only for testing) it will read the Audio Specific Config data
-(ASC). An unsuccessful attempt to recognize the bitstream format requires the
-user to provide this information manually. For any other bitstream formats that
-are usually applicable in streaming applications, the decoder itself will try to
-synchronize and parse the given bitstream fragment using the FDK transport
-library. Hence, for streaming applications (without file access) this step is
-not necessary.
 
 
 -# Call aacDecoder_Open() to open and retrieve a handle to a new AAC decoder
@@ -205,19 +190,17 @@ do {
 working memory (a client-supplied input buffer "inBuffer" in framework). This
 buffer will be used to load AAC bitstream data to the decoder.  Only when all
 data in this buffer has been processed will the decoder signal an empty buffer.
-For file-based input, you may invoke mpegFileRead_Read() to acquire new
-bitstream data.
 -# Call aacDecoder_Fill() to fill the decoder's internal bitstream input buffer
 with the client-supplied bitstream input buffer. Note, if the data loaded in to
 the internal buffer is not sufficient to decode a frame,
 aacDecoder_DecodeFrame() will return ::AAC_DEC_NOT_ENOUGH_BITS until a
 sufficient amount of data is loaded in to the internal buffer. For streaming
 formats (ADTS, LOAS), it is acceptable to load more than one frame to the
-decoder. However, for RAW file format (Fraunhofer IIS proprietary format), only
+decoder. However, for packed based formats, only one frame may be loaded to the
-one frame may be loaded to the decoder per aacDecoder_DecodeFrame() call. For
+decoder per aacDecoder_DecodeFrame() call. For least amount of communication
-least amount of communication delay, fill and decode should be performed on a
+delay, fill and decode should be performed on a frame by frame basis. \code
-frame by frame basis. \code ErrorStatus = aacDecoder_Fill(aacDecoderInfo,
+    ErrorStatus = aacDecoder_Fill(aacDecoderInfo, inBuffer, bytesRead,
-inBuffer, bytesRead, bytesValid); \endcode
+bytesValid); \endcode
 -# Call aacDecoder_DecodeFrame(). This function decodes one frame and writes
 decoded PCM audio data to a client-supplied buffer. It is the client's
 responsibility to allocate a buffer which is large enough to hold the decoded
@@ -225,12 +208,9 @@ output data. \code ErrorStatus = aacDecoder_DecodeFrame(aacDecoderInfo,
 TimeData, OUT_BUF_SIZE, flags); \endcode If the bitstream configuration (number
 of channels, sample rate, frame size) is not known a priori, you may call
 aacDecoder_GetStreamInfo() to retrieve a structure that contains this
-information. You may use this data to initialize an audio output device. In the
+information. You may use this data to initialize an audio output device. \code
-example program, if the number of channels or the sample rate has changed since
+    p_si = aacDecoder_GetStreamInfo(aacDecoderInfo);
-program start or the previously decoded frame, the audio output device is then
+\endcode
-re-initialized. If WAVE file output is chosen, a new WAVE file for each new
-stream configuration is be created. \code p_si =
-aacDecoder_GetStreamInfo(aacDecoderInfo); \endcode
 -# Repeat steps 5 to 7 until no data is available to decode any more, or in case
 of error. \code } while (bytesRead[0] > 0 || doFlush || doBsFlush ||
 forceContinue); \endcode
@@ -239,7 +219,7 @@ structures. \code aacDecoder_Close(aacDecoderInfo); \endcode
 
 \image latex decode.png "Decode calling sequence" width=11cm
 
-\image latex change_source.png "Change data source sequence" width 5cm
+\image latex change_source.png "Change data source sequence" width=5cm
 
 \image latex conceal.png "Error concealment sequence" width=14cm
 
@@ -296,16 +276,14 @@ input buffer, and one to hold the decoded output PCM sample data. In resource
 limited applications, the output buffer may be reused as an external input
 buffer prior to the subsequence aacDecoder_Fill() function call.
 
-The external input buffer is set in the example program and its size is defined
+To feed the data to the decoder-internal input buffer, use the
-by ::IN_BUF_SIZE. You may freely choose different buffer sizes. To feed the data
+function aacDecoder_Fill(). This function returns important information
-to the decoder-internal input buffer, use the function aacDecoder_Fill(). This
+regarding the number of bytes in the external input buffer that have not yet
-function returns important information regarding the number of bytes in the
+been copied into the internal input buffer (variable bytesValid). Once the
-external input buffer that have not yet been copied into the internal input
+external buffer has been fully copied, it can be completely re-filled again. In
-buffer (variable bytesValid). Once the external buffer has been fully copied, it
+case you wish to refill the buffer while there are unprocessed bytes (bytesValid
-can be completely re-filled again. In case you wish to refill the buffer while
+is unequal 0), you should preserve the unconsumed data. However, we recommend to
-there are unprocessed bytes (bytesValid is unequal 0), you should preserve the
+refill the buffer only when bytesValid returns 0.
-unconsumed data. However, we recommend to refill the buffer only when bytesValid
-returns 0.
 
 The bytesValid parameter is an input and output parameter to the FDK decoder. As
 an input, it signals how many valid bytes are available in the external buffer.
@@ -340,10 +318,7 @@ explanation, please refer to ISO/IEC 13818-7:2005(E), chapter 8.5.3.2.
 In case a Program Config is included in the audio configuration, the channel
 mapping described within it will be adopted.
 
-In case of MPEG-D Surround the channel mapping will follow the same criteria
+The examples below explain these aspects in detail.
-described in ISO/IEC 13818-7:2005(E), but adding corresponding top channels (if
-available) to the channel types in order to avoid ambiguity. The examples below
-explain these aspects in detail.
 
 \section OutputFormatChange Changing the audio output format
 
@@ -689,9 +664,7 @@ typedef enum {
                      2. If the parameter value is greater than that of
                  ::AAC_PCM_MAX_OUTPUT_CHANNELS both will be set to the same
                  value. \n
-                     3. This parameter does not affect MPEG Surround processing.
+                     3. This parameter will be ignored if the number of encoded
-                 \n
-                     4. This parameter will be ignored if the number of encoded
                  audio channels is greater than 8. */
   AAC_PCM_MAX_OUTPUT_CHANNELS =
       0x0012, /*!< Maximum number of PCM output channels. If lower than the
@@ -718,11 +691,7 @@ typedef enum {
                      2. If the parameter value is greater than zero but smaller
                  than ::AAC_PCM_MIN_OUTPUT_CHANNELS both will be set to same
                  value. \n
-                     3. The operating mode of the MPEG Surround module will be
+                     3. This parameter will be ignored if the number of encoded
-                 set accordingly. \n
-                     4. Setting this parameter with any value will disable the
-                 binaural processing of the MPEG Surround module
-                     5. This parameter will be ignored if the number of encoded
                  audio channels is greater than 8. */
   AAC_METADATA_PROFILE =
       0x0020, /*!< See ::AAC_MD_PROFILE for all available values. */
@@ -803,11 +772,11 @@ typedef enum {
                  sequences for fading in and out, if provided in the
                  bitstream.\n Enabled album mode makes use of dedicated album
                  loudness information, if provided in the bitstream.\n */
-  AAC_QMF_LOWPOWER = 0x0300, /*!< Quadrature Mirror Filter (QMF) Bank processing
+  AAC_QMF_LOWPOWER =
-                                mode. \n -1: Use internal default. Implies MPEG
+      0x0300, /*!< Quadrature Mirror Filter (QMF) Bank processing mode. \n
-                                Surround partially complex accordingly. \n 0:
+                   -1: Use internal default. \n
-                                Use complex QMF data mode. \n 1: Use real (low
+                    0: Use complex QMF data mode. \n
-                                power) QMF data mode. \n */
+                    1: Use real (low power) QMF data mode. \n */
   AAC_TPDEC_CLEAR_BUFFER =
       0x0603 /*!< Clear internal bit stream buffer of transport layers. The
                 decoder will start decoding at new data passed after this event
@@ -1038,21 +1007,24 @@ LINKSPEC_H AAC_DECODER_ERROR aacDecoder_Fill(HANDLE_AACDECODER self,
                                              const UINT bufferSize[],
                                              UINT *bytesValid);
 
-#define AACDEC_CONCEAL                                                        \
+/** Flag for aacDecoder_DecodeFrame(): Trigger the built-in error concealment
-  1 /*!< Flag for aacDecoder_DecodeFrame(): Trigger the built-in error        \
+ * module to generate a substitute signal for one lost frame. New input data
-       concealment module to generate a substitute signal for one lost frame. \
+ * will not be considered.
-       New input data will not be considered. */
+ */
-#define AACDEC_FLUSH                                                         \
+#define AACDEC_CONCEAL 1
-  2 /*!< Flag for aacDecoder_DecodeFrame(): Flush all filterbanks to get all \
+/** Flag for aacDecoder_DecodeFrame(): Flush all filterbanks to get all delayed
-       delayed audio without having new input data. Thus new input data will \
+ * audio without having new input data. Thus new input data will not be
-       not be considered.*/
+ * considered.
-#define AACDEC_INTR                                                         \
+ */
-  4 /*!< Flag for aacDecoder_DecodeFrame(): Signal an input bit stream data \
+#define AACDEC_FLUSH 2
-       discontinuity. Resync any internals as necessary. */
+/** Flag for aacDecoder_DecodeFrame(): Signal an input bit stream data
-#define AACDEC_CLRHIST                                                        \
+ * discontinuity. Resync any internals as necessary.
-  8 /*!< Flag for aacDecoder_DecodeFrame(): Clear all signal delay lines and  \
+ */
-       history buffers. CAUTION: This can cause discontinuities in the output \
+#define AACDEC_INTR 4
-       signal. */
+/** Flag for aacDecoder_DecodeFrame(): Clear all signal delay lines and history
+ * buffers. CAUTION: This can cause discontinuities in the output signal.
+ */
+#define AACDEC_CLRHIST 8
 
 /**
  * \brief               Decode one audio frame