[Python-checkins] python/dist/src/Doc/lib libossaudiodev.tex,1.3,1.4

gward@users.sourceforge.net gward@users.sourceforge.net
Sun, 09 Mar 2003 18:09:53 -0800


Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv16191

Modified Files:
	libossaudiodev.tex 
Log Message:
Rewrite intro paragraphs and add a "See also" box for the link to the
official OSS docs.

Markup fixes: change \code{} variously to \function{}, \method{}, or
\constant{} as appropriate.


Index: libossaudiodev.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libossaudiodev.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** libossaudiodev.tex	10 Mar 2003 00:24:42 -0000	1.3
--- libossaudiodev.tex	10 Mar 2003 02:09:51 -0000	1.4
***************
*** 1,25 ****
  \section{\module{ossaudiodev} ---
!          Access to Open Sound System-compatible audio hardware}
  
  \declaremodule{builtin}{ossaudiodev}
!   \platform{OSS}
! \modulesynopsis{Access to OSS-compatible audio hardware.}
! 
! % I know FreeBSD uses OSS -- what about Net- and Open-?
! This module allows you to access the Open Sound System audio interface.
! The Open Sound System interface is present on Linux and FreeBSD.
! 
! This module provides a very "bare bones" wrapper over the IOCTLs used to
! access the audio hardware.  The best---albeit rather daunting---way to
! get a feel for the interface is from the Open Sound System official
! documentation:
  
