afSetConversionParams(3dm)                          afSetConversionParams(3dm)


NAME
     afSetConversionParams, afGetConversionParams - set/get the parameters
     associated with format conversion for a specified audio track via
     dmParams

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

     DMstatus afSetConversionParams(AFfilehandle file, int track,
                                       DMparams *params)

     DMstatus afGetConversionParams(AFfilehandle file, int track,
                                       DMparams *params)

PARAMETER
     file     is an AFfilehandle structure, previously created by a call to
              afOpenFile(3dm) or its equivalent.

     track    is an integer which identifies an audio track in file.

              Since all currently supported file formats contain only one
              audio track, the value AF_DEFAULT_TRACK should be used here for
              now.

     params   a DMparams list, previously created by a call to
              dmParamsCreate(3dm).

RETURN VALUE
     afSetConversionParams() and afGetConversionParams() return DM_SUCCESS on
     success, otherwise they return DM_FAILURE.

DESCRIPTION
     When some type of format conversion takes place during afReadFrames() or
     afWriteFrames() due to a difference between the track and the virtual
     format, the precise mechanism for this conversion may be controlled via a
     set of parameters.

     afSetConversionParams() sets all parameters associated with the
     conversion of audio data to or from an audio track from or to an audio
     buffer.

     afGetConversionParams() allows an application to retrieve the complete
     set of conversion parameters currently contained within an AFfilehandle
     structure for a given audio track.

     The following parameters are defined in dmedia/dm_audio.h and may be set
     or retrieved via params:

     DM_AUDIO_RC_ALGORITHM
             The converson algorithm to be used if rate conversion is being
             performed.  Its possible values are:


     DM_AUDIO_RC_JITTER_FREE   Jitter-Free is the highest quality rate
                               conversion available, and is the default for
                               all sampling rate ratios which it can support.
                               This includes all standard rate conversions
                               (i.e., 44.1k to 8k, 48k to 22.05k, etc.).

     DM_AUDIO_RC_POLYNOMIAL_ORDER_3
                               A third-order polynomial interpolating
                               algorithm.  It is the default for all sampling
                               rate ratios not covered by Jitter-Free.

     DM_AUDIO_RC_POLYNOMIAL_ORDER_1
                               A simple linear-interpolating algorithm.  This
                               is the least CPU-intensive, but also generated
                               the most distortion.

     DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION
             The parameter is specific to the jitter free rate converter
             algorithm.  The values correspond to the minimum attenuation
             level of the out-of-band frequencies, those frequencies which do
             not fit in the smaller of the output or input bandwidths.  Higher
             values correspond to better noise suppression.  Supported values
             are:

                 DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_78_DB (default)
                 DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_96_DB
                 DM_AUDIO_RC_JITTER_FREE_STOPBAND_ATTENUATION_120_DB

     DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH
             This parameter is specific to the jitter free rate converter
             algorithm.  The values correspond to the percent of the high
             frequency response of the output signal lost in the conversion
             process.  Lower percentages correspond to better high frequency
             response.  Supported values are:

                 DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_1_PERCENT
                 DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_10_PERCENT
                 DM_AUDIO_RC_JITTER_FREE_TRANSITION_BANDWIDTH_20_PERCENT (default)

     DM_AUDIO_DITHER_ALGORITHM
             When performing conversions from larger into smaller data types
             (i.e., floating point to 16-bit integer or 16-bit integer to 8-
             bit integer), a dithering algorithm may be applied to reduce the
             quantization error distortion inherant in such conversions.  This
             parameter is ignored if such a conversion is not happening.
             Supported values are:

                 DM_AUDIO_DITHER_NONE (default)
                 DM_AUDIO_DITHER_LSB_TPDF (LSB TPDF dither)


     DM_AUDIO_CHANNEL_MATRIX
             Allows specification of input to output channel routing via a
             matrix of values.

             This is a type DMfloatarray which must be set and retrieved via
             dmParamsSetFloatArray(3dm) and dmParamsGetFloatArray(3dm),
             respectively.  The data itself is a one-dimensional array of
             double-precision floating point numbers arranged as if it were an
             n x m matrix of values, where rows == output_channels and columns
             == input_channels. See the afSetChannelMatrix(3dm) manual page
             for a detailed explanation of this.

SEE ALSO
     afWriteFrames(3dm), afInitFormatParams(3dm),
     afSetVirtualFormatParams(3dm), dmACSetParams(3dm)


                                                                        Page 3