afInitPCMMapping(3dm)afInitPCMMapping(3dm)NAMEafInitPCMMapping - configure the PCM mapping for an audio track in an
AFfilesetup structure
SYNOPSIS
#include <dmedia/audiofile.h>
void afInitPCMMapping(AFfilesetup setup, int track,
double slope, double intercept,
double minclip, double maxclip)
PARAMETER
setup expects an AFfilesetup structure, previously created by a call to
afNewFileSetup(3dm).
track is an integer which identifies an audio track in setup.
Since all currently supported file formats contain one audio
track, the value AF_DEFAULT_TRACK should always be used here.
slope is a positive double-precision floating point value which
specifies an amplitude scaling factor for the waveform to be
associated with track.
intercept
is a positive, negative, or zero double-precision floating point
value which specifies the sample value which represents the
vertical midpoint ("zero crossing") of the waveform to be
associated with track.
minclip and maxclip
are double-precision floating point values which specify the
maximum desired negative and positive amplitudes for the waveform
associated with track. Any values encountered outside the range
[minclip, maxclip] will be clipped, i.e., set to these values.
DESCRIPTIONafInitPCMMapping() configures the PCM mapping for the specified audio
track in an AFfilesetup structure. setup is passed to afOpenFile(3dm)
when a new audio file is created. See afIntro(3dm) for a detailed
description of the PCM mapping technique.
EXAMPLE
To configure setup for a floating point waveform with a total expected
amplitude of 100.0 (i.e., values between -100.0 and 100.0) and a
symmetrical clipping to match, and a 0.0 zero crossing value, the track
would be initialized with the following:
afInitPCMMapping(setup, AF_DEFAULT_TRACK, 100.0, 0.0, -100.0, 100.0);
Page 1
afInitPCMMapping(3dm)afInitPCMMapping(3dm)CAVEATS
If this routine is used, it must be called after any calls to
afInitSampleFormat(). Setting the sample format automatically resets the
PCM mapping to the default values for the requested format. PCM mapping
is useful for modifying the values of frames as they are read into or
written out from a buffer via afReadFrames(3dm) or afWriteFrames(3dm).
None of the currently supported file formats have the capability to store
mapping information, even though the actual mapping can and will be
applied to the frames stored in those files. Therefor, it is important
to be careful what values you specify. 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.
SEE ALSOafOpenFile(3dm), afNewFileSetup(3dm), afReadFrames(3dm),
afWriteFrames(3dm), afSetTrackPCMMapping(3dm),
afSetVirtualPCMMapping(3dm), afGetVirtualPCMMapping(3dm)
Page 2
