alGetFrameTime(3dm)alGetFrameTime(3dm)NAMEalGetFrameTime - 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.
DESCRIPTIONalGetFrameTime 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
Page 1
alGetFrameTime(3dm)alGetFrameTime(3dm)
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 ALSOdmGetUST(3dm), alGetFrameNumber(3dm), oserror(3C)
Page 2