! \url{http://www.opensound.com/pguide/oss.pdf}
  
! The module defines a number of constants which may be used to program
! the device.  These constants are the same as those defined in the C
! include file \code{<sys/soundcard.h>}.
  
! \code{ossaudiodev} defines the following variables and functions:
  
  \begin{excdesc}{error}
--- 1,26 ----
  \section{\module{ossaudiodev} ---
!          Access to OSS-compatible audio devices}
  
  \declaremodule{builtin}{ossaudiodev}
! \platform{Linux, FreeBSD}
! \modulesynopsis{Access to OSS-compatible audio devices.}
  
! % XXX OSS is standard for Linux and FreeBSD -- what about NetBSD?
! % OpenBSD?  others?
! This module allows you to access the OSS (Open Sound System) audio
! interface.  OSS is available for a wide range of open-source and
! commercial Unices, and is the standard audio interface for Linux (up to
! kernel 2.4) and FreeBSD.
  
! \begin{seealso}
! \seetitle[http://www.opensound.com/pguide/oss.pdf]
!          {Open Sound System Programmer's Guide}
!          {the official documentation for the OSS C API}
! \seetext{The module defines a large number of constants supplied by
!          the OSS device driver; see \file{<sys/soundcard.h>} on either
!          Linux or FreeBSD for a listing .}
! \end{seealso}
  
! \module{ossaudiodev} defines the following variables and functions:
  
  \begin{excdesc}{error}
***************
*** 32,36 ****
  object.  This object can then be used to do I/O on.  The \var{device}
  parameter is the audio device filename to use.  If it is not specified,
! this module first looks in the environment variable \code{AUDIODEV} for
  a device to use.  If not found, it falls back to \file{/dev/dsp}.
  
--- 33,37 ----
  object.  This object can then be used to do I/O on.  The \var{device}
  parameter is the audio device filename to use.  If it is not specified,
! this module first looks in the environment variable \envvar{AUDIODEV} for
  a device to use.  If not found, it falls back to \file{/dev/dsp}.
  
***************
*** 47,51 ****
  \var{device} parameter is the mixer device filename to use.  If it is
  not specified, this module first looks in the environment variable
! \code{MIXERDEV} for a device to use.  If not found, it falls back to
  \file{/dev/mixer}.  You may specify \code{'r'}, \code{'rw'} or
  \code{'w'} for \var{mode}; the default is \code{'r'}.
--- 48,52 ----
  \var{device} parameter is the mixer device filename to use.  If it is
  not specified, this module first looks in the environment variable
! \envvar{MIXERDEV} for a device to use.  If not found, it falls back to
  \file{/dev/mixer}.  You may specify \code{'r'}, \code{'rw'} or
  \code{'w'} for \var{mode}; the default is \code{'r'}.
***************
*** 60,66 ****
  sequence:
  \begin{enumerate}
! \item \code{setfmt()} to set the output format,
! \item \code{channels()} to set the number of channels, and
! \item \code{speed()} to set the sample rate.
  \end{enumerate}
  
--- 61,67 ----
  sequence:
  \begin{enumerate}
! \item \method{setfmt()} to set the output format,
! \item \method{channels()} to set the number of channels, and
! \item \method{speed()} to set the sample rate.
  \end{enumerate}
  
***************
*** 87,99 ****
  number of bytes written.  If the audio device is opened in blocking
  mode, the entire string is always written.  If the device is opened in
! nonblocking mode, some data may not be written---see \code{writeall}.
  \end{methoddesc}
  
  \begin{methoddesc}[audio device]{writeall}{data}
  Writes the entire Python string \var{data} to the audio device.  If the
! device is opened in blocking mode, behaves identially to \code{write};
! in nonblocking mode, waits until the device becomes available before
! feeding it more data.  Returns None, since the amount of data written is
! always equal to the amount of data supplied.
  \end{methoddesc}
  
--- 88,101 ----
  number of bytes written.  If the audio device is opened in blocking
  mode, the entire string is always written.  If the device is opened in
! nonblocking mode, some data may not be written---see
! \method{writeall()}.
  \end{methoddesc}
  
  \begin{methoddesc}[audio device]{writeall}{data}
  Writes the entire Python string \var{data} to the audio device.  If the
! device is opened in blocking mode, behaves identially to
! \method{write()}; in nonblocking mode, waits until the device becomes
! available before feeding it more data.  Returns \code{None}, since the
! amount of data written is always equal to the amount of data supplied.
  \end{methoddesc}
  
***************
*** 114,118 ****
  \lineii{AFMT_MU_LAW}
         {a logarithmic encoding.  This is the default format on
!         /dev/audio and is the format used by Sun .au files.}
  \lineii{AFMT_A_LAW}
         {a logarithmic encoding}
--- 116,120 ----
  \lineii{AFMT_MU_LAW}
         {a logarithmic encoding.  This is the default format on
!         \file{/dev/audio} and is the format used by Sun .au files.}
  \lineii{AFMT_A_LAW}
         {a logarithmic encoding}
***************
*** 136,149 ****
  \end{tableii}
  Most systems support only a subset of these formats.  Many devices only
! support \code{AFMT_U8}; the most common format used today is
! \code{AFMT_S16_LE}.
  \end{methoddesc}
  
  \begin{methoddesc}[audio device]{setfmt}{format}
  Used to set the current audio format to \var{format}---see
! \code{getfmts} for a list.  May also be used to return the current audio
! format---do this by passing an ``audio format'' of \code{AFMT_QUERY}.
! Returns the audio format that the device was set to, which may not be
! the requested format.
  \end{methoddesc}
  
--- 138,151 ----
  \end{tableii}
  Most systems support only a subset of these formats.  Many devices only
! support \constant{AFMT_U8}; the most common format used today is
! \constant{AFMT_S16_LE}.
  \end{methoddesc}
  
  \begin{methoddesc}[audio device]{setfmt}{format}
  Used to set the current audio format to \var{format}---see
! \method{getfmts()} for a list.  May also be used to return the current
! audio format---do this by passing an ``audio format'' of
! \constant{AFMT_QUERY}. Returns the audio format that the device was set
! to, which may not be the requested format.
  \end{methoddesc}
  
***************
*** 171,175 ****
  returns.  This also occurs when the sound device is closed.  The OSS
  documentation recommends simply closing and re-opening the device rather
! than using \code{sync}.
  \end{methoddesc}
  
--- 173,177 ----
  returns.  This also occurs when the sound device is closed.  The OSS
  documentation recommends simply closing and re-opening the device rather
! than using \method{sync()}.
  \end{methoddesc}
  
***************
*** 177,188 ****
  Immediately stops and playing or recording and returns the device to a
  state where it can accept commands.  The OSS documentation recommends
! closing and re-opening the device after calling \code{reset}.
  \end{methoddesc}
  
  \begin{methoddesc}[audio device]{post}
! To be used like a lightweight \code{sync}, the \code{post} IOCTL informs
! the audio device that there is a likely to be a pause in the audio
! output---i.e., after playing a spot sound effect, before waiting for
! user input, or before doing disk IO.
  \end{methoddesc}
  
--- 179,190 ----
  Immediately stops and playing or recording and returns the device to a
  state where it can accept commands.  The OSS documentation recommends
! closing and re-opening the device after calling \method{reset()}.
  \end{methoddesc}
  
  \begin{methoddesc}[audio device]{post}
! To be used like a lightweight \method{sync()}, the \method{post()}
! IOCTL informs the audio device that there is a likely to be a pause in
! the audio output---i.e., after playing a spot sound effect, before
! waiting for user input, or before doing disk I/O.
  \end{methoddesc}
  
***************
*** 192,199 ****
  Initialise the sound device in one method.  \var{samplerate},
  \var{channels} and \var{format} should be as specified in the
! \code{speed}, \code{channels} and \code{setfmt} methods.  If
! \var{emulate} is true, attempt to find the closest matching format
! instead, otherwise raise ValueError if the device does not support the
! format.  The default is to raise ValueError on unsupported formats.
  \end{methoddesc}
  
--- 194,202 ----
  Initialise the sound device in one method.  \var{samplerate},
  \var{channels} and \var{format} should be as specified in the
! \method{speed()}, \method{channels()} and \method{setfmt()}
! methods.  If \var{emulate} is true, attempt to find the closest matching
! format instead, otherwise raise ValueError if the device does not
! support the format.  The default is to raise ValueError on unsupported
! formats.
  \end{methoddesc}
  
***************
*** 230,236 ****
  This method returns a bitmask specifying the available mixer controls
  (``Control'' being a specific mixable ``channel'', such as
! \code{SOUND_MIXER_PCM} or \code{SOUND_MIXER_SYNTH}).  This
  bitmask indicates a subset of all available mixer channels---the
! \code{SOUND_MIXER_*} constants defined at module level.  To determine if,
  for example, the current mixer object supports a PCM mixer, use the
  following Python code:
--- 233,239 ----
  This method returns a bitmask specifying the available mixer controls
  (``Control'' being a specific mixable ``channel'', such as
! \constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}).  This
  bitmask indicates a subset of all available mixer channels---the
! \constant{SOUND_MIXER_*} constants defined at module level.  To determine if,
  for example, the current mixer object supports a PCM mixer, use the
  following Python code:
***************
*** 243,250 ****
  \end{verbatim}
  
! For most purposes, the \code{SOUND_MIXER_VOLUME} (Master volume) and
! \code{SOUND_MIXER_PCM} channels should suffice---but code that uses the
  mixer should be flexible when it comes to choosing sound channels.  On
! the Gravis Ultrasound, for example, \code{SOUND_MIXER_VOLUME} does not
  exist.
  \end{methoddesc}
--- 246,253 ----
  \end{verbatim}
  
! For most purposes, the \constant{SOUND_MIXER_VOLUME} (Master volume) and
! \constant{SOUND_MIXER_PCM} channels should suffice---but code that uses the
  mixer should be flexible when it comes to choosing sound channels.  On
! the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not
  exist.
  \end{methoddesc}
***************
*** 254,260 ****
  the corresponding channel is stereo; if it is unset, the channel is
  either monophonic or not supported by the mixer (use in combination with
! \function{channels} to determine which).
  
! See the code example for the \function{channels} function for an example
  of getting data from a bitmask.
  \end{methoddesc}
--- 257,263 ----
  the corresponding channel is stereo; if it is unset, the channel is
  either monophonic or not supported by the mixer (use in combination with
! \method{channels()} to determine which).
  
! See the code example for the \method{channels()} function for an example
  of getting data from a bitmask.
  \end{methoddesc}
***************
*** 262,266 ****
  \begin{methoddesc}[mixer device]{reccontrols}{}
  Returns a bitmask specifying the mixer controls that may be used to
! record.  See the code example for \function{controls} for an example of
  reading from a bitmask.
  \end{methoddesc}
--- 265,269 ----
  \begin{methoddesc}[mixer device]{reccontrols}{}
  Returns a bitmask specifying the mixer controls that may be used to
! record.  See the code example for \method{controls()} for an example of
  reading from a bitmask.
  \end{methoddesc}
***************
*** 268,272 ****
  \begin{methoddesc}[mixer device]{get}{channel}
  Returns the volume of a given mixer channel.  The returned volume is a
! 2-tuple of \code{left volume, right volume}.  Volumes are specified as
  numbers from 0 (silent) to 100 (full volume).  If the channel is
  monophonic, a 2-tuple is still returned, but both channel volumes are
--- 271,275 ----
  \begin{methoddesc}[mixer device]{get}{channel}
  Returns the volume of a given mixer channel.  The returned volume is a
! 2-tuple \code{(left_volume,right_volume)}.  Volumes are specified as
  numbers from 0 (silent) to 100 (full volume).  If the channel is
  monophonic, a 2-tuple is still returned, but both channel volumes are
***************
*** 277,281 ****
  
  \begin{methoddesc}[mixer device]{set}{channel, (left, right)}
! Sets the volume for a given mixer channel to \code{(left, right)}.
  \code{left} and \code{right} must be ints and between 0 (silent) and 100
  (full volume).  On success, the new volume is returned as a 2-tuple.
--- 280,284 ----
  
  \begin{methoddesc}[mixer device]{set}{channel, (left, right)}
! Sets the volume for a given mixer channel to \code{(left,right)}.
  \code{left} and \code{right} must be ints and between 0 (silent) and 100
  (full volume).  On success, the new volume is returned as a 2-tuple.