wmaudio.h

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

 *                  state of the WMAudio decoder
 *                  This memory should be cleared before the first call
 *                  to WMAFileDecodeInit
 *   
 *  nDecoderFlags    : bit-or'd options DECOPT*. Can be 0
 *  nDRCSetting      : 0, 1, or 2.
 *  nDstChannelMask  : Need not have any relation to source channels. 
 *                     Used only if "nDecoderFlags | DECOPT_CHANNEL_DOWNMIXING" is true.
 *  nInterpResampRate: can be 0.
 *  pPCMFormat is filled by the function.
 *  wTargetAudioStream Specify which audio stream among all audio streams to decode. 1 or above.
 *
 * Return Value
 * ------------
 *   cWMA_NoErr                decoder initialized
 *   cWMA_BadArgument          bad argument passed in
 *   cWMA_BadAsfHeader         bad ASF header
 *   cWMA_BadDRMType           unknown encryption type
 *   cWMA_DRMFailed            DRM failed
 *   cWMA_Failed               decoder Initialization failed 
 */
tWMAFileStatus WMAFileDecodeInitEx (tHWMAFileState phstate, tWMA_U16 nDecoderFlags,
                                    tWMA_U16 nDRCSetting, BOOL bDropPacket, 
                                    tWMA_U32 nDstChannelMask,   
                                    tWMA_U32 nInterpResampRate,
                                    PCMFormat* pPCMFormat,
                                    tWMA_U16 wTargetAudioStream);
#ifdef _ELIMINATED
/*
 *        WMAFileMBRAudioStreams
 *        =================
 *
 * Description
 * -----------
 * Given all the streams in ASF file, this function provides
 * the otal number of audio streams in the ASF file.
 *
 * Must have called WMAFileIsWMA prior to calling this function.
 *
 * Syntax
 * ------
 * tWMAFileStatus WMAFileMBRAudioStreams (tHWMAFileState phstate, 
 *                                        tWMA_U16 *pwNumberOfAudioStreams);
 *
 * where:
 *
 *   phstate                pointer to the handle that holds the internal
 *                          state of the WMAudio decoder
 *   pwNumberOfAudioStreams pointer to return the number of audio streams in the file
 *   
 * Return Value
 * ------------
 *   cWMA_NoErr                decoder initialized
 *   cWMA_BadArgument          bad argument passed in
 */
/* O.K> to make it the same as in .c
 *  tWMAFileStatus WMAFileMBRAudioStreams (tHWMAFileState phstate, 
                                         tWMA_U16 *pwTotalNumberOfAudioStreams);
*/
tWMAFileStatus WMAFileMBRAudioStreams (tWMAFileHdrState *pstate, 
                                       tWMA_U16 *pTotalAudioStreams);
#endif /*_ELIMINATED*/

/*
 *        WMAFileSetTargetMBRAudioStream
 *        =================
 *
 * Description
 * -----------
 * Given all the streams in ASF file, this function sets the
 * the audio streams the decoder would like to deal with.
 *
 * Must have called before calling WMAFileIsWMA. That is, even before it is ascertained 
 * that the file is MBR! 
 * 
 * Syntax
 * ------
 * tWMAFileStatus WMAFileSetTargetMBRAudioStream (tHWMAFileState phstate, 
 *                                                tWMA_U16 wTargetAudioStream);
 *
 * where:
 *
 *   phstate             pointer to the handle that holds the internal
 *                       state of the WMAudio decoder
 *   wTargetAudioStream  Specify which audio stream the decoder is attempting to handle. 
 *                       A number greater than or equal to 1 is expected.
 *   
 * Return Value
 * ------------
 *   cWMA_NoErr                decoder initialized
 *   cWMA_BadArgument          bad argument passed in
 */
  /* O.K. to fit the same as wmaudio.c
   * tWMAFileStatus WMAFileSetTargetMBRAudioStream (tHWMAFileState phstate, 
                                                 tWMA_U16 wTargetAudioStream);
*/
tWMAFileStatus WMAFileSetTargetMBRAudioStream (tWMAFileHdrState *pstate, 
                                               tWMA_U16 wTargetAudioStream);

