dmMPEG1AudioEncode(3dm)

NAME
     dmMPEG1AudioEncode - Compresses a single block of audio data using MPEG1
     audio compression algorithm.


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

     DMstatus dmMPEG1AudioEncode(DMMPEG1audioencoder encoder,
                                         short *sampBuf,
                                         unsigned char *output,
                                         int *frameBytes)


PARAMETER
     encoder   DMMPEG1audioencoder structure, created by
               dmMPEG1AudioEncoderCreate(3dm), specifies and stores the signal
               processing parameters.  It describes the kind of compression to
               perform, and holds the between-block state of the compressor.
               It is initially generated and processed by calls to
               dmMPEG1AudioEncoderCreate(3dm) and
               dmMPEG1AudioEncoderSetParams(3dm), and is modified on each
               call.


     sampBuf   pointer to input sample data buffer.  The data format is short
               (16-bit).  The samples are assumed to be two's complement.  The
               block of audio data is understood to be
               DM_AUDIO_CODEC_FRAMES_PER_BLOCK sample frames long, where this
               is a symbol, which value is returned by
               dmMPEG1AudioEncoderGetParams(3dm).  For each call to
               dmMPEG1AudioEncode(3dm), DM_AUDIO_CODEC_FRAMES_PER_BLOCK sample
               frames long data must be provided in the buffer.


     output    pointer to output data buffer, an array of bytes.  The data
               format is unsigned char (8-bit).  It points to a pre-allocated
               byte block into which dmMPEG1AudioEncode(3dm) will write the
               compressed data for this block.  The block must be at least
               DM_AUDIO_CODEC_MAX_BYTES_PER_BLOCK bytes long, where this is
               also a symbol, which value is also returned by
               dmMPEG1AudioEncoderGetParams(3dm).


     frameBytes
               pointer to an integer return value; indicates the actual number
               of compressed bytes written into the data structure (which will
               be less than or equal to DM_AUDIO_CODEC_MAX_BYTES_PER_BLOCK).
               It is the value returned by the function.  In the case of some
               error occuring such as an unrecognized encoder structure, this
               value is zero.
RETURNED VALUE
     Returns DM_FAILURE or DM_SUCCESS.


DESCRIPTION
     dmMPEG1AudioEncode(3dm) implements MPEG1 audio compression.


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
     dmMPEG1AudioEncoderCreate(3dm), dmMPEG1AudioEncoderSetParams(3dm),
     dmMPEG1AudioEncoderGetParams(3dm), dmMPEG1AudioEncoderDestroy(3dm),
     dmMPEG1AudioDecode(3dm).