alGetFrameNumber(3dm)                                    alGetFrameNumber(3dm)


NAME
     alGetFrameNumber - Get the absolute sample frame number associated with a
     port

SYNOPSIS
     #include <dmedia/audio.h>

     int alGetFrameNumber(const ALport port, stamp_t *fnum)

PARAMETERS
     port expects the ALport structure for the audio port for which you wish
          to know the sample frame number.  This structure is the returned
          value of the alOpenPort(3dm) call.

     fnum expects a pointer to an unsigned 64-bit value which is to contain
          the resultant sample-frame number.

DESCRIPTION
     Each audio device on a system counts how many sample frames have come in
     or gone out of that device. This count is known as the absolute sample
     frame number for that device. All audio ports connected to a given device
     share its absolute frame number as a common timeline.

     For an input port, alGetFrameNumber returns the absolute sample frame
     number associated with the next sample frame to be read from the port.
     If the port's queue is in an overflow state, the frame number will be
     constantly changing. The application should bring the port out of
     overflow state by reading or discarding sample frames, then re-examine
     the value of alGetFrameNumber.

     For an output port, alGetFrameNumber returns the absolute sample frame
     number associated with the next sample frame to be written to the port.
     If the port's queue is in an underflow state, the frame number will be
     constantly changing. The application should bring the port out of
     underflow state by writing samples into it, then re-examine the value of
     alGetFrameNumber.

     For ports transferring subcode data, the sample frame number returned by
     alGetFrameNumber corresponds to the sample frame number of the last audio
     data sample associated with the subcode frame.

     Practically speaking, alGetFrameNumber allows an application to precisely
     determine when a port's samples came into the machine or when they will
     go out, using the sample-frame counter as a timeline. To reference this
     timeline to the timelines for other media, or for other audio devices,
     the alGetFrameTime() call should be used as well.

     See the manual page for alGetFrameTime for a code example illustrating
     how these two calls work.


DIAGNOSTICS
     Upon successful completion, alGetFrameNumber returns 0. Otherwise
     alGetFrameNumber returns -1 and sets an error number which can be
     retrieved with oserror(3C).

     alGetFrameNumber can fail for the following reasons:

     AL_BAD_PORT            port is invalid.


SEE ALSO
     alOpenPort(3dm), alGetFrameTime(3dm), oserror(3C)


                                                                        Page 2