mp3dec_mp3dec.h

瑞星微公司RK27XX系列芯片的SDK开发包

           * If interleaved output is not enabled
             The PCM samples for channel k are written to the buffer pointed
             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.
           */
        short          **channels ;// this variable is changed by Jeiff 02.09.2004
//    short          **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_ */