afGetMarkPosition(3dm)                                  afGetMarkPosition(3dm)


NAME
     afGetMarkPosition, AFgetmarkpos, afSetMarkPosition, AFsetmarkpos -
     get/set the position of a marker in an audio track

SYNOPSIS
     #include <dmedia/audiofile.h>

     AFframecount afGetMarkPosition(AFfilehandle file, int trackid, int markid)

     void afSetMarkPosition(AFfilehandle file, int trackid, int markid,
                                                 AFframecount markpos)

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

     trackid   expects a positive integer value which identifies an audio
               track in file.  All currently supported file formats allow
               exactly one track per file, so the constant AF_DEFAULT_TRACK
               should always be used here for now.

     markid    is a positive integer value which identifies a marker structure
               in the audio track given by trackid.

               You obtain marker ID's by calling afGetMarkIDs(3dm).  You can
               call afInitMarkIDs(3dm) to assign your own ID's when you create
               a new audio file.

     markpos   is a nonnegative value of type AFframecount which marks a
               location in an audio track.  This value should be  between 0
               and the total number of audio sample frames stored in the
               track, but can be set beyond EOF in the expectation of an
               extension of the current track's length.

RETURN VALUE
     afGetMarkPosition() returns a value of type AFframecount representing the
     location of the mark in the audio track, or -1 if there is an error.

DESCRIPTION
     Markers point to locations "between" adjacent sample frames in an audio
     track.

     If a track contains 500000 stereo sample pairs (frames), then the range
     of possible marker positions is 0 to 500000.  Position 0 is before the
     first frame, position 1 is between the first and second frames, position
     500000 is after the last frame.

     You can use afGetMarkPosition() to obtain the marker position stored in a
     marker structure for an audio track.


     You can use afSetMarkPosition() to set track position for a marker
     structure in a file opened for write access.

EXAMPLE
     In AIFF and AIFF-C files, markers are used to delimit loop endpoints.

     If you want to define a sustain loop which starts at frame 100000 and
     ends at frame 200000 in the above track, you would use two markers. You
     would assign the position 99999 to the first marker, and the position
     200000 to the second using afSetMarkPosition(3dm).

     Then you would use the routines afSetLoopStart(3dm) and afSetLoopEnd(3dm)
     to attach the marker structures to the sustain loop structure.  Finally,
     you would call afSetInstParamLong(3dm) to map the loop ID to the sustain
     loop location in the instrument configuration chunk.

     To read loop information out of an audio file, you'd first obtain loop
     ID's for the sustain and release loop by calling afGetInstParamLong(3dm).
     Then you'd obtain marker ID's for the beginning and end points of the
     loops by calling afGetLoopStart(3dm) and afGetLoopEnd(3dm).

     Finally, you would obtain the positions of the individual markers by
     calling afGetMarkPosition().

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.

SEE ALSO
     afOpenFile(3dm), afGetMarkIDs(3dm), afInitMarkIDs(3dm),
     afGetInstParamLong(3dm), afGetLoopStart(3dm), afSetLoopStart(3dm)


                                                                        Page 2