afSetVirtualFormatParams(3dm)                    afSetVirtualFormatParams(3dm)


NAME
     afSetVirtualFormatParams, afGetVirtualFormatParams - set/get the virtual
     audio data format in an AFfilehandle for a specified audio track via
     dmParams

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

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

     DMstatus afGetVirtualFormatParams(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
     afSetVirtualFormatParams() and afGetVirtualFormatParams() return
     DM_SUCCESS on success, otherwise they return DM_FAILURE.

DESCRIPTION
     When a audio data is read from a file into the application's data buffer
     using afReadFrames(3dm), or written into a file via afWriteFrames(3dm),
     the format of the data in the application's buffer can vary independently
     of the actual file data format.  This independent format is call the
     virtual format of the data.  Once some aspect of the virtual data format
     is set via one of the above-described routines, the conversion to and
     from the file format into the virtual format happens automatically and
     transparently.  This allows an application to choose to ignore the actual
     file format entirely, and specify only the format in which it wants the
     data to appear in the afReadFrames(3dm) buffer.  See afIntro(3dm) for
     more information about the virtual format.

     afSetVirtualFormatParams() sets all virtual parameters associated with
     the audio data in an AFfilehandle structure for an audio track.  It
     obsoletes the individual routines afSetVirtualSampleFormat(3dm),
     afSetVirtualChannels(3dm), afSetVirtualRate(3dm), and
     afSetVirtualPCMMapping(3dm).


     afGetVirtualFormatParams() allows an application to retrieve the complete
     set of virtual params currently contained within an AFfilehandle
     structure for a given track.

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

     DM_AUDIO_FORMAT       Sample format.  Must be DM_AUDIO_TWOS_COMPEMENT,
                           DM_AUDIO_UNSIGNED, DM_AUDIO_FLOAT, or
                           DM_AUDIO_DOUBLE.

     DM_AUDIO_WIDTH        Sample width in bits.  For integer sample formats,
                           it must be an integer value between 1 and 32,
                           inclusive.  For formats DM_AUDIO_FLOAT and
                           DM_AUDIO_DOUBLE, this parameter is ignored.

     DM_AUDIO_CHANNELS     Channel count.  Integer value greater than or equal
                           to 1.

     DM_AUDIO_RATE         Sampling rate.  Must be a positive, double
                           precision floating point value.

     DM_AUDIO_COMPRESSION  Compression type.  Must be left unset or set to
                           DM_AUDIO_UNCOMPRESSED, since all data returned via
                           afReadFrames(3dm) or handed to afWriteFrames(3dm)
                           must be uncompressed.

     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).

CAVEATS
     The Audio File Library will continue to support additional file formats.
     The ability of these file formats to store data of various sample formats
     will vary.  If you are choosing a file format other than the default
     format, you should make sure that you either explicitly specify format
     params for this file's tracks which are compatible with that file format,
     or do not set them at all (in which case they will be set to default
     values for the format).

SEE ALSO
     afNewFileSetup(3dm), afOpenFile(3dm), afWriteFrames(3dm),
     afInitFormatParams(3dm), afSetConversionParams(3dm)


                                                                        Page 2