dmDVIAudioEncode(3dm)

NAME
     dmDVIAudioEncode - compress audio data using the IMA (Interactive
     Multimedia Association) Recommended ADPCM compression, based on Intel's
     DVI algorithm.


SYNOPSIS
     #include <dmedia/dm_audioutil.h>

     DMstatus dmDVIAudioEncode(DMDVIaudioencoder handle,
                               short *ibuf, unsigned char *obuf,
                               int nsamples)


PARAMETER
     handle    DMDVIaudioencoder structure, created by a previous call to
               dmDVIAudioEncoderCreate(3dm).  It contains the state associated
               with the encoder.

     ibuf      pointer to input sample data buffer.  The data format is short
               (16-bit).  The samples are assumed to be two's complement.
               Sampling rate could range from 8 kHz to 48 kHz.


     obuf      pointer to output compressed data buffer. The data format is
               unsigned char (8-bit).


     nsamples  The number of samples to be processed.  For the 4:1 algorithm
               (the only one currently supported), the value of nsamples
               passed to the DVI encode/decode routines must always be a
               multiple of 2.


RETURNED VALUE
     Returns DM_FAILURE or DM_SUCCESS.


DESCRIPTION
     dmDVIAudioEncode(3dm) implements Intel, Inc.'s DVI IMA4:1 ADPCM
     compression for monaural audio data.

     DVI IMA ADPCM compression exists in two forms, 4 bits per sample (IMA4:1)
     and 3 bits per sample (IMA3:1).  The compression form may be retrieved
     using dmDVIAudioDecoderGetParams(3dm) via the parameter
     DM_DVI_AUDIO_BITS_PER_SAMPLE.  Its possible values are:

     DM_DVI_AUDIO_4BITS_PER_SAMPLE
          4:1 compression.  This is the only form currently supported by the
          SGI Digital Media libraries.
     DM_DVI_AUDIO_3BITS_PER_SAMPLE
          3:1 compression.  Currently not supported.

DVI AUDIO FILE BLOCK MODE
     DVI audio compression uses a linear prediction scheme.  This means that
     the compressed bits are interrelated or interdependent.  If a application
     seeks to an offset into the compressed bit stream file and then starts
     reading at that point in the stream and decompresses it via
     dmDVIAudioDecode(3dm), the interdependency of the bits at the start point
     is lost.  The application will initially get back data with a lower
     amplitude than if he had read the same data back during a complete pass
     over the file from the beginning.

     In pure DVI ADPCM data, there is no way to accurately begin decoding data
     in the middle of the bit stream file without starting the beginning.  Two
     solutions to this problem have been developed, one by Intel, Inc. and one
     by Apple, Inc.  Both involve breaking the compressed data up into blocks,
     each with a small header encapsulating the information needed to allow
     decoding to begin at any block boundry with no loss of data. WAVE(4) and
     AIFF-C format sound files using IMA DVI compression take advantage of
     this block method if you create them using the Audio File Library.  In
     addition, a block method compressed stream may be created using
     dmACConvert(3dm) if it is configured properly.

CONFIGURING DMAC FOR BLOCK MODE
     Three parameters are needed to configure the DMaudioconverter to allow
     creation of these block streams:

     DM_AUDIO_CODEC_MAX_BYTES_PER_BLOCK
          Indicates the number of bytes of compressed data per block,
          including the header.  Indicates the number of bytes of compressed
          data per block, including the header.  For AIFF-C(4) files, this
          value is always 34 * channel_count.  For WAVE(4) files, this value
          varies.

     DM_AUDIO_CODEC_FRAMES_PER_BLOCK
          Indicates the number of frames of uncompressed data contained in
          each block.  Indicates the number of frames of uncompressed data
          contained in each block.  For AIFF-C(4) files, this value is always
          64.  For WAVE(4) files, this value varies.

     DM_DVI_AUDIO_BLOCK_TYPE
          This DVI-specific parameter specifies whether the data will be
          compressed using the Intel scheme, the Apple scheme, or no blocking
          at all (i.e., "pure" DVI).  Its possible values are:

          DM_DVI_AUDIO_BLOCK_TYPE_NONE -- For stream use only.
          DM_DVI_AUDIO_BLOCK_TYPE_APPLE -- For AIFF-C files.
          DM_DVI_AUDIO_BLOCK_TYPE_INTEL -- For WAVE files.

IMPORTANT NOTE
     Stereo audio streams and streams with block data cannot be created using
     dmDVIAudioEncode() directly -- you must use dmACConvert(3dm).  It is
     highly recommended that the Audio File Library be used for all to- and
     from-disk compression and decompression.

SEE ALSO
     dmDVIAudioEncoderCreate(3dm), dmDVIAudioEncoderSetParams(3dm),
     dmDVIAudioEncoderDestroy(3dm), dmDVIAudioEncode(3dm), dnACConvert(3dm),
     afWriteFrames(3dm), IMA Recommended Practices for Enhancing Digital Audio
     Compatibility in Multimedia Systems, rev 3.00.