- replace "audio stream" by "audio device", as sndio is a device

abstraction
- remove useless statements.

libsndio/sio_open.3

@@ -35,7 +35,7 @@
 .Nm sio_setvol ,
 .Nm sio_onvol ,
 .Nm sio_initpar
-.Nd interface to bidirectional audio streams
+.Nd interface to audio devices
 .Sh SYNOPSIS
 .In sndio.h
 .Ft "struct sio_hdl *"
@@ -87,10 +87,10 @@ used with the
 .Xr sndiod 1
 server it supports resampling and format
 conversions on the fly.
-.Ss Opening and closing an audio stream
+.Ss Opening and closing an audio device
 First the application must call the
 .Fn sio_open
-function to obtain a handle representing the newly created stream;
+function to obtain a handle to the device;
 later it will be passed as the
 .Ar hdl
 argument of most other functions.
@@ -103,19 +103,16 @@ the user to select it using the
 .Ev AUDIODEVICE
 environment variable.
 .Pp
-The
+The following values of the
 .Ar mode
-parameter gives the direction of the stream.
+parameter are supported:
-The following are supported:
 .Bl -tag -width "SIO_PLAY | SIO_REC"
 .It SIO_PLAY
-The stream is play-only; data written to the stream will be played
+Play-only mode: data written will be played by the device.
-by the hardware.
 .It SIO_REC
-The stream is record-only; recorded samples by the hardware
+Record-only mode: samples are recorded by the device and must be read.
-must be read from the stream.
 .It SIO_PLAY | SIO_REC
-The stream plays and records synchronously; this means that
+The device plays and records synchronously; this means that
 the n-th recorded sample was physically sampled exactly when
 the n-th played sample was actually played.
 .El
@@ -130,20 +127,17 @@ functions (see below) will be non-blocking.
 .Pp
 The
 .Fn sio_close
-function closes the stream and frees all allocated resources
+function closes the device and frees the handle.
-associated with the
+If the device is not stopped it will be stopped first as if
-.Nm libsndio
-handle.
-If the stream is not stopped it will be stopped first as if
 .Fn sio_stop
 is called.
 .Ss Negotiating audio parameters
-Audio streams always use linear interleaved encoding.
+Audio samples are interleaved.
-A frame consists of one sample for each channel in the stream.
+A frame consists of one sample for each channel.
-For example, a 16-bit stereo stream has two samples per frame
+For example, a 16-bit stereo encoding has two samples per frame
-and, typically, two bytes per sample (thus 4 bytes per frame).
+and, two bytes per sample (thus 4 bytes per frame).
 .Pp
