audiodec.h

本程序为ST公司开发的源代码

         to by channels[k], and the channelOffsets array is not used.
         
       * If interleaved output is enabled
         The first sample for channel k is written at the address pointed
         to by channels[k], and the distance between adjacent samples is
         given by channelOffsets[k]. Therefore, the samples for channel k
         are written to:
         
         ((tPCM *)channels[k])[                     0 ],  
         ((tPCM *)channels[k])[ channelOffsets[k] * 1 ],
         ((tPCM *)channels[k])[ channelOffsets[k] * 2 ],
           ...
         ((tPCM *)channels[k])[ channelOffsets[k] * (maxNumberOfSamples-1) ],
                    
        where tPCM is the type of the PCM samples. 
       */
    void          **channels ;
    int            *channelOffsets;
    
} sDecoderOutput ;

/*
 * Description:
 * Decode the next frame in the bitstream.
 *
 * Implementation:
 * This function will output up to one frame of samples, or
 * 'maxNumberOfSamples', whichever is the smaller.
 *
 * The function should be called repeatedly while kDecoderStatus_MoreData
 * or kDecoderStatus_MoreSamples is returned.  For example:
 *
 * do
 * {
 *     do
 *     {
 *         add data to the fields of the bitstream, as necessary
 *         result = DecodeFrame( handle, scratch, output, bitstream ) ;
 *     } while( kDecoderStatus_MoreData == result ) ;
 *     play(?) the samples that have been decoded
 * } while( kDecoderStatus_MoreSamples == result ) ;
 *
 * if( 0 > result )
 * {
 *     a fatal error has occurred
 * }
 *
 * Note:
 * After the first call to this function for each new frame of data to be
 * decoded, the scratch parameter must be maintained between each function
 * call while the function returns either kDecoderStatus_MoreData or
 * kDecoderStatus_MoreSamples.  This is because the scratch parameter is 
 * used during the frame decode operation to hold data necessary to enable 
 * a frame to be decoded over several function calls.
 *
 * If the function decodes and outputs an entire frame with the first call
 * for each frame to be decoded, the scratch parameter does not need
 * maintained.
 *
 * Inputs:
 * handle - decoder handle for this instance of the decoder
 * scratch - pointer to the memory that can be used for scratch work space
 * output - pointer to the output structure
 * bitstream - pointer to the bitstream structure
 *
 * Outputs:
 * scratch - pointer to the memory used for scratch work space.  This must 
 *           be maintained as-is from the return of each call to this 
 *           function while the function's return value is either 
 *           kDecoderStatus_MoreData or kDecoderStatus_MoreSamples.
 * output - pointer to the output structure with the number of samples
 *          per channel set and the sample data in the channel memory
 * bitstream - pointer to the bitstream structure updated
 *
 * Return Value:
 * kDecoderStatus_Fatal_Error - an unknown fatal error has occurred
 * kDecoderStatus_Fatal_UnsupportedFeature - the frame contains features
 *                                           that are not supported by
 *                                           the decoder
 * kDecoderStatus_Fatal_TooManyChannels - more channels in bitstream
 *                                        than decoder can support
 * kDecoderStatus_NoError - frame has been decoded
 * kDecoderStatus_MoreData - more input data is required to decode the
 *                           frame
 * kDecoderStatus_MoreSamples - more output data exists for the frame
 * kDecoderStatus_BrokenFrame - the frame is inconsistent
 * kDecoderStatus_CRCError - CRC error
 * kDecoderStatus_FrameDiscarded - the frame is incomplete
 * kDecoderStatus_InvalidChannelConfiguration - specified channels cannot
 *                                              be output
 * kDecoderStatus_TooFewOutputChannels - 'channels' does not reference
 *                                       enough memory blocks
 * kDecoderStatus_InvalidArgument - the decoder instance is undefined,
 *                                  the scratch memory is undefined,
 *                                  the output structure is undefined
 *                                  or the bitstream structure is undefined
 */
typedef eDecoderStatus fnDecodeFrame(
    oDecoderHandle     handle,
    void               *scratch,
    sDecoderOutput     *output,
    sDecoderBitstream  *bitstream
) ;


/*
 * Description:
 * Seek to a given byte offset in the bitstream.
 *
 * Implementation:
 * This function will relocate the decoder to a byte offset forward or 
 * backward in the bitstream.
 *
 * The function must only be called after fnDecodeHeader, and must be called 
 * repeatedly while kDecoderStatus_MoreData is returned.  For example:
 *
 * do
 * {
 *     result = BitstreamSeekBytes( bytesToSkip, handle, scratch, bitstream ) ;
 *     add data to the fields of the bitstream, as necessary
 * } while( kDecoderStatus_MoreData == result ) ;
 *
 * if( 0 > result )
 * {
 *     a fatal error has occurred
 * }
 *
 * Note that after the first call to this function for each new frame of 
 * data to be decoded, the scratch parameter must be maintained between each 
 * function call while the function returns kDecoderStatus_MoreData.
 *
 * Note that if a negative seek is requested, the bitstream dataOffset value 
 * will be negative. If the function returns kDecoderStatus_MoreData then
 * any subsequent dataOffset values will be positive.
 *
 * Inputs:
 * bytesToSkip - byte offset to skip forward or backward, relative to the 
 *               bitstream position corresponding to the 
 *               sDecoderBitstream->data pointer. 
 * handle      - decoder handle for this instance of the decoder
 * scratch     - pointer to the memory that can be used for scratch work 
 *               space
 * bitstream   - pointer to the bitstream structure
 *
 * Outputs:
 * scratch     - pointer to the memory used for scratch work space.  This 
 *               must be maintained as-is from the return of each call to 
 *               this function while the function's return value is 
 *               kDecoderStatus_MoreData.
 * bitstream   - pointer to the bitstream structure updated
 *
 * Return Value:
 * kDecoderStatus_NoError            - seek was successful
 * kDecoderStatus_MoreData           - more input data is required to 
 *                                     accomplish the seek
 * kDecoderStatus_UnsupportedFeature - the decoder cannot accomplish the 
 *                                     requested operation
 * kDecoderStatus_InvalidArgument    - the decoder instance is undefined,
 *                                     the scratch memory is undefined,
 *                                     or the bitstream structure is 
 *                                     undefined
 */
