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.
Page 1
afGetSampleFormat(3dm)afGetSampleFormat(3dm)RETURN VALUEafGetByteOrder() 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.
DESCRIPTIONafGetSampleFormat() 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 ALSOafOpenFile(3dm), afReadFrames(3dm), afWriteFrames(3dm),
afInitSampleFormat(3dm), afSetVirtualSampleFormat(3dm)
Page 2
