dmMPEG1AudioDecode(3dm)dmMPEG1AudioDecode(3dm)NAMEdmMPEG1AudioDecode - 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.
Page 1
dmMPEG1AudioDecode(3dm)dmMPEG1AudioDecode(3dm)RETURNED VALUE
Returns DM_FAILURE or DM_SUCCESS.
DESCRIPTIONdmMPEG1AudioDecode(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 ALSOdmMPEG1AudioDecoderCreate(3dm), dmMPEG1AudioDecoderSetParams(3dm),
dmMPEG1AudioDecoderGetParams(3dm), dmMPEG1AudioDecoderDestroy(3dm),
dmMPEG1AudioEncode(3dm).
Page 2
