Doc/lib/libal.tex

   1 \section{\module{al} ---
   2          Audio functions on the SGI}
   3
   4 \declaremodule{builtin}{al}
   5   \platform{IRIX}
   6 \modulesynopsis{Audio functions on the SGI.}
   7
   8
   9 This module provides access to the audio facilities of the SGI Indy
  10 and Indigo workstations.  See section 3A of the IRIX man pages for
  11 details.  You'll need to read those man pages to understand what these
  12 functions do!  Some of the functions are not available in IRIX
  13 releases before 4.0.5.  Again, see the manual to check whether a
  14 specific function is available on your platform.
  15
  16 All functions and methods defined in this module are equivalent to
  17 the C functions with \samp{AL} prefixed to their name.
  18
  19 Symbolic constants from the C header file \code{<audio.h>} are
  20 defined in the standard module
  21 \refmodule[al-constants]{AL}\refstmodindex{AL}, see below.
  22
  23 \warning{The current version of the audio library may dump core
  24 when bad argument values are passed rather than returning an error
  25 status.  Unfortunately, since the precise circumstances under which
  26 this may happen are undocumented and hard to check, the Python
  27 interface can provide no protection against this kind of problems.
  28 (One example is specifying an excessive queue size --- there is no
  29 documented upper limit.)}
  30
  31 The module defines the following functions:
  32
  33
  34 \begin{funcdesc}{openport}{name, direction\optional{, config}}
  35 The name and direction arguments are strings.  The optional
  36 \var{config} argument is a configuration object as returned by
  37 \function{newconfig()}.  The return value is an \dfn{audio port
  38 object}; methods of audio port objects are described below.
  39 \end{funcdesc}
  40
  41 \begin{funcdesc}{newconfig}{}
  42 The return value is a new \dfn{audio configuration object}; methods of
  43 audio configuration objects are described below.
  44 \end{funcdesc}
  45
  46 \begin{funcdesc}{queryparams}{device}
  47 The device argument is an integer.  The return value is a list of
  48 integers containing the data returned by \cfunction{ALqueryparams()}.
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{getparams}{device, list}
  52 The \var{device} argument is an integer.  The list argument is a list
  53 such as returned by \function{queryparams()}; it is modified in place
  54 (!).
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{setparams}{device, list}
  58 The \var{device} argument is an integer.  The \var{list} argument is a
  59 list such as returned by \function{queryparams()}.
  60 \end{funcdesc}
  61
  62
  63 \subsection{Configuration Objects \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 \label{al-port-objects}}
 110
 111 Port objects, as returned by \function{openport()}, have the following
 112 methods:
 113
 114 \begin{methoddesc}[audio port]{closeport}{}
 115 Close the port.
 116 \end{methoddesc}
 117
 118 \begin{methoddesc}[audio port]{getfd}{}
 119 Return the file descriptor as an int.
 120 \end{methoddesc}
 121
 122 \begin{methoddesc}[audio port]{getfilled}{}
 123 Return the number of filled samples.
 124 \end{methoddesc}
 125
 126 \begin{methoddesc}[audio port]{getfillable}{}
 127 Return the number of fillable samples.
 128 \end{methoddesc}
 129
 130 \begin{methoddesc}[audio port]{readsamps}{nsamples}
 131 Read a number of samples from the queue, blocking if necessary.
 132 Return the data as a string containing the raw data, (e.g., 2 bytes per
 133 sample in big-endian byte order (high byte, low byte) if you have set
 134 the sample width to 2 bytes).
 135 \end{methoddesc}
 136
 137 \begin{methoddesc}[audio port]{writesamps}{samples}
 138 Write samples into the queue, blocking if necessary.  The samples are
 139 encoded as described for the \method{readsamps()} return value.
 140 \end{methoddesc}
 141
 142 \begin{methoddesc}[audio port]{getfillpoint}{}
 143 Return the `fill point'.
 144 \end{methoddesc}
 145
 146 \begin{methoddesc}[audio port]{setfillpoint}{fillpoint}
 147 Set the `fill point'.
 148 \end{methoddesc}
 149
 150 \begin{methoddesc}[audio port]{getconfig}{}
 151 Return a configuration object containing the current configuration of
 152 the port.
 153 \end{methoddesc}
 154
 155 \begin{methoddesc}[audio port]{setconfig}{config}
 156 Set the configuration from the argument, a configuration object.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}[audio port]{getstatus}{list}
 160 Get status information on last error.
 161 \end{methoddesc}
 162
 163
 164 \section{\module{AL} ---
 165          Constants used with the \module{al} module}
 166
 167 \declaremodule[al-constants]{standard}{AL}
 168   \platform{IRIX}
 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 \refmodule{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}