ALgetframenumber(3dm)

NAME
     ALgetframenumber - (obsolete) Get the absolute sample frame number
     associated with a port

SYNOPSIS
     #include <dmedia/audio.h>

     int ALgetframenumber(const ALport port, unsigned long long *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
     ALgetframenumber is obsolete and is provided for backward compatibility.
     The preferred function is alGetFrameNumber(3dm).

     An audio sample frame is a group of samples which come into a port or go
     out of a port simultaneously. For example, the sample frame for a stereo
     audio port is a left / right sample pair. Whenever any audio port is
     open, audio sample frames are continuously coming into the audio device
     and/or going out of the audio device. A count is kept of the number of
     sample frames which come in or go out; this is called the absolute sample
     frame number for that device.

     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
     overflow state by writing samples into it, then re-examine the value of
     ALgetframenumber.

     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, the
     ALgetframetime() call should be used as well.

     ALgetframenumber can fail for the following reasons:
     AL_BAD_PORT            port is invalid.

     AL_BAD_NOT_IMPLEMENTED the feature is not implemented on the given
                            machine. ALgetframenumber is not implemented on
                            Indigo (IP12), 4D/35 (IP12), and Indigo R4K (IP20)
                            systems.


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

SEE ALSO
     ALopenport(3dm), ALgetframetime(3dm), oserror(3C)