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 VALUEafGetLoopStart() 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.
Page 1
afGetLoopStart(3dm)afGetLoopStart(3dm)
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().
EXAMPLEafGetLoopStart() 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.
Page 2
afGetLoopStart(3dm)afGetLoopStart(3dm)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 ALSOafOpenFile(3dm), afGetInstParamLong(3dm), afGetMarkPosition(3dm),
afGetLoopIDs(3dm), afGetMarkIDs(3dm), aiff(4)
Page 3
