mp3dec_mp3dec.h

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

     *                 returned by this function
     * scratch - pointer to the memory that can be used for scratch work space
     * formats - pointer to a constant decoder formats structure that defines
     *           the capabilities desired of the decoder; this must be the same
     *           structure that was passed to the function DecoderRequirements
     *           to guarantee that the state and scratch parameters reference
     *           enough memory.
     *
     * Outputs:
     * None
     *
     * Return Value:
     * oDecoderHandle - a pointer to the decoder's handle for this instance
     *                  of the decoder.  No assumptions should be made about
     *                  the address of this handle, in particular, it cannot
     *                  be assumed that this address will be the same as that
     *                  for the 'state' parameter.
     * NULL - the decoder could not be initialised
     */
    typedef oDecoderHandle fnDecoderCreate(
        oDecoderReference       decoderReference,
        void                    *instanceState,
        void                    *scratch,
        const sDecoderFormats   *formats
    ) ;

    /*
     * Description:
     * Enumeration of the sample rates supported by all the audio decoders
     */
    typedef enum tagDecoderSampleRate
    {
        kDecoderSampleRate_Undefined = 0,
        kDecoderSampleRate_8000Hz = 8000,
        kDecoderSampleRate_11025Hz = 11025,
        kDecoderSampleRate_12000Hz = 12000,
        kDecoderSampleRate_16000Hz = 16000,
        kDecoderSampleRate_22050Hz = 22050,
        kDecoderSampleRate_24000Hz = 24000,
        kDecoderSampleRate_32000Hz = 32000,
        kDecoderSampleRate_44100Hz = 44100,
        kDecoderSampleRate_48000Hz = 48000,
        kDecoderSampleRate_64000Hz = 64000,
        kDecoderSampleRate_88200Hz = 88200,
        kDecoderSampleRate_96000Hz = 96000
        /* add other sample rates here */
    } eDecoderSampleRate ;

    /*
     * Description:
     * Structure to hold the total number of channels and the split of this
     * number between each of the different channel positions
     *
     * The ordering of the channel positions in the structure - from lowest
     * word in memory to highest word in memory - defines the ordering of the
     * channels during output, with the left channel first followed by the
     * right in multi-channel output
     */
    typedef struct tagDecoderChannels
    {
        unsigned int   total ; /* total number of all channels */
        unsigned char  front ; /* number of front channels */
        unsigned char  side ; /* number of side channels */
        unsigned char  back ; /* number of back channels */
        unsigned char  lfe ; /* number of low frequency channels */
    } sDecoderChannels ;

    /*
     * Description:
     * Volume type and some of the values that can be given to control the
     * volume digitally in the decoder
     */

//typedef unsigned short tVolume ;

