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.
DESCRIPTIONafInitLoopIDs(3dm) initializes a list of unique loop ID's corresponding
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.
Page 1
afInitLoopIDs(3dm)afInitLoopIDs(3dm)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 ALSOafNewFileSetup(3dm), afOpenFile(3dm), afInitMarkIDs(3dm),
afInitInstIDs(3dm), afSetLoopStart(3dm), afSetInstParamLong(3dm),
afSetMarkPosition(3dm)
Page 2
