afGetLoopIDs(3dm)                                            afGetLoopIDs(3dm)


NAME
     afGetLoopIDs - get a number and list of loop ID's for an instrument
     configuration

SYNOPSIS
     #include <dmedia/audiofile.h>

     int afGetLoopIDs(AFfilehandle file, int instid, int loopids[])

PARAMETER
     file      expects an AFfilehandle structure, created when an audio file
               is opened by a call to afOpenFile(3dm) or its equivalent.

     instid    is an integer which identifies a chunk of instrument parameters
               contained in file.  Since the number of supported inst chunks
               varies with file format, applications should always retrieve
               this value via afGetInstIDs(3dm).

     loopids   is an array of integer locations used to return a list of
               (unique) positive loop id's for the given instrument chunk.  If
               loopids is a null pointer, afGetLoopIDs() simply returns the
               number of loops for the given instrument.

RETURN VALUE
     afGetLoopIDs() returns a nonnegative integer count of the number of loop
     structures in the specified instrument chunk.  You use this value to
     determine the size of an array which you pass back to afGetLoopIDs().

     For AIFF-C (and AIFF) files, the number of loop structures in the
     AF_DEFAULT_INST chunk is always 2: a sustain loop and a release loop.
     For other file formats, this number may vary from 0 to an unlimited
     quantity.

DESCRIPTION
     afGetLoopIDs() reports the number of loops for instid, and supplies a
     list of unique positive id's for the loops in loopids[].

     Typically, you call afGetLoopIDs() twice.  The first time, you pass it a
     null loopids pointer and just check the return value.  This value tells
     you how many locations to allocate in the loopids[] array, which you pass
     back to afGetLoopIDs() to obtain a list of loop ID's.

     You can then use these id's to reference the individual loops and obtain
     information about them such as play mode, start and end points (see
     afGetLoopStart(3dm)), and for some formats, the loop count (see
     afGetLoopCount(3dm)).

NOTE
     For AIFF-C (and AIFF), you can obtain loop ID's for the sustain and
     release loops in the instrument map directly by calling
     afGetInstParamLong(3dm) with the parameters AF_INST_SUSLOOPID and
     AF_INST_RELLOOPID.


CAVEATS
     These functions may return any number of loops within an inst, not just
     the fixed value of 2 current found in AIFF/AIFF-C files.  Other supported
     file formats have different loop configurations than those in AIFF/AIFF-
     C.  Applications may use the afQuery(3dm) system to determine whether a
     format supports loops and if so, the number allowed.  A program should be
     written to expect and ignore loop configurations it does not understand.

SEE ALSO
     afOpenFile(3dm), afInitLoopIDs(3dm), afGetInstParamLong(3dm),
     afGetLoopStart(3dm)


                                                                        Page 2