-The set of parameters of the stream that can be controlled
+The set of parameters of the device that can be controlled
 is given by the following structure:
 .Bd -literal
 struct sio_par {
@@ -231,7 +225,7 @@ or
 constants.
 .El
 .Pp
-The following approach is recommended to negotiate parameters of the stream:
+The following approach is recommended to negotiate device parameters:
 .Bl -bullet
 .It
 Initialize a
@@ -244,19 +238,18 @@ If the application supports any value for a given parameter,
 then the corresponding parameter should be left unset.
 Then call
 .Fn sio_setpar
-to request the stream to use them.
+to request the device to use them.
 .It
 Call
 .Fn sio_getpar
-to retrieve the actual parameters of the stream
+to retrieve the actual parameters of the device
 and check that they are usable.
 If they are not, then fail or set up a conversion layer.
 Sometimes the rate set can be slightly different to what was requested.
 A difference of about 0.5% is not audible and should be ignored.
 .El
 .Pp
-Parameters cannot be changed while the stream is in a waiting state;
+Parameters cannot be changed after
-if
 .Fn sio_start
 has been called,
 .Fn sio_stop
@@ -286,9 +279,9 @@ Can be used to set the
 .Va le
 parameter when native byte order is required.
 .El
-.Ss Getting stream capabilities
+.Ss Getting device capabilities
 There's no way to get an exhaustive list of all parameter
-combinations the stream supports.
+combinations the device supports.
 Applications that need to have a set of working
 parameter combinations in advance can use the
 .Fn sio_getcap
@@ -377,11 +370,11 @@ array of the
 .Va sio_cap
 structure is valid for this configuration.
 .El
-.Ss Starting and stopping the stream
+.Ss Starting and stopping the device
 The
 .Fn sio_start
-function puts the stream in a waiting state:
+function puts the device in a waiting state:
-the stream will wait for playback data to be provided
+the device will wait for playback data to be provided
 (using the
 .Fn sio_write
 function).
@@ -403,7 +396,7 @@ be played after
 .Fn sio_stop
 returns.
 If samples to play are queued but playback hasn't started yet
-then playback is forced immediately; the stream will actually stop
+then playback is forced immediately; the device will actually stop
 once the buffer is drained.
 .Ss Playing and recording
 When record mode is selected, the
@@ -440,17 +433,10 @@ and
 functions will never block; if no data is available, they will
 return zero immediately.
 .Pp
-Note that non-blocking mode must be used on bidirectional streams.
+The
-For instance, if recording is blocked in
-.Fn sio_read
-then, even if samples can be played,
-.Fn sio_write
-cannot be called and the play buffers may underrun.
-.Pp
-To avoid busy loops when non-blocking mode is used, the
 .Xr poll 2
 system call can be used to check if data can be
-read from or written to the stream.
+read from or written to the device.
 The
 .Fn sio_pollfd
 function fills the array
@@ -483,14 +469,14 @@ array of
 structures.
 If
 .Va POLLIN
-is set,
+is set, recorded samples are available in the device buffer
-.Fn sio_read
+and can be read with
-can be called without blocking.
+.Fn sio_read .
 If
 .Va POLLOUT
-is set,
+is set, space is available in the device buffer and new samples
-.Fn sio_write
+to play can be submitted with
-can be called without blocking.
+.Fn sio_write .
 POLLHUP may be set if an error occurs, even if
 it is not selected with
 .Fn sio_pollfd .
@@ -503,8 +489,8 @@ structures the caller must preallocate in order to be sure
 that
 .Fn sio_pollfd
 will never overrun.
-.Ss Synchronizing non-audio events to the stream in real-time
+.Ss Synchronizing non-audio events to the audio stream in real-time
-In order to perform actions at precise positions of the stream,
+In order to perform actions at precise positions of the audio stream,
 such as displaying video in sync with the audio stream,
 the application must be notified in real-time of the exact
 position in the stream the hardware is processing.
@@ -513,16 +499,18 @@ The
 .Fn sio_onmove
 function can be used to register the
 .Va cb
-callback function that will be called by the
+callback function called at regular time intervals.
-.Nm sndio
-library at regular time intervals to notify the application
-the position in the stream changed.
 The
 .Va delta
-argument contains the number of frames the hardware moved in the stream
+argument contains the number of frames the hardware played and/or recorded
 since the last call of
 .Va cb .
-When the stream starts, the callback is invoked with a zero
+It is called by
+.Fn sio_read , sio_write ,
+and
+.Fn sio_revents .
+When the first sample is played and/or recorded, right after the device starts,
+the callback is invoked with a zero
 .Va delta
 argument.
 The value of the
@@ -556,17 +544,14 @@ During this phase talking about latency is meaningless.
 In any cases, at most
 .Va bufsz
 frames are buffered.
-This value takes into account all buffers,
+This value takes into account all buffers.
-including device, kernel and socket buffers.
 The number of frames stored is equal to the number of frames
 written minus the current position.
 .Pp
 The recording latency is obtained similarly, by subtracting
 the number of frames read from the current position.
 .Pp
-It is strongly discouraged to use the latency and/or the buffer
+Note that
-usage for anything but monitoring.
-Especially, note that
 .Fn sio_write
 might block even if there is buffer space left;
 using the buffer usage to guess if
@@ -589,11 +574,11 @@ parameter of the
 structure, the audio subsystem will behave as follows:
 .Bl -tag -width "SIO_IGNORE"
 .It SIO_IGNORE
-The stream is paused during overruns and underruns,
+The devices pauses during overruns and underruns,
 thus the current position (obtained through
 .Va sio_onmove )
 stops being incremented.
-Once the overrun and/or underrun condition is gone, the stream is unpaused;
+Once the overrun and/or underrun condition is gone, the device resumes;
 play and record are always kept in sync.
 With this mode, the application cannot notice
 underruns and/or overruns and shouldn't care about them.
@@ -623,14 +608,12 @@ where time is important and where underruns or overruns are
 short and rare.
 .It SIO_ERROR
 With this mode, on the first play buffer underrun or
-record buffer overrun, the stream is terminated and
+record buffer overrun, playback and/or recording is terminated and
 no other function than
 .Fn sio_close
 will succeed.
 .Pp
-This mode is mostly useful for testing; portable
+This mode is mostly useful for testing.
-applications shouldn't depend on it, since it's not available
-on other systems.
 .El
 .Ss Controlling the volume
 The
@@ -733,7 +716,7 @@ may be a value between 0 and 2.
 .Sh BUGS
 The
 .Xr audio 4
-driver cannot drain playback buffers in the background, thus if
+driver doesn't drain playback buffers, thus if
 .Nm libsndio
 is used to directly access an
 .Xr audio 4
@@ -742,12 +725,11 @@ the
 .Fn sio_stop
 function will stop playback immediately.
 .Pp
-The
-.Xr sndiod 1
-server doesn't implement flow control (for performance reasons).
 If the application doesn't consume recorded data fast enough then
 .Dq "control messages"
-are delayed and consequently
+from the
+.Xr sndiod 1
+server are delayed and consequently
 .Va sio_onmove
 callback or volume changes may be delayed.
 .Pp