mp3dec_mp3dec.h

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

#ifndef _GENERIC_AUDIO_DECODER_API_
#define _GENERIC_AUDIO_DECODER_API_

#ifdef __cplusplus
extern "C"   /* allow C++ to use these headers */
{
#endif /* __cplusplus */

    /*
     * --------Generic Audio Decoder Common API--------
     *
     * An audio decoder is a structure consisting of a decoder reference pointer,
     * and pointers to functions that are the decoder methods.  This is defined
     * last after each of the defines, enumerations, structures and function
     * types used by a decoder have been defined.
     */

    /*
     * Description:
     * Enumeration for error/status return codes.  A function may return any
     * error/status return code in addition to those return codes that are
     * explicitly defined as return codes.
     *
     * For example, any function may return the non-specific fatal or non-fatal
     * error/status return code but this is not given as an explicit return
     * code to any function in this API.
     *
     * Implementation:
     * Fatal errors -     A fatal error is one from the which the decoder cannot
     *                    recover.  If this results from an operation involving a
     *                    bitstream, no more decoding of the bitstream is possible.
     *                    In all cases, a restart of the decoder is necessary.
     *
     *                    Fatal-errors are negative.
     *
     * Non-fatal errors - A non-fatal error is an error indicating that the
     *                    previous operation has failed but the decoder can
     *                    recover from the error starting from the next frame.
     *
     *                    Non-fatal errors are positive.
     */

    typedef enum tagDecoderStatus
    {
        /* SUCCESS: zero */
        /* general success */
        kDecoderStatus_NoError = 0,

        /* FATAL ERRORS: negative */
        /* non-specific fatal error */
        kDecoderStatus_Fatal_Error = -1,

        /* the bitstream has been corrupted in some way */
        kDecoderStatus_Fatal_BadBitstream = -2,

        /* bitstream contains more channels of output than either requested
           or than the decoder supports */
        kDecoderStatus_Fatal_TooManyChannels = -3,

        /* bitstream contains a feature that is not supported by decoder */
        kDecoderStatus_Fatal_UnsupportedFeature = -4,

        /* insert more fatal errors here in increasing negativity */

        /* NON-FATAL ERRORS: positive */
        kDecoderStatus_Error = 1, /* non-specific non-fatal error */

        /* the decoder requires more bitstream data to complete */
        kDecoderStatus_MoreData = 2,

        /* there are more decoded samples ready for output */
        kDecoderStatus_MoreSamples = 3,

        /* decoder could not find a valid frame header */
        kDecoderStatus_NoFrameHeader = 4,

        /* frame encountered cyclic-redundancy check error */
        kDecoderStatus_CRCError = 5,

        /* the frame is corrupted */
        kDecoderStatus_BrokenFrame = 6,

        /* the decoder doesn't recognise the bitstream */
        kDecoderStatus_UnknownBitstream = 7,

        /* bitstream contains a feature that is not supported by decoder */
        kDecoderStatus_UnsupportedFeature = 8,

        /* frame has been discarded as invalid */
        kDecoderStatus_FrameDiscarded = 9,

        /* output sampling frequency of decoded data is not valid */
        kDecoderStatus_ReservedSamplingFrequency = 10,

        /* incoming bit rate of data is not valid */
        kDecoderStatus_ReservedBitRate = 11,

        /* channel configuration is invalid */
        kDecoderStatus_InvalidChannelConfiguration = 12,

        /* not enough output channel memory blocks have been provided */
        kDecoderStatus_TooFewOutputChannels = 13,

        /* one of the arguments to the function is not valid/correct */
        kDecoderStatus_InvalidArgument = 14,

        DECODERSTATUS_REWIND = 15,

        DECODERSTATUS_FASTFORWARD = 16,

        kDecoderStatus_Fseek_Error = 17
        /* insert more non-fatal errors here in increasing positivity */
    } eDecoderStatus ;

    /*
     * Description:
     * This is a 32bit value that is used to parameterise a decoder. The
     * interpretation of this value is decoder specific and should be documented
     * separately with each decoder. It is provided in the AudioDecoder
     * structure.
     */
    typedef void *oDecoderReference ;

    /*
     * Description:
     * Output data format types from a decode.
     *
     * The output format is made up of the desired flags in the top 20 bits
     * and the maximum number of channels in the bottom 12 bits.
     */
    typedef unsigned int tOutputFormats ;

    /* output format flags */
    /* mask to extract flags from output fromat type */
#define OUTPUT_FORMAT_FLAGS_MASK           0xfffff000
    /* 16-bit sample size */
#define OUTPUT_FORMAT_16BIT                0x00001000
    /* 32-bit sample size */
#define OUTPUT_FORMAT_32BIT                0x00002000
    /* Interleaved output via sDecoderOutput.channelOffsets */
#define OUTPUT_FORMAT_INTERLEAVED          0x00004000
    /* stereo-to-mono downmix */
#define OUTPUT_FORMAT_STEREO_MONO_DOWNMIX  0x00008000
    /* add more output format flag here */

    /* output format maximum channel count */
    /* mask to extract channel count from output format type */
#define OUTPUT_FORMAT_CHANNEL_COUNT_MASK   0x00000fff
    /* single-channel mono */
#define OUTPUT_FORMAT_MONO                 1
    /* dual-channel stereo */
#define OUTPUT_FORMAT_STEREO               2
    /* surround sound 5.1 format */
#define OUTPUT_FORMAT_5_1                  6
    /* add more output format maximum channel count definitions here */

    /*
     * Description:
     * Additional features that may be supported by an audio decoder in
     * addition to the actual decode operation
     */
    typedef unsigned int tDecoderFeatures ;

    /* no additional decoder features */
#define DECODER_FEATURE_NONE             0x00000000
    /* decoder supports digital volume */
#define DECODER_FEATURE_VOLUME_CONTROL   0x00000001
    /* quality vs MHz tradeoffs supported */
#define DECODER_FEATURE_QUALITY_CONTROL  0x00000002
    /* halve sample rate on output */
#define DECODER_FEATURE_SAMPLE_RATE_D2   0x00000004
    /* quarter sample rate on output */
#define DECODER_FEATURE_SAMPLE_RATE_D4   0x00000008

    /* add more decoder features here */

    /*
     * Description:
     * Structure to hold the output sample type and decoder features.
     * Format types and features can be combined by a bitwise OR.
     */
    typedef struct tagDecoderFormats
    {
        tOutputFormats     outputFormats ;
        tDecoderFeatures   decoderFeatures ;
    } sDecoderFormats ;

    /*
     * Description:
     * Structure to hold the requirements of the decoder in order to perform
     * the decode operation requested of it
     */
    typedef struct tagDecoderRequirements
    {
        /* the number of bytes of state required for an instance of the
           decoder with the requested features; this should be used to allocate
           a block of memory of this size that is fixed in memory and is
           maintained between function calls and cannot be re-used during the
           life of the decoder instance for which it is associated */
        unsigned int  instanceStateSize ;

        /* the size of the scratch area for decoding a frame in which
           the decoder can perform the decode operation; this should be used
           to allocate a block of memory of this size, but, unlike the state,
           this can be re-used between function calls, except where explicitly
           stated otherwise in the description for a function; where the memory
           can be re-used, the scratch space contents do not need to be
           maintained in memory nor does the address of the scratch space
           have to remain fixed so it is acceptable to use different blocks of
           memory for the scratch with every function call, except where
           indicated otherwise */
        unsigned int  scratchSize ;

        /* the minimum number of sequential bytes of input bitstream data
           the decoder will require in one go; this is the minimum number
           that each decode operation will require in order to make any
           progress; an input buffer of at least this size will be sufficient
           to decode all files */
        unsigned int  inputSize ;

        /* the maximum number of sequential bytes of input
           bitstream data the decoder will require in one go in order
           to decode an entire frame of data across all possible input files;
           if an input buffer of at least this size is used it will be
           sufficient to decode an entire frame at a time across all input
           files; this is, therefore, the ideal input buffer size */
        unsigned int  maxInputSize ;

        /* the minimum number of sequential samples of output data, per
           channel, that can be returned by the decoder; an output buffer
           of at least this size will be sufficient to decode all files;
           note that this is samples, and not bytes, per channel */
        unsigned int  outputSize ;

        /* the maximum number of sequential samples of output data for each
           channel the decoder will require in one go in order to output
           an entire frame of decoded data across all possible input
           files; note that this is samples, and not bytes, per channel */
        unsigned int  maxOutputSize ;
    } sDecoderRequirements ;

    /*
     * Description:
     * Determine the requirements of the decoder needed to implement a
     * given set of capabilities.
     *
     * Implementation:
     * Given a set of capabilities required of the decoder, this function will
     * modify them in place to reflect the best agreement between the requested
     * capabilities and what the decoder can support. It will then return the
     * specific requirements of the decoder in order to achieve these
     * capabilities.
     *
     * This function should be called prior to initialisation.  It is purely
     * for information purposes and does not affect the decoder in any way -
     * that is, for each implementation of a decoder this function need only
     * be called once to determine the requirements for a specific set of
     * formats required of the decoder.
     *
     * Inputs:
     * decoderReference - decoder handle for this decoder from the AudioDecoder
     *                  structure
     * requirements - pointer to decoder requirements structure
     * formats - pointer to a constant decoder formats structure that defines
     *           the capabilities desired of the decoder
     *
     * Outputs:
     * requirements - pointer to decoder requirements structure initialised
     *                with the requirements of the decoder in order to achieve
     *                the given capabilities; the values of each structure
     *                entry are undefined if an error is returned.
     *
     * Return Value:
     * kDecoderStatus_NoError - all the capabilities can be achieved and
     *                          the decoder requirements structure has been
     *                          initialised with appropriate values
     * kDecoderStatus_UnsupportedFeature - the capabilities requested of the
     *                                     decoder cannot be achieved
     * kDecoderStatus_InvalidArgument - the decoder state was not correct,
     *                                  the requirements structure is undefined
     *                                  or the formats structure is undefined
     */
    typedef eDecoderStatus fnDecoderRequirements(
        oDecoderReference       decoderReference,
        sDecoderRequirements    *requirements,
        sDecoderFormats         *formats
    ) ;

    /*
     * Description:
     * Opaque type to represent a handle to a decoder instance.  No assumptions
     * should be made about this handle.  It cannot be assumed, for example,
     * that this handle is unique for every instance of a decoder.
     */
    typedef void *oDecoderHandle ;

    /*
     * Description:
     * Create an instance of the decoder given a set of capabilities required
     * of the decoder.
     *
     * Inputs:
     * decoderReference - decoder handle for this decoder from the AudioDecoder
     *                  structure
     * instanceState - pointer to the memory that can be used for the decoder's
     *                 internal state for this instance of the decoder; this
     *                 pointer is maintained in the decoder handle that is