/*
 *        WMAFileIsWMA
 *        ============
 *
 * Description
 * -----------
 * Checks to see if the file is decodable.  Uses WMAFileCBGetData(),
 * but the first argument to it is not really of type tHWMAFileState,
 * but tWMAFileIdState.
 *
 * To decode the file, the app should call WMAFileDecodeInit() or WMAFileDecodeInitEx()
 * instead.
 *
 * This function was added in case the app wants to determine the
 * type of the file without fully allocating tHWMAFileState.
 *
 * Syntax
 * ------
 *   tWMAFileStatus WMAFileIsWMA(tWMAFileHdrState *state);
 *
 * where:
 *
 *   state          pointer to the smaller structure that contains
 *                  state of the checking function
 *
 * Return Value
 * ------------
 *   cWMA_NoErr                yes, it's a WMA file
 *   cWMA_BadArgument          bad argument passed in
 *   cWMA_BadAsfHeader         bad ASF header
 *
 */
tWMAFileStatus WMAFileIsWMA (tWMAFileHdrState *state);

/*
 *        WMAFileCBGetData
 *        ================
 *
 * Description
 * -----------
 * Supplies more data to the WMAudio decoder.  Not implemented by
 * the WMAudio decoder library.
 *
 * It is a callback function implemented by the application.  When
 * the WMAudio library needs more data to process (both to parse
 * informatio and to decode the actual data bitstream), the library
 * will call this function.
 *
 * Called by WMAFileDecodeInit(), WMAFileContentDesc() and
 * WMAFileDecodeData().
 *
 * Syntax
 * ------
 *   tWMA_U32 WMAFileCBGetData(tHWMAFileState hstate,
 *                             tWMA_U32 offset,
 *                             tWMA_U32 num_bytes,
 *                             unsigned char  **ppData);
 *
 * where:
 *
 *   state          pointer to the structure that holds the internal
 *                  state of the WMAudio decoder
 *   offset         offset into the WMA file to get the data from
 *   num_bytes      how many bytes to get
 *   ppData         pointer to contain the returned buffer with more
 *                  data
 *                  The WMA library may over-write this buffer
 *
 * Return Value
 * ------------
 *   tWMA_U32       how many actually returned
 *                  should be same as num_bytes except for at the
 *                  very end of the file
 *
 */
/* O.K. to fit pattern in main.c
 * extern tWMA_U32 WMAFileCBGetData (
    tHWMAFileState hstate,
    tWMA_U64 offset,
    tWMA_U32 num_bytes,
    unsigned char **ppData);*/
extern tWMA_U32 WMAFileCBGetData (
    tHWMAFileState *state,
    tWMA_U64 offset,
    tWMA_U32 num_bytes,
    unsigned char **ppData);   
     
extern tWMA_U32 WMAFileFBGetData (
    tHWMAFileState *state,
    tWMA_U64 offset,
    tWMA_U32 num_bytes,
    unsigned char **ppData);       

/*
 *        WMAFileDecodeClose
 *        =================
 *
 * Description
 * -----------
 * Closes the WMAudio decoder and frees all allocated memories.
 *
 * Must be called after decoding a WMA file.
 *
 * Syntax
 * ------
 *   tWMAFileStatus WMAFileDecodeClose (tHWMAFileState* phstate);
 *
 * where:
 *
 *   phstate        pointer to the handle that holds the internal
 *                  state of the WMAudio decoder
 *
 * Return Value
 * ------------
 *   cWMA_NoErr                decoder closed 
 *   cWMA_BadArgument		   bad argument(s)	 	
 */
tWMAFileStatus WMAFileDecodeClose (tHWMAFileState* phstate);

/*
 *       WMAFileDecodeInfo
 *       =================
 *
 * Description
 * -----------
 * Retrieves the header information for the WMA file.
 *
 * Syntax
 * ------
 *   tWMAFileStatus WMAFileDecodeInfo(tHWMAFileState hstate,
 *                                    tWMAFileHeader *hdr);
 *
 * where:
 *
 *   state          pointer to the structure that holds the internal
 *                  state of the WMAudio decoder
 *   hdr            pointer to the structure that holds the WMA file
 *                  header info
 *
 * Return Value
 * ------------
 *   cWMA_NoErr                header retrieved ok
 *   cWMA_BadArgument          bad argument(s)
 *
 */
tWMAFileStatus WMAFileDecodeInfo (tHWMAFileState hstate, tWMAFileHeader *hdr);

