dmDVIAudioDecode(3dm)					 dmDVIAudioDecode(3dm)

NAME    [Toc]    [Back]

     dmDVIAudioDecode -	decode audio data compressed using the IMA
     (Interactive Multimedia Association) Recommended ADPCM decompression,
     based on Intel's DVI algorithm.

SYNOPSIS    [Toc]    [Back]

     #include <dmedia/dm_audioutil.h>

     DMstatus dmDVIAudioDecode(DMDVIaudiodecoder handle,
			       unsigned	char *ibuf, short *obuf,
			       int nsamples)

PARAMETER    [Toc]    [Back]

     handle    DMDVIaudiodecoder structure, created by a previous call to
	       dmDVIAudioDecoderCreate(3dm).  It contains the state associated
	       with the	decoder.


     ibuf      A pointer to the	compressed input data buffer. The data format
	       is unsigned char	(8-bit).


     obuf      A pointer to the	output sample data buffer.  The	data format is
	       short (16-bit).	The samples are	assumed	to be two's
	       complement.  Sampling rate may range from 8 kHz to 48 kHz, but
	       has to be the same as encoder.


     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    [Toc]    [Back]

     Returns DM_FAILURE	or DM_SUCCESS.

DESCRIPTION    [Toc]    [Back]

     dmDVIAudioDecode(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    [Toc]    [Back]
	  4:1 compression.  This is the	only form currently supported by the
	  SGI Digital Media libraries.



									Page 1






dmDVIAudioDecode(3dm)					 dmDVIAudioDecode(3dm)



     DM_DVI_AUDIO_3BITS_PER_SAMPLE    [Toc]    [Back]
	  3:1 compression.  Currently not supported.

DVI AUDIO FILE BLOCK MODE    [Toc]    [Back]

     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(4) format sound files using	IMA DVI	compression take advantage of
     this block	method,	and if such a file is read using the Audio File
     Library, accurate file seeks are possible.

     The data contained	in one of these	files may also be decoded accurately
     using dmACConvert(3dm) if it is configured	properly.

CONFIGURING DMAC TO PARSE IN BLOCK MODE    [Toc]    [Back]

     Three parameters are needed to configure the DMaudioconverter to allow
     parsing of	these block streams:

     DM_AUDIO_CODEC_MAX_BYTES_PER_BLOCK    [Toc]    [Back]
	  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.  If
	  afOpenFile(3dm) is used to open a WAVE(4) file, the value of this
	  parameter can	be retrieved directly using afGetFormatParams(3dm).

     DM_AUDIO_CODEC_FRAMES_PER_BLOCK    [Toc]    [Back]
	  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.  If	afOpenFile(3dm)	is used	to
	  open a WAVE(4) file, the value of this parameter can be retrieved
	  directly using afGetFormatParams(3dm).

     DM_DVI_AUDIO_BLOCK_TYPE    [Toc]    [Back]
	  This DVI-specific parameter specifies	whether	the data is 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.



									Page 2






dmDVIAudioDecode(3dm)					 dmDVIAudioDecode(3dm)

IMPORTANT NOTE    [Toc]    [Back]

     Stereo audio streams and streams with block data cannot be	parsed using
     dmDVIAudioDecode()	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    [Toc]    [Back]

     dmDVIAudioDecoderCreate(3dm), dmDVIAudioDecoderSetParams(3dm),
     dmDVIAudioDecoderDestroy(3dm), dmDVIAudioEncode(3dm),  afReadFrames(3dm),
     IMA Recommended Practices for Enhancing Digital Audio Compatibility in
     Multimedia	Systems, rev 3.00.


									PPPPaaaaggggeeee 3333