[alsa-devel] [PATCH] alsa-lib: Reword doxygen doc for snd_pcm_delay()
snd_pcm_delay() is for synchronization purposes, it returns the overall latency of the stream, not just the latency induced by the hardware playback buffer. The documentation is a bit misleading about this fact, and some people already misunderstood it. So let's reword this to make the explanation clearer and explicit.
This is a result of the discussions of the thread this mail belongs to:
http://mailman.alsa-project.org/pipermail/alsa-devel/2008-June/008456.html
Lennart
--- src/pcm/pcm.c | 22 +++++++++++++++++----- 1 files changed, 17 insertions(+), 5 deletions(-)
diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c index ee2300e..ae89795 100644 --- a/src/pcm/pcm.c +++ b/src/pcm/pcm.c @@ -939,11 +939,23 @@ int snd_pcm_hwsync(snd_pcm_t *pcm) * \param delayp Returned delay in frames * \return 0 on success otherwise a negative error code * - * Delay is distance between current application frame position and - * sound frame position. - * It's positive and less than buffer size in normal situation, - * negative on playback underrun and greater than buffer size on - * capture overrun. + * For playback the delay is defined as the time that a frame that is written + * to the PCM stream shortly after this call will take to be actually + * audible. It is as such the overall latency from the write call to the final + * DAC. + * + * For capture the delay is defined as the time that a frame that was + * digitized by the audio device takes until it can be read from the PCM + * stream shortly after this call returns. It is as such the overall latency + * from the initial ADC to the read call. + * + * Please note that hence in case of a playback underrun this value will not + * necessarily got down to 0. + * + * If the application is interested in the fill level of the playback buffer + * of the device, it should use snd_pcm_avail_update(). The + * value returned by that call is not directly related to the delay, since the + * latter might include some additional, fixed latencies the former does not. * * Note this function does not update the actual r/w pointer * for applications. The function #snd_pcm_avail_update()
participants (1)
-
Lennart Poettering