#ifdef _ELIMINATED
/*
 *       WMAFileContentDesc
 *       ==================
 *
 * Description
 * -----------
 * Retrieves the content description for the WMA file.  Content
 * descriptions are such as the song title, the author, the
 * copyright info, the song description, and the rating info.
 * All these are part of the standard ASF description.
 *
 * Not all songs have content descriptions.
 *
 * Syntax
 * ------
 *   tWMAFileStatus WMAFileContentDesc (tHWMAFileState hstate, )
 *                                      const tWMAFileContDesc **ppDesc);
 *
 * where:
 *
 *   state          pointer to the structure that holds the internal
 *                  state of the WMAudio decoder
 *   ppDesc         pointer of pointer to the Extended Content Desc
 *                  structure that holds in the ASF file.
 *
 * Return Value
 * ------------
 *   cWMA_NoErr                description retrieved ok
 *   cWMA_BadArgument          bad argument(s)
 *   ppDesc is the pointer of pointer to the ASF content desc object.
 ***** DO NOT RELEASE THIS POINTER *************
 */
tWMAFileStatus WMAFileContentDesc (tHWMAFileState hstate, const tWMAFileContDesc **ppDesc);
#endif /*_ELIMINATED*/

/*
 *       WMAFileDecodeData
 *       =================
 *
 * Description
 * -----------
 * Decodes WMAudio bitstream.
 *
 * Syntax
 * ------
 *   tWMAFileStatus WMAFileDecodeData (tHWMAFileState hstate, tWMA_U32 *pnDecodedSamples);
 *
 * where:
 *
 *   state              pointer to the structure that holds the internal
 *                      state of the WMAudio decoder
 *   pnDecodedSamples   pointer to the number of samples decoded by this call. 
 *
 * Return Value
 * ------------
 *   cWMA_NoErr                frame decoded ok
 *   cWMA_BadArgument          bad argument
 *   cWMA_NoMoreFrames         no more data to decode
 *   cWMA_BadPacketHeader      Bad Packet header
 *
 */
#ifdef USE_SPDTX
tWMAFileStatus WMAFileDecodeToSpdif (tHWMAFileState hstate, tWMA_U32 *pnDecodedSamples );
#else
tWMAFileStatus WMAFileDecodeData (tHWMAFileState hstate, tWMA_U32 *pnDecodedSamples);
#endif

/*
 *       WMAFileGetPCM
 *       =============
 *
 * Description
 * -----------
 * Write PCM samples from the WMAudio bitstream previously decoded by
 * WMAFileDecodeData().
 *
 * WMAFileGetPCM() may have to be called more than once to obtain all
 * of the samples for the frame. The frame is complete when the number
 * of samples written is less than the number of samples requested.
 *
 * Syntax
 * ------
 *   tWMA_U32 WMAFileGetPCM(tHWMAFileState hstate,
 *                          tWMA_I16 *pi16Channel0, tWMA_I16 *pi16Channel1,
 *                          tWMA_U32 iSizeOfChannel0, tWMA_U32 max_nsamples
                            tWMA_I64* piTimeStamp);
 *
 * where:
 *
 *   state          pointer to the structure that holds the internal
 *                  state of the WMAudio decoder
 *   pi16Channel0   pointer to output buffer for left-channel PCM, or the entire PCM output if it is inter-leaved form
 *   pi16Channel1   pointer to output buffer for right-channel PCM, NULL if the output PCM is in parallel form
 *   iSizeOfChannel0 size of the pi16Channel0 buffer in bytes. It is assumed that Channel1 is the same size.
 *                   *** NOTE*** If Channel downmixing, frequency resampling or bit-depth conversion is being requested, 
 *                               the memory provided should be for maximum of source & destination sizes.
 *   max_nsamples   maximum number of samples to write per channel
 *   piTimeStamp    Pointer for getting TimeSatmp value.
 *
 * Return Value
 * ------------
 *   tWMA_U32       number of samples written
 *                  < max_nsamples when frame complete
 *
 */
#ifdef USE_SPDTX
tWMA_U32 WMAFileGetSpdifBurst( tHWMAFileState hstate, 
                               tWMA_U8  *pbBurst,
                               tWMA_U32  cbBurst,
                               tWMA_I64* piTimeStamp);