typedef eDecoderStatus fnBitstreamSeekBytes(
    int                bytesToSkip,
    oDecoderHandle     handle,
    void               *scratch,
    sDecoderBitstream  *bitstream
) ;


/*
 * Description:
 * Seek to a given time offset in the bitstream.
 *
 * Implementation:
 * This function will relocate the decoder to a time offset forward or 
 * backward in the bitstream.
 *
 * The function must only be called after fnDecodeHeader, and must be called 
 * repeatedly while kDecoderStatus_MoreData is returned.  For example:
 *
 * do
 * {
 *     result = BitstreamSeekTime( timeToSkip, handle, scratch, bitstream ) ;
 *     add data to the fields of the bitstream, as necessary
 * } while( kDecoderStatus_MoreData == result ) ;
 *
 * if( 0 > result )
 * {
 *     a fatal error has occurred
 * }
 *
 * Note that after the first call to this function for each new frame of 
 * data to be decoded, the scratch parameter must be maintained between each 
 * function call while the function returns kDecoderStatus_MoreData.
 *
 * Note that if a negative seek is requested, the bitstream dataOffset value 
 * will be negative. If the function returns kDecoderStatus_MoreData then
 * any subsequent dataOffset values will be positive.
 *
 * Inputs:
 * timeToSkip  - time offset in milliseconds to skip forward or backward, 
 *               relative to the bitstream position corresponding to the 
 *               sDecoderBitstream->data pointer. 
 * handle      - decoder handle for this instance of the decoder
 * scratch     - pointer to the memory that can be used for scratch work 
 *               space
 * bitstream   - pointer to the bitstream structure
 *
 * Outputs:
 * scratch     - pointer to the memory used for scratch work space.  This 
 *               must be maintained as-is from the return of each call to 
 *               this function while the function's return value is 
 *               kDecoderStatus_MoreData.
 * bitstream   - pointer to the bitstream structure updated
 *
 * Return Value:
 * kDecoderStatus_NoError            - seek was successful
 * kDecoderStatus_MoreData           - more input data is required to 
 *                                     accomplish the seek
 * kDecoderStatus_UnsupportedFeature - the decoder cannot accomplish the 
 *                                     requested operation
 * kDecoderStatus_InvalidArgument    - the decoder instance is undefined,
 *                                     the scratch memory is undefined,
 *                                     or the bitstream structure is 
 *                                     undefined
 */
typedef eDecoderStatus fnBitstreamSeekTime(
    int                timeToSkip,
    oDecoderHandle     handle,
    void               *scratch,
    sDecoderBitstream  *bitstream
) ;


/*
 * Description:
 * Finishes the decode of the bitstream for the decoder instance.
 *
 * Inputs:
 * handle - decoder handle for this instance of the decoder
 * scratch - pointer to the memory that can be used for scratch work space
 *
 * Outputs:
 * None
 *
 * Return Value:
 * kDecoderStatus_NoError - the bitstream structure has been closed
 * kDecoderStatus_InvalidArgument - the decoder instance is undefined,
 *                                  or the scratch memory is undefined
 */
typedef eDecoderStatus fnDecoderCloseBitstream(
    oDecoderHandle         handle,
    void                   *scratch
) ;

/*
 * Description:
 * Destroys an instance of the decoder created with a call to DecoderCreate.
 * The memory associated with the decoder handle (state) can be reused 
 * after this function.
 *
 * Inputs:
 * handle - decoder handle for this instance of the decoder
 * scratch - pointer to the memory that can be used for scratch work space
 *
 * Outputs:
 * None
 *
 * Return Value:
 * kDecoderStatus_NoError - the decoder instance has been destroyed
 * kDecoderStatus_InvalidArgument - the decoder instance is undefined,
 *                                  or the scratch memory is undefined
 */
typedef eDecoderStatus fnDecoderDestroy(
    oDecoderHandle         handle,
    void                   *scratch
) ;

/*
 * Description:
 * An Audio Decoder is a structure of function pointers to each of
 * the functions previously described together with its state.
 */
typedef struct tagAudioDecoder
{
    oDecoderReference       DecoderReference ;
    fnDecoderRequirements   *DecoderRequirements ;
    fnDecoderCreate         *DecoderCreate ;
    fnDecoderOpenBitstream  *DecoderOpenBitstream ;
    fnDecodeHeader          *DecodeHeader ;
    fnDecodeFrame           *DecodeFrame ;
    fnBitstreamSeekBytes    *BitstreamSeekBytes ;
    fnBitstreamSeekTime     *BitstreamSeekTime ;
    fnDecoderCloseBitstream *DecoderCloseBitstream ;
    fnDecoderDestroy        *DecoderDestroy ;
} AudioDecoder ;

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* _GENERIC_AUDIO_DECODER_API_ */