dmACConvert(3dm)dmACConvert(3dm)NAMEdmACConvert - 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;
Page 1
dmACConvert(3dm)dmACConvert(3dm)dmACConvert(3dm) Performs format, sampling rate, and/or
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.
Page 2
dmACConvert(3dm)dmACConvert(3dm)SEE ALSOdmACCreate(3dm), dmACSetParams(3dm), dmACGetParams(3dm), dmACReset(3dm),
dmACDestroy(3dm)
Page 3
