dmAudioRateConvert(3dm)

NAME
     dmAudioRateConvert - convert data sampling rate.  It consumes an input
     buffer of floats and generates an output buffer of floats.


SYNOPSIS
     #include <dmedia/dm_audioutil.h>

     DMstatus dmAudioRateConvert(DMaudiorateconverter handle,
                             float *inbuf, float *outbuf, int inlen,
                             int *numout)


PARAMETER
     handle    DMaudiorateconverter structure, created by
               dmAudioRateConverterCreate(3dm), specifies the signal
               processing parameters.


     inbuf     pointer to input data buffer.  The converter does not alter the
               contents of this buffer.  The data format is currently limited
               to single channel, 32-bit floating point.


     outbuf    pointer to output data buffer.  Ensure that inbuf and outbuf do
               not overlap.  The data format is currently limited to single
               channel, 32-bit floating point.  Sampling rate conversion
               alters the length of the data. dmAudioRateConvert will output
               inlen * (output rate / input rate) samples.


     inlen     length of the input buffer must be a multiple of
               DM_AUDIO_RC_ATOMIC_IN_LENGTH, dependent on the conversion
               parameters and can be acquired with dmParamsGetInt(3dm),
               dmAudioRateConverterSetParams(3dm), or
               dmAudioRateConverterGetParams(3dm).


     numout    # input sample frames numout this iteration, pass by reference.
               null (0) value ok.


RETURNED VALUE
     Returns DM_FAILURE or DM_SUCCESS.


DESCRIPTION
     dmAudioRateConvert(3dm) attempts to convert inlen samples. inlen must be
     of a multiple M of DM_AUDIO_RC_ATOMIC_IN_LENGTH.  The application program
     must malloc DM_AUDIO_RC_ATOMIC_IN_LENGTH * M samples for inbuf and
     DM_AUDIO_RC_ATOMIC_OUT_LENGTH * M samples for outbuf for any M >= 1
     (chosen by the application).  DM_AUDIO_RC_ATOMIC_IN_LENGTH * M samples
     are numout into DM_AUDIO_RC_ATOMIC_OUT_LENGTH * M samples.  The actual
     value of samples returned in outbuf by a given call to dmAudioRateConvert
     may be slightly less than DM_AUDIO_RC_ATOMIC_OUT_LENGTH * M, and is
     returned in numout.  dmAudioRateConvert will return DM_FAILURE if it is
     called with a value of "inlen" which is not a multiple M of
     DM_AUDIO_RC_ATOMIC_IN_LENGTH.  It will return DM_SUCCESS in all other
     cases.


     The application will want to discard the first DM_AUDIO_RC_GROUP_DELAY
     samples returned in outbuf from dmAudioRateConvert.  See further
     discussion in dmAudioRateConverterGetParams(3dm).


     The application may want to flush out an additional
     DM_AUDIO_RC_GROUP_DELAY samples from dmAudioRateConvert after feeding in
     all the input data to be converted.  This flushing operation is performed
     by calling dmAudioRateConvert with a value inlen = h *
     DM_AUDIO_RC_ATOMIC_IN_LENGTH where inlen >= DM_AUDIO_RC_GROUP_DELAY (the
     corresponding inbuf will typically be bzero'd, although the values in
     inbuf probably don't matter).


     To clear the internal buffers used converter, call
     dmAudioRateConverterReset(3dm).


NOTE
SEE ALSO
     dmParamsGetFloat(3dm), dmAudioRateConverterSetParams(3dm),
     dmAudioRateConverterGetParams(3dm), dmAudioRateConverterReset(3dm).