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