Restructured library documentation

1 files changed, 177 insertions, 0 deletions

diff --git a/Doc/libal.tex b/Doc/libal.tex
new file mode 100644
index 0000000..708c54e
--- /dev/null
+++ b/Doc/libal.tex
@@ -0,0 +1,177 @@
+\section{Built-in Module \sectcode{al}}
+\bimodindex{al}
+
+This module provides access to the audio facilities of the Indigo and
+4D/35 workstations, described in section 3A of the IRIX 4.0 man pages
+(and also available as an option in IRIX 3.3).  You'll need to read
+those man pages to understand what these functions do!
+Some of the functions are not available in releases below 4.0.5.
+Again, see the manual to check whether a specific function is
+available on your platform.
+
+Symbolic constants from the C header file \file{<audio.h>} are defined
+in the standard module \code{AL}, see below.
+
+\strong{Warning:} the current version of the audio library may dump core
+when bad argument values are passed rather than returning an error
+status.  Unfortunately, since the precise circumstances under which
+this may happen are undocumented and hard to check, the Python
+interface can provide no protection against this kind of problems.
+(One example is specifying an excessive queue size --- there is no
+documented upper limit.)
+
+Module \code{al} defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module al)}
+\begin{funcdesc}{openport}{name\, direction\, config}
+Equivalent to the C function ALopenport().  The name and direction
+arguments are strings.  The optional config argument is an opaque
+configuration object as returned by \code{al.newconfig()}.  The return
+value is an opaque port object; methods of port objects are described
+below.
+\end{funcdesc}
+
+\begin{funcdesc}{newconfig}{}
+Equivalent to the C function ALnewconfig().  The return value is a new
+opaque configuration object; methods of configuration objects are
+described below.
+\end{funcdesc}
+
+\begin{funcdesc}{queryparams}{device}
+Equivalent to the C function ALqueryparams().  The device argument is
+an integer.  The return value is a list of integers containing the
+data returned by ALqueryparams().
+\end{funcdesc}
+
+\begin{funcdesc}{getparams}{device\, list}
+Equivalent to the C function ALgetparams().  The device argument is an
+integer.  The list argument is a list such as returned by
+\code{queryparams}; it is modified in place (!).
+\end{funcdesc}
+
+\begin{funcdesc}{setparams}{device\, list}
+Equivalent to the C function ALsetparams().  The device argument is an
+integer.The list argument is a list such as returned by
+\code{al.queryparams}.
+\end{funcdesc}
+
+Configuration objects (returned by \code{al.newconfig()} have the
+following methods:
+
+\renewcommand{\indexsubitem}{(audio configuration object method)}
+\begin{funcdesc}{getqueuesize}{}
+Return the queue size; equivalent to the C function ALgetqueuesize().
+\end{funcdesc}
+
+\begin{funcdesc}{setqueuesize}{size}
+Set the queue size; equivalent to the C function ALsetqueuesize().
+\end{funcdesc}
+
+\begin{funcdesc}{getwidth}{}
+Get the sample width; equivalent to the C function ALgetwidth().
+\end{funcdesc}
+
+\begin{funcdesc}{getwidth}{width}
+Set the sample width; equivalent to the C function ALsetwidth().
+\end{funcdesc}
+
+\begin{funcdesc}{getchannels}{}
+Get the channel count; equivalent to the C function ALgetchannels().
+\end{funcdesc}
+
+\begin{funcdesc}{setchannels}{nchannels}
+Set the channel count; equivalent to the C function ALsetchannels().
+\end{funcdesc}
+
+\begin{funcdesc}{getsampfmt}{}
+Get the sample format; equivalent to the C function ALgetsampfmt().
+\end{funcdesc}
+
+\begin{funcdesc}{setsampfmt}{sampfmt}
+Set the sample format; equivalent to the C function ALsetsampfmt().
+\end{funcdesc}
+
+\begin{funcdesc}{getfloatmax}{}
+Get the maximum value for floating sample formats;
+equivalent to the C function ALgetfloatmax().
+\end{funcdesc}
+
+\begin{funcdesc}{setfloatmax}{floatmax}
+Set the maximum value for floating sample formats;
+equivalent to the C function ALsetfloatmax().
+\end{funcdesc}
+
+Port objects (returned by \code{al.openport()} have the following
+methods:
+
+\renewcommand{\indexsubitem}{(audio port object method)}
+\begin{funcdesc}{closeport}{}
+Close the port; equivalent to the C function ALcloseport().
+\end{funcdesc}
+
+\begin{funcdesc}{getfd}{}
+Return the file descriptor as an int; equivalent to the C function
+ALgetfd().
+\end{funcdesc}
+
+\begin{funcdesc}{getfilled}{}
+Return the number of filled samples; equivalent to the C function
+ALgetfilled().
+\end{funcdesc}
+
+\begin{funcdesc}{getfillable}{}
+Return the number of fillable samples; equivalent to the C function
+ALgetfillable().
+\end{funcdesc}
+
+\begin{funcdesc}{readsamps}{nsamples}
+Read a number of samples from the queue, blocking if necessary;
+equivalent to the C function ALreadsamples.  The data is returned as a
+string containing the raw data (e.g. 2 bytes per sample in big-endian
+byte order (high byte, low byte) if you have set the sample width to 2
+bytes.
+\end{funcdesc}
+
+\begin{funcdesc}{writesamps}{samples}
+Write samples into the queue, blocking if necessary; equivalent to the
+C function ALwritesamples.  The samples are encoded as described for
+the \code{readsamps} return value.
+\end{funcdesc}
+
+\begin{funcdesc}{getfillpoint}{}
+Return the `fill point'; equivalent to the C function ALgetfillpoint().
+\end{funcdesc}
+
+\begin{funcdesc}{setfillpoint}{fillpoint}
+Set the `fill point'; equivalent to the C function ALsetfillpoint().
+\end{funcdesc}
+
+\begin{funcdesc}{getconfig}{}
+Return a configuration object containing the current configuration of
+the port; equivalent to the C function ALgetconfig().
+\end{funcdesc}
+
+\begin{funcdesc}{setconfig}{config}
+Set the configuration from the argument, a configuration object;
+equivalent to the C function ALsetconfig().
+\end{funcdesc}
+
+\begin{funcdesc}{getstatus}{list}
+Get status information on last error
+equivalent to C function ALgetstatus().
+\end{funcdesc}
+
+\section{Standard Module \sectcode{AL}}
+\nodename{AL (uppercase)}
+\stmodindex{AL}
+
+This module defines symbolic constants needed to use the built-in
+module \code{al} (see above); they are equivalent to those defined in
+the C header file \file{<audio.h>} except that the name prefix
+\samp{AL_} is omitted.  Read the module source for a complete list of
+the defined names.  Suggested use:
+
+\bcode\begin{verbatim}
+import al
+from AL import *
+\end{verbatim}\ecode