afGetFormatParams(3dm)                                  afGetFormatParams(3dm)


NAME
     afGetFormatParams - get the audio data format in an AFfilehandle for a
     specified audio track via dmParams

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

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

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

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

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

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

DESCRIPTION
     afGetFormatParams() retrieves all parameters associated with the audio
     data in an AFfilehandle structure for an audio track.  It obsoletes the
     individual routines afGetSampleFormat(3dm), afGetChannels(3dm),
     afGetRate(3dm), afGetCompression(3dm), and afGetCompressionParams(3dm).

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

     DM_AUDIO_FORMAT       Sample format.  Will be DM_AUDIO_TWOS_COMPLEMENT,
                           DM_AUDIO_UNSIGNED, DM_AUDIO_FLOAT, or
                           DM_AUDIO_DOUBLE.

     DM_AUDIO_WIDTH        Sample width in bits.  For integer sample formats,
                           it will be an integer value between 1 and 32.  For
                           format DM_AUDIO_FLOAT it will be 32, and for
                           DM_AUDIO_DOUBLE it will be 64.

     DM_AUDIO_CHANNELS     Channel count.

     DM_AUDIO_RATE         Sampling rate.

     DM_AUDIO_COMPRESSION  Compression type.  Will be DM_AUDIO_UNCOMPRESSED or
                           one of the supported compression parameter values.
                           In addition, any parameters associated with the
                           compression, such as DM_AUDIO_BITRATE, will also be
                           retrievable here (see afGetCompression(3dm) and
                           afGetCompressionParams(3dm)).


     DM_AUDIO_PCM_MAP_SLOPE

     DM_AUDIO_PCM_MAP_INTERCEPT

     DM_AUDIO_PCM_MAP_MAXCLIP

     DM_AUDIO_PCM_MAP_MINCLIP
                           Slope, intercept, minimum and maximum clipping
                           values for PCM mapping (see
                           afGetVirtualPCMMapping(3dm) for a detailed
                           explanation).

     When a file is opened for reading via a call to afOpenFile(3dm), the
     track will contain a full description of the audio data format, including
     data type, sample width, number of channels, sample rate, compression and
     any associated parameters, and PCM mapping information.

CAVEATS
     Note that this library will continue to support new file formats and thus
     other data formats than the ones described above.  Since the Audio File
     Library is a Dynamic Shared Object (DSO), it is possible for this call to
     return parameter values not found in <dmedia/dm_audio.h> at the time of
     programming.  Programs should be written to at least reject files with
     formats they are not written to handle.

SEE ALSO
     afOpenFile(3dm), afReadFrames(3dm), afWriteFrames(3dm),
     afInitFormatParams(3dm), afSetVirtualFormatParams(3dm),
     afGetConversionParams(3dm)


                                                                        Page 2