afSetVirtualSampleFormat(3dm)afSetVirtualSampleFormat(3dm)NAME
afSetVirtualSampleFormat, afSetVirtualByteOrder, afSetVirtualChannels,
afSetVirtualRate, afSetVirtualPCMMapping - set the virtual data format
for a specified audio track
SYNOPSIS
#include <dmedia/audiofile.h>
int afSetVirtualSampleFormat(AFfilehandle file, int track,
int sampfmt, int sampwidth)
int afSetVirtualByteOrder(AFfilehandle file, int track, int byteorder)
int afSetVirtualChannels(AFfilehandle file, int track, int channels)
int afSetVirtualRate(AFfilehandle file, int track, double rate)
int afSetVirtualPCMMapping(AFfilehandle file, int track,
double slope, double intercept,
double minclip, double maxclip)
PARAMETER
Parameters for the virtual routines are identical to those for the
equivalent afInit routines, except the first argument is an AFfilehandle
structure rather than an AFfilesetup.
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 handle.
Since all currently supported file formats contain only one
audio track, the value AF_DEFAULT_TRACK should always be used
here.
sampfmt an integer constant which denotes a virtual sample format.
sampwidth a positive integer value which specifies the number of bits
in a virtual sample data point.
channels is a positive integer value which indicates the number of
interleaved audio channels in the audio track.
byteorder is a positive integer token which indicates the byte order of
the samples in the audio track.
rate is a double precision floating point value indicating the
sampling rate for the virtual audio data.
Page 1
afSetVirtualSampleFormat(3dm)afSetVirtualSampleFormat(3dm)
slope is a double precision floating point value
intercept is a double precision floating point value indicating the
audio data sample zero-crossing value for the given sample
format and width
minclip is a double precision floating point value indicating the
minimum or most negative audio data sample value to be
returned. Any value less than this will be set to minclip
maxclip is a double precision floating point value indicating the
maximum or most positive audio data sample value to be
returned. Any value greater than this will be set to maxclip
DESCRIPTION
When a audio data is read from a file into the application's data buffer
using afReadFrames(3dm), the format of the data loaded into the 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 of the file format into the virtual format happens
automatically and transparently. This allows an application to choose to
ignore the data format in the file 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.
afSetVirtualSampleFormat() sets the virtual sample format and width
parameters for the audio data buffer.
The following values may be used for sampfmt
AF_SAMPFMT_TWOSCOMP Two's complement samples.
AF_SAMPFMT_UNSIGNED Unsigned samples.
AF_SAMPFMT_FLOAT 32-bit floating point samples.
AF_SAMPFMT_DOUBLE 64-bit double-precision floating point samples.
afSetVirtualByteOrder() sets the virtual byte order (big- or little-
endian) of the samples in the audio buffer.
The following values may be used for byteorder
AF_BYTEORDER_BIGENDIAN Big-endian byte order samples. This is the
default value.
AF_BYTEORDER_LITTLEENDIAN Little-endian byte order samples.
afSetVirtualChannels() sets the number of virtual interleaved channels in
the audio buffer. If the virtual channel count does not equal the track
channel count, channel conversion is performed via a channel mix matrix.
Page 2
afSetVirtualSampleFormat(3dm)afSetVirtualSampleFormat(3dm)
If this matrix is not specified, a default matrix will be used. This
default matrix follows the same channel conversion rules as the Audio
Library (libaudio). See afSetChannelMatrix(3dm) for details.
afSetVirtualRate() sets the virtual sampling rate for the audio buffer.
If the track sampling rate is different, the data will be rate-converted
using one of several conversion algorithms. See
afSetConversionParams(3dm) for more information.
afSetVirtualPCMMapping() sets the virtual PCM mapping values for the
audio buffer. The range, zero-crossing, and clipping values for the data
placed in the audio buffer will be determined via a transformation
calculated from the relationship between the file's PCM mapping and the
requested mapping. In general, all two's complement and floating point
sample formats are expected to be symmetrical about zero, i.e., the
intercept will be 0.0 and minclip and maxclip will be negative and
positive N, where N is some non-zero positive value. If this routine is
used, it must be called after any calls to afSetVirtualSampleFormat().
Resetting the virtual sample format automatically resets the PCM mapping
to the default values for the requested format.
SEE ALSOafOpenFile(3dm), afReadFrames(3dm), afWriteFrames(3dm),
afGetVirtualSampleFormat(3dm), afGetVirtualChannels(3dm),
afSetChannelMatrix(3dm), afGetVirtualByteOrder(3dm),
afGetVirtualPCMMapping(3dm), afGetVirtualRate(3dm)
Page 3
