afSetChannelMatrix(3dm)                                afSetChannelMatrix(3dm)


NAME
     afSetChannelMatrix - set the channel mix matrix associated with a given
     track in an AFfilehandle

SYNOPSIS
     #include <dmedia/audiofile.h>

     int afSetChannelMatrix(AFfilehandle file, int track, double* matrix)

PARAMETER
     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.

DESCRIPTION
     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
     afWriteFrames(3dm) instead of afReadFrames(3dm) because the virtual
     format becomes the input rather than the output of the process.

     A channel conversion operation will occur any time n != 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.


EXAMPLE
     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();


     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

CAVEATS
     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.

SEE ALSO
     afSetVirtualChannels(3dm), afGetVirtualChannels(3dm), afReadFrames(3dm),
     afWriteFrames(3dm)


                                                                        Page 3