alGetFrameTime(3dm)                                        alGetFrameTime(3dm)


NAME
     alGetFrameTime - Get the time at which a sample frame came in or will go
     out

SYNOPSIS
     #include <dmedia/audio.h>

     int alGetFrameTime(const ALport port, stamp_t *fnum, stamp_t *time)

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.

     time expects a pointer to an unsigned 64-bit value which is to contain
          the resultant sample-frame time, in nanoseconds.

DESCRIPTION
     alGetFrameTime returns an atomic pair of (fnum, time) for the device to
     which port is connected. For an input device, the time returned is the
     time at which the returned sample frame arrived at the electrical input
     on the machine. For an output device, the time returned is the time at
     which the returned sample frame will arrive at the electrical output on
     the machine.

     The application cannot request a specific pair of values; alGetFrameTime
     merely returns the most recent pair available. It is up to the
     application to use this pair to calculate the time associated with a
     particular sample-frame, or the sample-frame number associated with a
     particular time, if desired.

     In general, the returned sample frame will not currently be in any
     application's port. For example, an input sample frame as returned by
     alGetFrameTime may be "in the future": it has not yet arrived in any
     application's port. Similarly, an output sample frame may be "in the
     past": it has already gone out of some application's port. In order to
     relate the sample frame numbers to those of a particular application's
     audio port, the alGetFrameNumber call must be used.

     alGetFrameTime uses the Unadjusted System Time (UST) as its timeline.
     This allows it to relate to other media which also use UST. See the man
     page for dmGetUST(3dm) for more information on UST.

EXAMPLE


          stamp_t fn, t;
          stamp_t fnd,td;
          double nanosec_per_frame = 1000000000.0 / rate_in_Hz;

          /*
           * Get the device sample frame number associated with the next
           * audio sample frame I'm going to read or write from this port
           */
          alGetFrameNumber(port, &fn);

          /*
           * Get some recent pair of (frame number, time) from the audio
           * device to which my port is connected. time is on a timeline
           * called UST which is given in nanoseconds and shared with the
           * other audio devices and with other media.
           */
          alGetFrameTime(port, &fnd, &td);

          /*
           * Calculate the UST associated with fn, the next sample frame
           * we're going to read or write. Because this is signed
           * arithmetic, this code works for both input and output ports.
           */
          t = td + (stamp_t) ((double)(fn - fnd) * nanosec_per_frame);

          /*
           * If my port is not in an underflow or overflow state, I can do an
           * alReadFrames or alWriteFrames here and know that t is the time
           * associated with the first sample frame of the buffer I read or
           * write.
           */


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

     alGetFrameTime can fail for the following reasons:

     AL_BAD_PORT            port is invalid.


SEE ALSO
     dmGetUST(3dm), alGetFrameNumber(3dm), oserror(3C)


                                                                        Page 2