afSetChannelMatrix(3dm) afSetChannelMatrix(3dm)
afSetChannelMatrix - set the channel mix matrix associated with a given
track in an AFfilehandle
#include <dmedia/audiofile.h>
int afSetChannelMatrix(AFfilehandle file, int track, double* matrix)
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 for now.
matrix is an array of double precision floating point values which
specify the manner in which a channel conversion operation
should take place. Because the values in this array will be
copied into internal memory, matrix may be either a locally
declared array or a dynamically allocated one, and in the latter
case may be freed immediately after the function call.
afSetChannelMatrix() allows an application to specify the exact file to
virtual mapping, i.e., how n audio file channels should be mapped into m
buffer channels. The matrix should be declared as a single-dimension
array, but should be laid out as if it were a two-dimensional array with
rows equal to virtual channels and columns equal to file channels. Note
that this means that for any given channel conversion, i.e., 2 -> 4, 4 ->
1, etc., the matrix must be swapped rows-for-columns if you call
afWriteFramesn != m. This will
happen during calls to afReadFrames(3dm) or afWriteFrames(3dm) when the
virtual channel count has been set to a different value than the track
channel count (they will always default to the same value). No matrix
operation will occur if n == m even if a matrix has been specified.
If no call to afSetChannelMatrix() is made, or if it is called with
matrix set to NULL, the AF will revert to a set of default matrices.
These were designed to match the default matrices used by the Audio
Library (see ALintro(3dm)).
afSetChannelMatrix() must be called after the call to
afSetVirtualChannels(3dm). Otherwise, a subsequent call to
afSetVirtualChannels will cause the matrix be reset to NULL.
Page 1
afSetChannelMatrix(3dm) afSetChannelMatrix(3dm)
To pan a monaural audio signal buffer to the center of a stereo output
file:
double matrix[] = { .71, .71 } /* "equal power" stereo */
int bufferChannels = 1; /* virtual (buffer) format */
AFfilesetup setup = afNewFileSetup();
AFfilehandle handle;
/* initialize file channel count to stereo */
afInitChannels(setup, AF_DEFAULT_TRACK, 2);
handle = afOpenFile("mysoundfile.aiff", "w", setup);
afSetVirtualChannels(handle, AF_DEFAULT_TRACK, bufferChannels);
afSetChannelMatrix(handle, AF_DEFAULT_TRACK, matrix);
/* note that
afWriteFrames(...);
To read a four-channel file into a stereo buffer with the front channels
mixed into the far left and right and the back channels mixed into the
near left and right:
double matrix[] = {
/* inputs */
/* FL FR BL BR */
/* outputs */
1.0, 0.0, 0.6, 0.4 /* L */
0.0, 1.0, 0.4, 0.6 /* R */
};
AFfilehandle handle;
int bufferChannels = 2; /* virtual (buffer) format */
/* open 4-channel sound file */
handle = afOpenFile("4channelsound.aiff", "r", NULL);
afSetVirtualChannels(handle, AF_DEFAULT_TRACK, bufferChannels);
afSetChannelMatrix(handle, AF_DEFAULT_TRACK, matrix);
afReadFrames(...);
To write a four-channel buffer into a stereo file with the same mixdown:
double matrix[] = {
/* outputs */
/* L R */
/* inputs */
1.0, 0.0, /* L */
0.0, 1.0, /* R */
0.6, 0.4 /* BL */
0.4, 0.6 /* BR */
};
int bufferChannels = 4; /* virtual (buffer) format */
AFfilesetup setup = afNewFileSetup();
Page 2
afSetChannelMatrix(3dm) afSetChannelMatrix(3dm)
AFfilehandle handle;
/* initialize file channel count to stereo */
afInitChannels(setup, AF_DEFAULT_TRACK, 2);
handle = afOpenFile("stereosound.aiff", "w", setup);
afSetVirtualChannels(handle, AF_DEFAULT_TRACK, bufferChannels);
afSetChannelMatrix(handle, AF_DEFAULT_TRACK, matrix);
afWriteFrames(...);
Note that the AF always assumes the 4-channel input has its channels laid
out:
Front
0 1
2 3
Back
The Audio File Library has no way to check the size of the double* array
passed in to afSetChannelMatrix(). Care must be taken to assure that the
array has (in_channels * out_channels) elements, regardless of how the
data in these channels is to be treated. Also note the above paragraph
concerning the calling order of this function.
afSetVirtualChannels(3dm), afGetVirtualChannels(3dm), afReadFrames(3dm),
afWriteFrames(3dm)
PPPPaaaaggggeeee 3333 [ Back ]
|
