mirrors/alsa-lib
1
0
Fork 0
mirror of https://github.com/alsa-project/alsa-lib.git synced 2025-10-29 05:40:25 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

pcm: documentation improvement mostly regarding samples and frames

Browse source 
In some places samples and frames are used interchangeably, which may
be a little confusing, so update it to say 'frames' where it could matter.

Closes: https://github.com/alsa-project/alsa-lib/pull/375
Signed-off-by: Jaroslav Kysela <perex@perex.cz>
This commit is contained in:
Zeno Endemann 2024-01-01 17:59:46 +01:00 • committed by Jaroslav Kysela
parent c3fec78ddd
commit 31f2ab57e2
1 changed files with 26 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

52
src/pcm/pcm.c
View file

@ -96,7 +96,7 @@ standard C open function - see 'man 2 open'). In non-blocked behaviour,
these I/O functions never stops, they return -EAGAIN error code, when no these I/O functions never stops, they return -EAGAIN error code, when no
data can be transferred (the ring buffer is full in our case). In blocked data can be transferred (the ring buffer is full in our case). In blocked
behaviour, these I/O functions stop and wait until there is a room in the behaviour, these I/O functions stop and wait until there is a room in the
ring buffer (playback) or until there are a new samples (capture). The ALSA ring buffer (playback) or until there are new samples (capture). The ALSA
implementation can be found in the \ref alsa_pcm_rw section. implementation can be found in the \ref alsa_pcm_rw section.
\subsection pcm_transfer_event Event waiting routines \subsection pcm_transfer_event Event waiting routines
@ -351,9 +351,9 @@ enumeration.
These parameters - #snd_pcm_sw_params_t can be modified at These parameters - #snd_pcm_sw_params_t can be modified at
any time including the running state. any time including the running state.
\par Minimum available count of samples \par Minimum available count of frames
This parameter controls the wakeup point. If the count of available samples This parameter controls the wakeup point. If the count of available frames
is equal or greater than this value, then application will be activated. is equal or greater than this value, then application will be activated.
\par Timestamp mode \par Timestamp mode
@ -372,29 +372,29 @@ is ignored by device. Usually, this value is set to one (no align).
\par Start threshold \par Start threshold
The start threshold parameter is used to determine the start point in The start threshold parameter is used to determine the start point in
stream. For playback, if samples in ring buffer is equal or greater than stream. For playback, if the frame count in the ring buffer is equal or greater
the start threshold parameters and the stream is not running, the stream will than the start threshold parameter and the stream is not running, the stream
be started automatically from the device. For capture, if the application wants will be started automatically from the device. For capture, if the application
to read count of samples equal or greater then the stream will be started. wants to read count of frames equal or greater then the stream will be started.
If you want to use explicit start (#snd_pcm_start), you can If you want to use explicit start (#snd_pcm_start), you can set this value
set this value greater than ring buffer size (in samples), but use the greater than the ring buffer size (in frames). For that simply using a large
constant LONG_MAX or the boundary value is not a bad idea. constant such as LONG_MAX or the boundary value is not a bad idea.
\par Stop threshold \par Stop threshold
Similarly, the stop threshold parameter is used to automatically stop Similarly, the stop threshold parameter is used to automatically stop
the running stream, when the available samples crosses this boundary. the running stream, when the available frames crosses this boundary.
It means, for playback, the empty samples in ring buffer and for capture, It means, for playback, the empty samples in ring buffer and for capture,
the filled (used) samples in ring buffer. the filled (used) samples in ring buffer.
\par Silence threshold \par Silence threshold
The silence threshold specifies count of samples filled with silence The silence threshold specifies the count of frames before an underrun when the
ahead of the current application pointer for playback. It is usable buffer gets filled with frames of silence according to the silence size parameter
for applications when an overrun is possible (like tasks depending on ahead of the current application pointer for playback. It is usable for applications
network I/O etc.). If application wants to manage the ahead samples itself, when an underrun is possible (like tasks depending on network I/O etc.). If
the #snd_pcm_rewind() function allows to forget the last application wants to manage the ahead samples itself, the #snd_pcm_rewind() function
samples in the stream. allows to forget the last samples in the stream.
\section pcm_status Obtaining stream status \section pcm_status Obtaining stream status
@ -402,11 +402,11 @@ The stream status is stored in #snd_pcm_status_t structure.
These parameters can be obtained: the current stream state - These parameters can be obtained: the current stream state -
#snd_pcm_status_get_state(), timestamp of trigger - #snd_pcm_status_get_state(), timestamp of trigger -
#snd_pcm_status_get_trigger_tstamp(), timestamp of last #snd_pcm_status_get_trigger_tstamp(), timestamp of last
pointer update #snd_pcm_status_get_tstamp(), delay in samples - pointer update #snd_pcm_status_get_tstamp(), delay in frames -
#snd_pcm_status_get_delay(), available count in samples - #snd_pcm_status_get_delay(), available count in frames -
#snd_pcm_status_get_avail(), maximum available samples - #snd_pcm_status_get_avail(), maximum available frames -
#snd_pcm_status_get_avail_max(), ADC over-range count in #snd_pcm_status_get_avail_max(), ADC over-range count in
samples - #snd_pcm_status_get_overrange(). The last two frames - #snd_pcm_status_get_overrange(). The last two
parameters - avail_max and overrange are reset to zero after the status parameters - avail_max and overrange are reset to zero after the status
call. call.
@ -414,7 +414,7 @@ call.
<p> <p>
The function #snd_pcm_avail_update() updates the current The function #snd_pcm_avail_update() updates the current
available count of samples for writing (playback) or filled samples for available count of frames for writing (playback) or filled frames for
reading (capture). This call is mandatory for updating actual r/w pointer. reading (capture). This call is mandatory for updating actual r/w pointer.
Using standalone, it is a light method to obtain current stream position, Using standalone, it is a light method to obtain current stream position,
because it does not require the user <-> kernel context switch, but the value because it does not require the user <-> kernel context switch, but the value
@ -427,10 +427,10 @@ The function #snd_pcm_avail() reads the current hardware pointer
in the ring buffer from hardware and calls #snd_pcm_avail_update() then. in the ring buffer from hardware and calls #snd_pcm_avail_update() then.
</p> </p>
<p> <p>
The function #snd_pcm_delay() returns the delay in samples. The function #snd_pcm_delay() returns the delay in frames.
For playback, it means count of samples in the ring buffer before For playback, it means count of frames in the ring buffer before
the next sample will be sent to DAC. For capture, it means count of samples the next frames will be sent to DAC. For capture, it means count of frames
in the ring buffer before the next sample will be captured from ADC. It works in the ring buffer before the next frames will be captured from ADC. It works
only when the stream is in the running or draining (playback only) state. only when the stream is in the running or draining (playback only) state.
Note that this function does not update the current r/w pointer for applications, Note that this function does not update the current r/w pointer for applications,
so the function #snd_pcm_avail_update() must be called afterwards so the function #snd_pcm_avail_update() must be called afterwards