#else
tWMA_U32 WMAFileGetPCM (tHWMAFileState hstate,
    tWMA_I16 *pi16Channel0, tWMA_I16 *pi16Channel1,
    tWMA_U32 iSizeOfChannel0,
    tWMA_U32 max_nsamples,
    tWMA_I64* piTimeStamp);
#endif


#ifdef WMA_SEEK_TEST //O.K.

/*
 *       WMAFileSeek
 *       ===========
 *
 * Description
 * -----------
 * Seek to a time into the WMA file.  It seeks to the nearest seek
 * point.
 *
 * Syntax
 * ------
 *   tWMAFileStatus WMAFileSeek (tHWMAFileState hstate, tWMA_U32 msSeek, tWMA_U32 *pmsActual);
 *
 * where:
 *
 *   state          pointer to the structure that holds the internal
 *                  state of the WMAudio decoder
 *   msSeek         time position to seek from the beginning of the
 *                  clip, in milliseconds
 *  pmsActual       actual time position from the beginning of the
 *                  clip, in milliseconds
 *
 * Return Value
 * ------------
 *   cWMA_NoErr                Seek OK
 *   cWMA_BadArgument          bad argument
 *   cWMA_Failed               Decoder Failed to reset
 *   cWMA_BadPacketHeader      Bad Packet/Payload header
 */
tWMAFileStatus WMAFileSeek (tHWMAFileState hstate, tWMA_U32 msSeek, tWMA_U32 *pmsActual);

/*
 *       WMAFileSeekBase
 *       ===========
 *
 * Description
 * -----------
 * Seek to a time into the WMA file.  It seeks to the nearest seek
 * point.
 *
 * Syntax
 * ------
 *   tWMAFileStatus WMAFileSeekBase(tHWMAFileState hstate,
 *                                  tWMA_U32 * pmsSeek,
 *                                  tWMA_U32 * piPacket,
 *                                  tWMA_U32 * pmsActual,
 *                                  BOOL fProWMAEncoder,
 *                                  BOOL fSeekToPacket);
 *
 * where:
 *
 *   state          pointer to the structure that holds the internal
 *                  state of the WMAudio decoder
 *   pmsSeek        points to the time you want to seek to
 * 
 *  pmsActual       actual time position from the beginning of the
 *
 *   piPacket       points to the packet you want to seek to
 *
 *   fProWMAENcoder Is the function called by Professional WMA encoder?
 *
 *   fSeekToPacket  indicate whether to seek to packet or to seek to timestamp. 
 *                  So if fSeekToPacket is true, piPacket will be used, otherwise, 
 *                  pmsSeek will be used. But after the successfully seeking, 
 *                  both piPacket and pmsSeek will be updated to the actual timestamp and packet we seek into.
 * Return Value
 * ------------
 *   cWMA_NoErr                Seek OK
 *   cWMA_BadArgument          bad argument
 *   cWMA_Failed               Decoder Failed to reset
 *   cWMA_BadPacketHeader      Bad Packet/Payload header
 *
 *  That function was added purely for the purpose of the WM Compression tool. Except the WM Compression tool, 
 *  all other callers should call WMAFileSeek.
 */
tWMAFileStatus WMAFileSeekBase(tHWMAFileState hstate,
                                   tWMA_U32 * pmsSeek,
                                   tWMA_U32 * piPacket,
                                   tWMA_U32 * pmsActual,
                                   BOOL fProWMAEncoder,
                                   BOOL fSeekToPacket);
  
  
#endif //WMA_SEEK_TEST  //O.K.


                                   
#ifdef __cplusplus
}
#endif /* __cplusplus */

/*
#ifdef USE_PACK_HEADERS
#include <poppack.h>
#endif
*/

//***********************************************************************
// Exercising Rapier Special Modes, not everything available all the time
//***********************************************************************
#define DECOPT_CHANNEL_DOWNMIXING      0x00000001
#define DECOPT_DRC                     0x00000002
#define DECOPT_INTERPOLATED_DOWNSAMPLE 0x00000004
#define DECOPT_HALF_TRANSFORM          0x00000008
#define DECOPT_HALF_UP_TRANSFORM       0x00000010
#define DECOPT_2X_TRANSFORM            0x00000020
#define DECOPT_REQUANTTO16             0x00000040
#define DECOPT_DOWNSAMPLETO44OR48      0x00000080
#define DECOPT_LTRTDOWNMIX             0x00000100

#endif /* _WMAUDIO_API_H_ */