afInitLoopIDs(3dm)                                          afInitLoopIDs(3dm)


NAME
     afInitLoopIDs - initialize a list of loop ID's for a given instrument in
     an AFfilesetup structure

SYNOPSIS
     #include <dmedia/audiofile.h>

     void afInitLoopIDs(AFfilesetup setup, int inst, int loopids[],
                                      int nloops)

PARAMETER
     setup   expects an AFfilesetup structure, previously created by a call to
             afNewFileSetup(3dm).

     inst    is an integer which identifies an instrument configuration to be
             included in a new file when the file is created.

             Of the currently supported audio file formats, only AIFF-C (AIFF)
             files contain instrument configurations, with a maximum of one
             per file.  For this reason, the value AF_DEFAULT_INST should
             always be used for this argument for now.

     loopids is an array of unique positive integer values to be used
             subsequently for configuring individual loops in a file opened
             for write access with setup.

             Since the instrument parameter chunk in an AIFF-C (AIFF) file
             allocates space for exactly two loops (a release loop and a
             sustain loop), the current version of the audio library will
             ignore any ID's after the first two in the list.

     nloops  is an integer which indicates the number of loop ID's in the
             loopids array.

             For AIFF-C (AIFF) files, nloops is ignored since the number of
             loops in the instrument configuration is always 2.

DESCRIPTION
     to the loops supplied for the specified instrument in an audio file.

     AIFF-C (AIFF) files contain storage space for two loops in the instrument
     configuration:  a "sustain" loop and a "release" loop.  You use the loop
     ID's as arguments to the library routines which allow you to set the play
     modes and beginning and end point markers for the loops.

     You can disable the loops by setting their loop modes to
     AF_LOOP_MODE_NOLOOP.


EXAMPLE
     Configure an AIFF-C file so that it will contain storage space for
     sustain and release loops.

     First call afInitInstIDs(3dm) to specify that the file should contain one
     instrument configuration (with ID AF_DEFAULT_INST).

     Next call afInitLoopIDs() with nloops set to 2 and loopids set to {1,2}
     (these values are arbitrary).

     Reserve four marker locations (two endpoints for each loop) by calling
     afInitMarkIDs(3dm) with the marker ID list set to {1,2,3,4} (these values
     are arbitrary).

     After you create an audio file using the AFfilesetup structure which
     contains the loop ID's, you set the endpoint markers and play modes for
     the loops individually using afSetLoopStart(3dm), afSetLoopEnd(3dm), and
     afSetLoopMode(3dm).

     You store the sample frame locations for the endpoints of the loops into
     the markers by calling afSetMarkPosition(3dm).

     You use the routine afSetInstParamLong(3dm) to map the loop ID's {1, 2}
     to "sustain" and "release" (in any order).

CAVEATS
     The Audio File Library will continue to expand the number of supported
     file formats.  The ability of these file formats to store various kinds
     and numbers of loops will vary.  See afGetLoopIDs(3dm) for some important
     notes about handling this situation.

SEE ALSO
     afNewFileSetup(3dm), afOpenFile(3dm), afInitMarkIDs(3dm),
     afInitInstIDs(3dm), afSetLoopStart(3dm), afSetInstParamLong(3dm),
     afSetMarkPosition(3dm)


                                                                        Page 2