#define VOLUME_MUTE     0x0000
#define VOLUME_NORMAL   0x1000
#define VOLUME_MAXIMUM  0x7fff

    /*
     * Description:
     * Four packed chars describing the input bitstream type - or 0 if not
     * known.
     *
     * This is a read-only value, consisting of four ASCII characters,
     * packed in a big-endian manner, into a 32-bit word. None of the chars will
     * represent any non-printable characters, except that they may be 0
     */
    typedef unsigned int tBitstreamType ;

    /*
     * Description:
     * The bitstream structure controls the buffer management and maintains
     * other pieces of public information.
     *
     * Implementation:
     * The data passed to each of the decode functions is considered to be
     * a byte stream and is, therefore, endian invariant.
     *
     * Before calling any of the decoder functions which take the bitstream
     * structure as a parameter, the calling application must set the 'data'
     * element such that it points to the start of at least 'dataRequired'
     * bytes, with the first byte being that which is 'dataOffset' bytes from
     * the position in the bitstream referenced by 'data' with the previous
     * function call. If the 'data' element points to less than 'dataRequired'
     * bytes, the function will return kDecoderStatus_MoreData. The element
     * 'dataLength' should also be set to the actual number of bytes that can
     * be used by the decoder.
     *
     * Each decoder function that reads the bitstream will:
     * - set 'dataOffset' to indicate both the number of bytes that have been
     *   read and can be discarded, and the next point in the bitstream
     *   required for the next decoder function; this is usually just the
     *   number of bytes the decoder has read and decoded from the bitstream
     * - set 'dataRequired' to the minimum number of bytes the decoder needs
     *   to make any headway on the next bitstream decode call; this is
     *   guaranteed to be in the range 1 to the value for 'inputSize' returned
     *   in the decoder requirements structure
     *
     * Note that a decode function does not necessarily use - as indicated
     * by 'dataOffset' - all of the bytes requested by 'dataRequired'.  In some
     * circumstances a decoder may even return 'dataOffset'=0 and increase
     * 'dataRequired' over that of the previous call; the result of this is to
     * purely increase the amount of data that is required to continue
     * the decode.
     */
    typedef struct tagDecoderBitstream
    {
        /* input */
        /* pointer to the next bitstream bytes */
        char                *data ;

        /* the number of input bytes presented to the decoder. */
        unsigned int        dataLength ;

        /* digital volume to be used on decode (if required) */
//    tVolume             volume ;
        unsigned short             volume ;

        /* output/updated */
        /* the next data offset requested by the decoder from the address
           in the bitstream referenced by 'data'; all 'dataOffset' bytes in
           memory from 'data' can be discarded. This value may be set negative
           by the decoder only if the BitstreamSeekBytes or BitstreamSeekTime
           functions are called with the first parameter (offset) being negative.
           At all other times, this value will be positive
            */
        int                 dataOffset ;

        /* the next number of bytes required by the decoder to make some
           progress; this is guaranteed to be less than or equal to the value of
           'inputSize' returned in the decoder requirements */
        unsigned int        dataRequired ;

        /* bit rate in bits per second - or 0 if not known */
        unsigned int        bitRate ;

        /* offset in bytes of the first byte of the most recently decoded header
           relative to the bitstream position corresponding to the
           sDecoderBitstream->data pointer. Only valid immediately after DecodeHeader
           returns with kDecoderStatus_NoError. */
        int                 headerOffset ;

        /* number of bytes remaining in frame after header - 0 if not known. Only
           valid when DecodeHeader returns with kDecoderStatus_NoError. */
        unsigned int        frameRemain ;

        /* frame length in samples per channel - or 0 if not known */
        unsigned int        samplesPerChannelPerFrame ;

        /* output sample rate in Hz */
        eDecoderSampleRate  sampleRate ;

        /* number of channels in the bitstream */
        sDecoderChannels    channels ;

        /* type of input bitstream (if known) */
        tBitstreamType      bitstreamType ;

        /* output format for the bitstream (if known).
           features to be used when decoding */
        sDecoderFormats     formats ;
    } sDecoderBitstream ;

    /*
     * Description:
     * Initialise the bitstream structure to default values for the decoder
     * including setting the first value for 'dataRequired' and initialising
     * 'dataOffset' to 0.
     *
     * Inputs:
     * 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
     * formats - pointer to a constant decoder formats structure that defines
     *           the formats of the data in the bitstream; this must be a
     *           subset of the structure that was passed to the functions
     *           DecoderRequirements and DecoderCreate and details
     *           the formats for the data to be decoded
     *
     * Outputs:
     * bitstream - pointer to the bitstream structure initialised with
     *             suitable default values for the given formats
     *
     * Return Value:
     * kDecoderStatus_NoError - the bitstream structure has been initialised
     * kDecoderStatus_UnsupportedFeature - the formats requested of the
     *                                     decoder cannot be achieved
     * kDecoderStatus_InvalidArgument - the decoder instance is undefined,
     *                                  the scratch memory is undefined
     *                                  the bitstream structure is undefined
     *                                  or the formats structure is undefined
     */
    typedef eDecoderStatus fnDecoderOpenBitstream(
        oDecoderHandle         handle,
        void                    *scratch,
        sDecoderBitstream      *bitstream,
        const sDecoderFormats  *formats
    ) ;


    /*
     * Description:
     * Find and decode the next valid frame header in the bitstream.
     *
     * Implementation:
     * The function should be called repeatedly while kDecoderStatus_MoreData
     * is returned.  For example:
     *
     * do
     * {
     *     add data to the fields of the bitstream
     *     result = DecodeHeader( handle, scratch, bitstream ) ;
     * } while( kDecoderStatus_MoreData == result ) ;
     *
     * if( 0 > result )
     * {
     *     a fatal error has occurred
     * }
     *
     * Inputs:
     * 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:
     * bitstream - pointer to the bitstream structure updated; header fields
     *             have been updated only if they were decoded; any field that
     *             is not updated is maintained with its value as passed
     *
     * Return Value:
     * kDecoderStatus_NoError - header has been decoded
     * kDecoderStatus_MoreData - more input data is required to decode the
     *                           header
     * kDecoderStatus_NoFrameHeader - decoder could not find a frame header
     * kDecoderStatus_BrokenFrame - header is inconsistent
     * kDecoderStatus_ReservedBitRate - illegal/forbidden bit rate
     * kDecoderStatus_ReservedSamplingFrequency -
     *   undefined or reserved output sampling frequency
     * kDecoderStatus_UnsupportedFeature - frame is not supported
     * kDecoderStatus_InvalidArgument - the decoder instance is undefined,
     *                                  the scratch memory is undefined
     *                                  or the bitstream structure is undefined
     */
    typedef eDecoderStatus fnDecodeHeader(
        oDecoderHandle     handle,
        void               *scratch,
        sDecoderBitstream  *bitstream
    ) ;

    /*
     * Description:
     * Structure to hold the channels for output
     */
    typedef struct tagDecoderOutput
    {
        /* input */
        /* array of channel numbers that specify which channels in a
           multi-channel decode are desired as output; the order in which these
           channels are desired from the decoder is given by the order of the
           channel numbers in the array from lowest array index to highest
           array index

           the pointer should be NULL if all channels are required and the
           default ordering of the channels should be used */
        short         *channelsRequired ;
        /* number of output memory blocks referenced by 'channels'

           if 'channelsRequired' is non-NULL, this number is also the number
           of entries in the 'channelsRequired' array indicating the number of
           of channels to output

           if 'channelsRequired' is NULL, this number must be at least the
           number specified by the output format type when initialising the
           bitstream for this instance */
        unsigned int  numberOfChannels ;
        /* maximum number of samples per channel to decode and will fit
           into the memory referenced by the 'channels' pointer; this value
           must be at least 'outputSize' specified in the decoder requirements
           for this decoder instance */
        unsigned int  maxNumberOfSamples ;

        /* output */
        /* the number of samples decoded and contained in the 'channels'
           pointer; less than or equal to 'maxNumberOfSamples' */
        unsigned int  numberOfSamples ;

        /* array of output channel pointers and inter-sample offsets.