dmMPEG1AudioDecode(3dm)

NAME
     dmMPEG1AudioDecode - decodes a single compressed block of data created by
     a call to dmMPEG1AudioEncode(3dm).


SYNOPSIS
     #include <dmedia/dmedia.h>
     #include <dmedia/dm_audioutil.h>

     DMstatus dmMPEG1AudioDecode(DMMPEG1audiodecoder decoder,
                                         unsigned char *cmpData,
                                         short *output,
                                         int *fmtBytes)


PARAMETER
     decoder   DMMPEG1audiodecoder structure, created by
               dmMPEG1AudioDecoderCreate(3dm), specifies and stores the signal
               processing parameters.  It describes the kind of decompression
               to perform, and holds the between-block state of the
               decompressor.  It is initially generated and processed by calls
               to dmMPEG1AudioDecoderCreate(3dm) and
               dmMPEG1AudioDecoderSetParams(3dm), and is modified on each
               call.  To get decoder in the proper state for the first call,
               see DESCRIPTION below.


     cmpData   points to the next block of compressed bytes to be decoded.
               The calling procedure should pass an entire compressed block's
               worth of bytes.  Generally, this amount is unkown and the
               calling procedure must queue up at least as many bytes as
               returned from a call to dmMPEG1AudioHeaderGetBlockBytes(3dm) as
               that is the expected length that dmMPEG1AudioDecode(3dm) will
               require.


     output    points to a pre-allocated block of memory into which
               dmMPEG1AudioDecode(3dm) will write the decompressed sample
               frames. output must be big enough to hold the entire
               decompressed frame.  Note that all decompressed blocks contain
               the same number of sample frames.  A way to determine this size
               is described below under DESCRIPTION.


     fmtBytes  pointer to an integer return value; indicates the actual number
               of compressed bytes consumed. By advancing the index in the
               compressed data stream by this amount, the next block of
               compressed data will be located correctly. If the decoder
               structure or the compressed data is malformed, this return will
               be zero, indicating an error.
RETURNED VALUE
     Returns DM_FAILURE or DM_SUCCESS.


DESCRIPTION
     dmMPEG1AudioDecode(3dm) implements MPEG1 audio decompression.

     The decoder state parameters need to be initialized before the first call
     to dmMPEG1AudioDecode(3dm), after which it is self-maintaining. DMparam
     *params should be passed to dmMPEG1AudioHeaderGetParams in order to fill
     in the params structure from the compressed data header, and find the
     worst-case buffering requirements for the compressed data.  Then, a call
     to dmMPEG1AudioDecoderSetParams(3dm) will set decoding parameter values
     for decoder.  And dmMPEG1AudioDecoderGetParams(3dm) will be used to qurey
     DM_AUDIO_CODEC_FRAMES_PER_BLOCK, which contains the size of decompressed
     blocks for the compressed stream.


NOTE
     compression/decompression delay will be caused by filter operations that
     convolve a N past input samples with a filter M-coefficient array to
     create N+M-1 output samples.  The filtered signal contains more samples
     than the unfiltered signal. the output signal is offset by
     DM_AUDIO_CODEC_FILTER_DELAY samples from the first sample thus omits the
     last DM_AUDIO_CODEC_FILTER_DELAY samples from the output file.


SEE ALSO
     dmMPEG1AudioDecoderCreate(3dm), dmMPEG1AudioDecoderSetParams(3dm),
     dmMPEG1AudioDecoderGetParams(3dm), dmMPEG1AudioDecoderDestroy(3dm),
     dmMPEG1AudioEncode(3dm).