audiodec.h

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

/*
0123456789012345678901234567890123456789012345678901234567890123456789012345
*/

/*
 * $Copyright: 
 * ----------------------------------------------------------------
 * This confidential and proprietary software may be used only as
 * authorised by a licensing agreement from ARM Limited
 *   (C) COPYRIGHT 2001,2002 ARM Limited
 *       ALL RIGHTS RESERVED
 * The entire notice above must be reproduced on all authorised
 * copies and copies may only be made to the extent permitted
 * by a licensing agreement from ARM Limited.
 * ----------------------------------------------------------------
 * File:     audiodec.h,v
 * Revision: 1.9
 * ----------------------------------------------------------------
 * $
 *
 * Generic Audio decoder common API
 */
 
#ifndef _GENERIC_AUDIO_DECODER_API_
#define _GENERIC_AUDIO_DECODER_API_

#include "decoder_defines.h" //[OK] to know sample rates

#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
    
    /* 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
) ;