From bd7b73a621a74de863f6d6f79af4131144e4f9fe Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sun, 31 Aug 2008 03:42:20 +0200 Subject: [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 From: Lennart Poettering Signed-off-by: Jaroslav Kysela --- src/pcm/pcm.c | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c index ee2300ec..ae897950 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() -- 2.47.1