afGetLoopStart(3dm)                                        afGetLoopStart(3dm)


NAME
     afGetLoopStart, afGetLoopEnd, afGetLoopTrack, afGetLoopMode - get the
     start/end markers, play mode, and track from an AFfilehandle structure
     for a specified loop.

SYNOPSIS
     #include <dmedia/audiofile.h>

     int markid  = afGetLoopStart(AFfilehandle file, int instid,
                                        int loopid)
     int markid  = afGetLoopEnd(AFfilehandle file, int instid,
                                        int loopid)
     int trackid = afGetLoopTrack(AFfilehandle file, int instid,
                                        int loopid)
     int mode    = afGetLoopMode(AFfilehandle file, int instid,
                                        int loopid)

PARAMETER
     file     is an AFfilehandle structure, previously created by a call to
              afOpenFile(3dm).

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

     loopid   is a positive integer value which identifies a loop structure in
              an instrument parameter chunk.  You obtain loopid's by calling
              afGetInstParamLong(3dm) for AIFF and AIFF-C formats, or
              afGetLoopIDs(3dm) for any format.

RETURN VALUE
     afGetLoopStart() returns a positive integer markid designating the marker
     structure which stores the loop start point, or -1 if there is an error.

     afGetLoopEnd() returns a positive integer markid designating the marker
     structure which stores the loop end point, or -1 if there is an error.

     afGetLoopTrack() returns a positive integer trackid designating which
     audio track contains the loop, or -1 if there is an error. For all
     currently supported file formats, trackid is always AF_DEFAULT_TRACK.

     afGetLoopMode() returns a positive integer mode which gives the play mode
     for the loop, or -1 if there is an error.

DESCRIPTION
     These routines allow you to obtain information about loops in an audio
     file. Each takes a loopid argument which provides a handle to a set of
     loop parameters.


     You can obtain a list of loop ID's for an audio track by calling
     afGetLoopIDs(3dm).  Logically, an audio file contains zero or more chunks
     of instrument parameters (specified by instid handles), and each chunk of
     instrument parameters may contain zero or more loops.

AIFF INSTRUMENTS AND LOOPS
     AIFF-C (and AIFF) files contain at most one instrument configuration.
     For this format, you may use the constant AF_DEFAULT_INST to reference
     the instrument data, but it is always safer to use afGetInstIDs(3dm).
     AIFF-C (and AIFF) instrument configurations contain two loops, a sustain
     loop and a release loop.  You can determine the ID's for AIFF loops
     directly (without calling afGetLoopIDs(3dm)) by calling
     afGetInstParamLong(3dm) with the parameters AF_INST_SUSLOOPID and
     AF_INST_RELLOOPID.  Note that other formats may contain larger numbers of
     loops, and these instrument parameters do not apply to them.

     Once you know the ID for a loop, you can determine its play mode by
     calling afGetLoopMode.  Valid loop modes are:

     AF_LOOP_MODE_NOLOOP
          loop is to be ignored

     AF_LOOP_MODE_FORW
          forward loop

     AF_LOOP_MODE_FORWBAKW
          forward/backward loop

     You can obtain marker ID's for the marker structures which contain the
     endpoints for a loop by calling afGetLoopStart() and afGetLoopEnd().

EXAMPLE
     afGetLoopStart() returns the value 3.  This is the ID of the marker in
     the audio track which labels the beginning of the specified loop.

     You call afGetMarkPosition(3dm) with markid = 3 to obtain a sample frame
     location in the track.

     Suppose you retrieve the marker position 125000 for the loop start
     marker, and marker position 150000 for the loop end marker.  The loop
     consists of sample frames 125001 through 150000.

     Remember that markers are positioned "between" audio sample frames.  See
     the AIFF or AIFF-C spec for a detailed explanation of how markers and
     loops work.

     afGetLoopTrack() is included in the library as a placeholder for future
     functionality.  It always returns AF_DEFAULT_TRACK for now.


NOTES
     It is now possible to retrieve the loop start and end frame directly
     without using the associated markers (see afGetLoopStartFrame(3dm)).
     This is useful and necessary for audio file formats which support loops
     which are independent of any markers, and for formats which support loops
     but which do not support markers at all.  For formats which always
     associate loops and markers, such as AIFF(4) and WAVE(4),
     afGetLoopStart() and afGetLoopEnd() will always return a valid ID for a
     marker, but this marker may have been artifically generated by the AF.
     If this is the case, the name of the marker (as retrieved via
     afGetMarkName(3dm)) will be "start mark for loop id x" or "end mark for
     loop id x", where x is the loop ID.

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), afGetInstParamLong(3dm), afGetMarkPosition(3dm),
     afGetLoopIDs(3dm), afGetMarkIDs(3dm), aiff(4)


                                                                        Page 3