pcm: documentation improvement mostly regarding samples and frames

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: #375
Signed-off-by: Jaroslav Kysela <[email protected]>

src/pcm/pcm.c

@@ -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
 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
-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.
 
 \subsection pcm_transfer_event Event waiting routines
@@ -351,9 +351,9 @@ enumeration.
 These parameters - #snd_pcm_sw_params_t can be modified at
 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.
 
 \par Timestamp mode
@@ -372,49 +372,49 @@ is ignored by device. Usually, this value is set to one (no align).
 \par Start threshold
 
 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
-the start threshold parameters and the stream is not running, the stream will
-be started automatically from the device. For capture, if the application wants
-to read count of samples equal or greater then the stream will be started.
-If you want to use explicit start (#snd_pcm_start), you can
-set this value greater than ring buffer size (in samples), but use the
-constant LONG_MAX or the boundary value is not a bad idea.
+stream. For playback, if the frame count in the ring buffer is equal or greater
+than the start threshold parameter and the stream is not running, the stream
+will be started automatically from the device. For capture, if the application
+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 set this value
+greater than the ring buffer size (in frames). For that simply using a large
+constant such as LONG_MAX or the boundary value is not a bad idea.
 
 \par Stop threshold
 
 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,
 the filled (used) samples in ring buffer.
 
 \par Silence threshold
 
-The silence threshold specifies count of samples filled with silence
-ahead of the current application pointer for playback. It is usable
-for applications when an overrun is possible (like tasks depending on
-network I/O etc.). If application wants to manage the ahead samples itself,
-the #snd_pcm_rewind() function allows to forget the last
-samples in the stream.
+The silence threshold specifies the count of frames before an underrun when the
+buffer gets filled with frames of silence according to the silence size parameter
+ahead of the current application pointer for playback. It is usable for applications
+when an underrun is possible (like tasks depending on network I/O etc.). If
+application wants to manage the ahead samples itself, the #snd_pcm_rewind() function
+allows to forget the last samples in the stream.
 
 \section pcm_status Obtaining stream status
 
 The stream status is stored in #snd_pcm_status_t structure.
 These parameters can be obtained: the current stream state -
 #snd_pcm_status_get_state(), timestamp of trigger -
 #snd_pcm_status_get_trigger_tstamp(), timestamp of last
-pointer update #snd_pcm_status_get_tstamp(), delay in samples -
-#snd_pcm_status_get_delay(), available count in samples -
-#snd_pcm_status_get_avail(), maximum available samples -
+pointer update #snd_pcm_status_get_tstamp(), delay in frames -
+#snd_pcm_status_get_delay(), available count in frames -
+#snd_pcm_status_get_avail(), maximum available frames -
 #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
 call.
 
 \subsection pcm_status_fast Obtaining stream state fast and update r/w pointer
 
 <p>
 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.
 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
@@ -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.
 </p>
 <p>
-The function #snd_pcm_delay() returns the delay in samples.
-For playback, it means count of samples in the ring buffer before
-the next sample will be sent to DAC. For capture, it means count of samples
-in the ring buffer before the next sample will be captured from ADC. It works
+The function #snd_pcm_delay() returns the delay in frames.
+For playback, it means count of frames in the ring buffer before
+the next frames will be sent to DAC. For capture, it means count of frames
+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.
 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