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. 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. 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 ALSO afOpenFile(3dm), afReadFrames(3dm), afWriteFrames(3dm), afGetVirtualSampleFormat(3dm), afGetVirtualChannels(3dm), afSetChannelMatrix(3dm), afGetVirtualByteOrder(3dm), afGetVirtualPCMMapping(3dm), afGetVirtualRate(3dm) Page 3