Doc/libal.tex

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