[alsa-devel] [PATCH] alsa-lib: Reword doxygen doc for snd_pcm_delay()

[Lennart Poettering]

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()
-- 
1.6.0.1



Lennart

-- 
Lennart Poettering                        Red Hat, Inc.
lennart [at] poettering [dot] net         ICQ# 11060553
http://0pointer.net/lennart/           GnuPG 0x1A015CC4