dmACConvert(3dm)                                              dmACConvert(3dm)


NAME
     dmACConvert - convert audio data format, sampling rate and compression

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

     DMstatus dmACConvert(
                  DMaudioconverter converter,
                  void *inbuffer,
                  void *outbuffer,
                  int *in_amount,
                  int *out_amount)

PARAMETERS
     converter    is a DMaudioconverter handle created by a previous call to
                  the creation method dmACCreate(3dm).

     inbuffer     is a pointer to the buffer containing the audio data to be
                  converted. Its length may need to be determined via the
                  DM_AUDIO_MIN_INPUT_LEN parameter described below.  If
                  inbuffer is NULL, the converter will flush its internal
                  buffers (if any) to the output buffer.

     outbuffer    is a pointer to the buffer where the converter will place
                  the converted data. Its length may need to be determined via
                  the DM_AUDIO_MIN_OUTPUT_LEN parameter described below.

     in_amount    is a pointer to an integer containing the number of frames
                  of data being handed to the converter.  dmACConvert will
                  reset this to the number of frames used (i.e., taken from
                  inbuffer) by the converter.

     out_amount   is a pointer to an integer containing the number of frames
                  requested from the converter.  The initial value will be
                  ignored in push mode;  the output buffer must always be
                  large enough to hold the output as specified by
                  DM_AUDIO_MIN_OUTPUT_LEN.  dmACConvert will reset out_amount
                  to the number of frames processed (i.e., placed into
                  outbuffer) by this call.  This number can vary significantly
                  from in_amount if rate conversion or
                  compression/decompression is being applied to the data. It
                  can even be zero despite a positive value of in_amount.

RETURNED VALUE
     Returns DM_SUCCESS if the operation succeeds.  If DM_FAILURE is returned,
     the error number and/or message can be retrieved via dmGetError(3dm).

DESCRIPTION
     The handle passed to this routine is declared as follows:

     typedef struct _DMaudioconverter *DMaudioconverter;


     compression/decompression upon the audio data in inbuffer, based on the
     difference between the parameters specified for the input and the output
     via dmACSetParams(3dm). The conversion process itself may be modified by
     any applicable parameters present in the conversion parameters given in
     that same call.

     The converter operates in two distinct modes, depending on the conversion
     operation specified.  If the input data is being decompressed into the
     output, it operates in "pull" mode, meaning that the user specifies how
     many frames of uncompressed data should be placed in the output buffer.
     The amount taken from the input buffer will be reported in in_amount and
     the amount placed in the output buffer will be reported in out_amount.

                                   Pull Mode

     1) User indicates amount available.           User requests this.

     2) in_amount ------------> dmACConvert() ---> out_amount

     3) Set to amount used.                        Set to amount processed.

     If the input data is being compressed into the output, or if no
     compression or decompression is being applied, the converter operates in
     "push" mode, meaning that the user specifies in in_amount how many frames
     of uncompressed data is available in the input buffer. The amount placed
     in the output buffer will be reported in out_amount.  If no compression
     or decompression is being performed, out_amount is guaranteed to equal
     in_amount.

                                   Push Mode

     1) User requests this.                    This value ignored.

     2) in_amount --------> dmACConvert() ---> out_amount

     3) Set to amount used.                    Set to amount processed.

     In cases where compression, decompression, or rate conversion is being
     performed, the parameter DM_AUDIO_MAX_REQUEST_LEN must be passed to the
     converter via dmACSetParams(3dm) prior to the first call to dmACConvert,
     informing the converter of the largest input or output request that will
     be made of it.  Then dmACGetParams(3dm) must be called, and, depending on
     the value of the returned parameter DM_AUDIO_PROCESS_MODE, the parameter
     indicating the minimum length needed for the input
     (DM_AUDIO_MIN_INPUT_LEN) or output (DM_AUDIO_MIN_OUTPUT_LEN) buffer must
     be retrieved and used to allocate the appropriate buffer.

     These parameters only need be set and queried if the audio data is being
     compressed, decompressed, or rate-converted. In all other cases, the
     output buffer length in frames will and must equal the input length.


SEE ALSO
     dmACCreate(3dm), dmACSetParams(3dm), dmACGetParams(3dm), dmACReset(3dm),
     dmACDestroy(3dm)


                                                                        Page 3