Doc/lib/libal.tex

   1 \section{\module{al} ---
   2          Audio functions on the SGI.}
   3 \declaremodule{builtin}{al}
   4
   5 \modulesynopsis{Audio functions on the SGI.}
   6
   7
   8 This module provides access to the audio facilities of the SGI Indy
   9 and Indigo workstations.  See section 3A of the IRIX man pages for
  10 details.  You'll need to read those man pages to understand what these
  11 functions do!  Some of the functions are not available in IRIX
  12 releases before 4.0.5.  Again, see the manual to check whether a
  13 specific function is available on your platform.
  14
  15 All functions and methods defined in this module are equivalent to
  16 the \C{} functions with \samp{AL} prefixed to their name.
  17
  18 Symbolic constants from the \C{} header file \code{<audio.h>} are
  19 defined in the standard module \module{AL}\refstmodindex{AL}, see
  20 below.
  21
  22 \strong{Warning:} the current version of the audio library may dump core
  23 when bad argument values are passed rather than returning an error
  24 status.  Unfortunately, since the precise circumstances under which
  25 this may happen are undocumented and hard to check, the Python
  26 interface can provide no protection against this kind of problems.
  27 (One example is specifying an excessive queue size --- there is no
  28 documented upper limit.)
  29
  30 The module defines the following functions:
  31
  32
  33 \begin{funcdesc}{openport}{name, direction\optional{, config}}
  34 The name and direction arguments are strings.  The optional
  35 \var{config} argument is a configuration object as returned by
  36 \function{newconfig()}.  The return value is an \dfn{audio port
  37 object}; methods of audio port objects are described below.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{newconfig}{}
  41 The return value is a new \dfn{audio configuration object}; methods of
  42 audio configuration objects are described below.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{queryparams}{device}
  46 The device argument is an integer.  The return value is a list of
  47 integers containing the data returned by \cfunction{ALqueryparams()}.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{getparams}{device, list}
  51 The \var{device} argument is an integer.  The list argument is a list
  52 such as returned by \function{queryparams()}; it is modified in place
  53 (!).
  54 \end{funcdesc}
  55
  56 \begin{funcdesc}{setparams}{device, list}
  57 The \var{device} argument is an integer.  The \var{list} argument is a
  58 list such as returned by \function{queryparams()}.
  59 \end{funcdesc}
  60
  61
  62 \subsection{Configuration Objects}
  63 \label{al-config-objects}
  64
  65 Configuration objects (returned by \function{newconfig()} have the
  66 following methods:
  67
  68 \begin{methoddesc}[audio configuration]{getqueuesize}{}
  69 Return the queue size.
  70 \end{methoddesc}
  71
  72 \begin{methoddesc}[audio configuration]{setqueuesize}{size}
  73 Set the queue size.
  74 \end{methoddesc}
  75
  76 \begin{methoddesc}[audio configuration]{getwidth}{}
  77 Get the sample width.
  78 \end{methoddesc}
  79
  80 \begin{methoddesc}[audio configuration]{setwidth}{width}
  81 Set the sample width.
  82 \end{methoddesc}
  83
  84 \begin{methoddesc}[audio configuration]{getchannels}{}
  85 Get the channel count.
  86 \end{methoddesc}
  87
  88 \begin{methoddesc}[audio configuration]{setchannels}{nchannels}
  89 Set the channel count.
  90 \end{methoddesc}
  91
  92 \begin{methoddesc}[audio configuration]{getsampfmt}{}
  93 Get the sample format.
  94 \end{methoddesc}
  95
  96 \begin{methoddesc}[audio configuration]{setsampfmt}{sampfmt}
  97 Set the sample format.
  98 \end{methoddesc}
  99
 100 \begin{methoddesc}[audio configuration]{getfloatmax}{}
 101 Get the maximum value for floating sample formats.
 102 \end{methoddesc}
 103
 104 \begin{methoddesc}[audio configuration]{setfloatmax}{floatmax}
 105 Set the maximum value for floating sample formats.
 106 \end{methoddesc}
 107
 108
 109 \subsection{Port Objects}
 110 \label{al-port-objects}
 111
 112 Port objects, as returned by \function{openport()}, have the following
 113 methods:
 114
 115 \begin{methoddesc}[audio port]{closeport}{}
 116 Close the port.
 117 \end{methoddesc}
 118
 119 \begin{methoddesc}[audio port]{getfd}{}
 120 Return the file descriptor as an int.
 121 \end{methoddesc}
 122
 123 \begin{methoddesc}[audio port]{getfilled}{}
 124 Return the number of filled samples.
 125 \end{methoddesc}
 126
 127 \begin{methoddesc}[audio port]{getfillable}{}
 128 Return the number of fillable samples.
 129 \end{methoddesc}
 130
 131 \begin{methoddesc}[audio port]{readsamps}{nsamples}
 132 Read a number of samples from the queue, blocking if necessary.
 133 Return the data as a string containing the raw data, (e.g., 2 bytes per
 134 sample in big-endian byte order (high byte, low byte) if you have set
 135 the sample width to 2 bytes).
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}[audio port]{writesamps}{samples}
 139 Write samples into the queue, blocking if necessary.  The samples are
 140 encoded as described for the \method{readsamps()} return value.
 141 \end{methoddesc}
 142
 143 \begin{methoddesc}[audio port]{getfillpoint}{}
 144 Return the `fill point'.
 145 \end{methoddesc}
 146
 147 \begin{methoddesc}[audio port]{setfillpoint}{fillpoint}
 148 Set the `fill point'.
 149 \end{methoddesc}
 150
 151 \begin{methoddesc}[audio port]{getconfig}{}
 152 Return a configuration object containing the current configuration of
 153 the port.
 154 \end{methoddesc}
 155
 156 \begin{methoddesc}[audio port]{setconfig}{config}
 157 Set the configuration from the argument, a configuration object.
 158 \end{methoddesc}
 159
 160 \begin{methoddesc}[audio port]{getstatus}{list}
 161 Get status information on last error.
 162 \end{methoddesc}
 163
 164
 165 \section{\module{AL} ---
 166          Constants used with the \module{al} module.}
 167 \declaremodule{standard}{AL}
 168
 169 \modulesynopsis{Constants used with the \module{al} module.}
 170
 171
 172 This module defines symbolic constants needed to use the built-in
 173 module \module{al} (see above); they are equivalent to those defined
 174 in the \C{} header file \code{<audio.h>} except that the name prefix
 175 \samp{AL_} is omitted.  Read the module source for a complete list of
 176 the defined names.  Suggested use:
 177
 178 \begin{verbatim}
 179 import al
 180 from AL import *
 181 \end{verbatim}