Restructured library documentation

1 files changed, 120 insertions, 0 deletions

diff --git a/Doc/libaudio.tex b/Doc/libaudio.tex
new file mode 100644
index 0000000..47c0b64
--- /dev/null
+++ b/Doc/libaudio.tex
@@ -0,0 +1,120 @@
+\section{Built-in Module \sectcode{audio}}
+\bimodindex{audio}
+
+\strong{Note:} This module is obsolete, since the hardware to which it
+interfaces is obsolete.  For audio on the Indigo or 4D/35, see
+built-in module \code{al} above.
+
+This module provides rudimentary access to the audio I/O device
+\file{/dev/audio} on the Silicon Graphics Personal IRIS 4D/25;
+see {\it audio}(7). It supports the following operations:
+
+\renewcommand{\indexsubitem}{(in module audio)}
+\begin{funcdesc}{setoutgain}{n}
+Sets the output gain.
+\iftexi
+\code{0 <= \var{n} < 256}.
+\else
+$0 \leq \var{n} < 256$.
+%%JHXXX Sets the output gain (0-255).
+\fi
+\end{funcdesc}
+
+\begin{funcdesc}{getoutgain}{}
+Returns the output gain.
+\end{funcdesc}
+
+\begin{funcdesc}{setrate}{n}
+Sets the sampling rate: \code{1} = 32K/sec, \code{2} = 16K/sec,
+\code{3} = 8K/sec.
+\end{funcdesc}
+
+\begin{funcdesc}{setduration}{n}
+Sets the `sound duration' in units of 1/100 seconds.
+\end{funcdesc}
+
+\begin{funcdesc}{read}{n}
+Reads a chunk of
+\var{n}
+sampled bytes from the audio input (line in or microphone).
+The chunk is returned as a string of length n.
+Each byte encodes one sample as a signed 8-bit quantity using linear
+encoding.
+This string can be converted to numbers using \code{chr2num()} described
+below.
+\end{funcdesc}
+
+\begin{funcdesc}{write}{buf}
+Writes a chunk of samples to the audio output (speaker).
+\end{funcdesc}
+
+These operations support asynchronous audio I/O:
+
+\renewcommand{\indexsubitem}{(in module audio)}
+\begin{funcdesc}{start_recording}{n}
+Starts a second thread (a process with shared memory) that begins reading
+\var{n}
+bytes from the audio device.
+The main thread immediately continues.
+\end{funcdesc}
+
+\begin{funcdesc}{wait_recording}{}
+Waits for the second thread to finish and returns the data read.
+\end{funcdesc}
+
+\begin{funcdesc}{stop_recording}{}
+Makes the second thread stop reading as soon as possible.
+Returns the data read so far.
+\end{funcdesc}
+
+\begin{funcdesc}{poll_recording}{}
+Returns true if the second thread has finished reading (so
+\code{wait_recording()} would return the data without delay).
+\end{funcdesc}
+
+\begin{funcdesc}{start_playing}{}
+\funcline{wait_playing}{}
+\funcline{stop_playing}{}
+\funcline{poll_playing}{}
+\begin{sloppypar}
+Similar but for output.
+\code{stop_playing()}
+returns a lower bound for the number of bytes actually played (not very
+accurate).
+\end{sloppypar}
+\end{funcdesc}
+
+The following operations do not affect the audio device but are
+implemented in C for efficiency:
+
+\renewcommand{\indexsubitem}{(in module audio)}
+\begin{funcdesc}{amplify}{buf\, f1\, f2}
+Amplifies a chunk of samples by a variable factor changing from
+\code{\var{f1}/256} to \code{\var{f2}/256.}
+Negative factors are allowed.
+Resulting values that are to large to fit in a byte are clipped.         
+\end{funcdesc}
+
+\begin{funcdesc}{reverse}{buf}
+Returns a chunk of samples backwards.
+\end{funcdesc}
+
+\begin{funcdesc}{add}{buf1\, buf2}
+Bytewise adds two chunks of samples.
+Bytes that exceed the range are clipped.
+If one buffer is shorter, it is assumed to be padded with zeros.
+\end{funcdesc}
+
+\begin{funcdesc}{chr2num}{buf}
+Converts a string of sampled bytes as returned by \code{read()} into
+a list containing the numeric values of the samples.
+\end{funcdesc}
+
+\begin{funcdesc}{num2chr}{list}
+\begin{sloppypar}
+Converts a list as returned by
+\code{chr2num()}
+back to a buffer acceptable by
+\code{write()}.
+\end{sloppypar}
+\end{funcdesc}