afGetSampleFormat(3dm)                                  afGetSampleFormat(3dm)


NAME
     afGetSampleFormat, AFgetsampfmt, afGetVirtualSampleFormat,
     afGetByteOrder, afGetVirtualByteOrder - get the track / virtual sample
     format or byte order for a specified audio track from an AFfilehandle
     structure.

SYNOPSIS
     #include <dmedia/audiofile.h>

     void afGetSampleFormat(AFfilehandle file, int track,
                            int *sampfmt, int *sampwidth)

     void afGetVirtualSampleFormat(AFfilehandle file, int track,
                                   int *sampfmt, int *sampwidth)

     int afGetByteOrder(AFfilehandle file, int track)

     int afGetVirtualByteOrder(AFfilehandle file, int track)

PARAMETERS
     file        expects an AFfilehandle structure, previously created when an
                 audio file was opened by a call to afOpenFile(3dm) or
                 afOpenFD(3dm).

     track       expects an integer which identifies the audio track in the
                 file.  Since all file formats currently supported by the
                 audio file library allow at most one audio track per file,
                 the value AF_DEFAULT_TRACK should always be used for this
                 argument.

     sampfmt     is a pointer to an integer location.  The routine uses this
                 location to return a symbolic integer constant denoting the
                 format of the sample data.

                 For AIFF-C (AIFF) files, this value is always
                 AF_SAMPFMT_TWOSCOMP, linear two's complement PCM.  Other
                 currently supported file types support AF_SAMPFMT_UNSIGNED
                 (unsigned), AF_SAMPFMT_FLOAT (32-bit floating point) or
                 AF_SAMPFMT_DOUBLE (64-bit double-precision floating point)
                 formats.

     sampwidth   is a pointer to an integer location.  The routine returns a
                 nonnegative integer value here which gives the sample width
                 for the audio track in bits.

                 For AIFF-C (AIFF) files, this value is greater than 0 and
                 less than or equal to 32.  This parameter may or may not be
                 meaningful depending on the value of sampfmt.  For
                 AF_SAMPFMT_TWOSCOMP it is the number of bits per sample in
                 the 2's complement signed integer.  See the CAVEATS section
                 below for more details.


RETURN VALUE
     afGetByteOrder() and afGetVirtualByteOrder() return an integer token
     representing the byte order of the samples.  This value will be either
     AF_BYTEORDER_BIGENDIAN or AF_BYTEORDER_LITTLEENDIAN.

DESCRIPTION
     afGetSampleFormat() and afGetVirtualSampleFormat() return the sample
     format and sample width (in bits) for the audio file's track and the
     audio buffer, respectively, using the integer pointer arguments.  See
     afIntro(3dm) for an explanation of virtual format.

     An AIFF-C file which contains 16 bit sample data would return the value
     AF_SAMPFMT_TWOSCOMP in the location sampfmt, and the value 16 in the
     location sampwidth.

     You can use the sample width value to determine the data type used to
     pass samples to afWriteFrames(3dm), or to obtain samples from
     afReadFrames(3dm).

     1-8 bit samples are packed into signed chars, 9-16 bit samples are packed
     into shorts, and 17-32 bit samples are packed into integers or floats,
     depending on the sampfmt, and 64-bit samples are stored into doubles.

     SGI has proposed an extension to the AIFF-C format which will allow files
     to store linear PCM samples as scaled IEEE floats or doubles in addition
     to two's complement integers.

EXAMPLE
     If afGetSampleFormat() returns the value 8 in sampwidth, and
     AF_SAMPFMT_UNSIGNED in sampfmt, allocate an unsigned char buffer for
     reading samples from a file via afReadFrames(3dm).

     If afGetSampleFormat() returns the value 13 in sampwidth and
     AF_SAMPFMT_TWOSCOMP in sampfmt, allocate a (signed) short buffer for
     reading samples from the file.

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 a sampfmt value not found in <audiofile.h> at the time of
     programming.  Programs should be written to at least reject files with
     sample formats they are not written to handle.

SEE ALSO
     afOpenFile(3dm), afReadFrames(3dm), afWriteFrames(3dm),
     afInitSampleFormat(3dm), afSetVirtualSampleFormat(3dm)


                                                                        Page 2