[Python-checkins] python/dist/src/Doc/lib libossaudiodev.tex, 1.10.10.1, 1.10.10.2

Tue May 4 21:33:24 EDT 2004

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11085

Modified Files:
      Tag: release23-maint
	libossaudiodev.tex 
Log Message:
SF #814606: fix mixer docs to talk about "controls", not "channels".
General cleanup of mixer docs, especially clarifying which exceptions
  are thrown when.
Trim \platform{}, add \versionadded{}.

Index: libossaudiodev.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libossaudiodev.tex,v
retrieving revision 1.10.10.1
retrieving revision 1.10.10.2
diff -C2 -d -r1.10.10.1 -r1.10.10.2
*** libossaudiodev.tex	30 Sep 2003 20:00:20 -0000	1.10.10.1
--- libossaudiodev.tex	5 May 2004 01:33:21 -0000	1.10.10.2
***************
*** 3,9 ****

  \declaremodule{builtin}{ossaudiodev}
! \platform{Linux, FreeBSD, maybe other Unix-like systems}
  \modulesynopsis{Access to OSS-compatible audio devices.}

  This module allows you to access the OSS (Open Sound System) audio
  interface.  OSS is available for a wide range of open-source and
--- 3,11 ----

  \declaremodule{builtin}{ossaudiodev}
! \platform{Linux, FreeBSD}
  \modulesynopsis{Access to OSS-compatible audio devices.}

+ \versionadded{2.3}
+ 
  This module allows you to access the OSS (Open Sound System) audio
  interface.  OSS is available for a wide range of open-source and
***************
*** 290,294 ****
  \subsection{Mixer Device Objects \label{mixer-device-objects}}

! File-like interface

  \begin{methoddesc}[mixer device]{close}{}
--- 292,296 ----
  \subsection{Mixer Device Objects \label{mixer-device-objects}}

! The mixer object provides two file-like methods:

  \begin{methoddesc}[mixer device]{close}{}
***************
*** 301,305 ****
  \end{methoddesc}

! Mixer interface

  \begin{methoddesc}[mixer device]{controls}{}
--- 303,307 ----
  \end{methoddesc}

! The remaining methods are specific to audio mixing:

  \begin{methoddesc}[mixer device]{controls}{}
***************
*** 307,311 ****
  (``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
--- 309,313 ----
  (``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 controls---the
  \constant{SOUND_MIXER_*} constants defined at module level.  To determine if,
  for example, the current mixer object supports a PCM mixer, use the
***************
*** 314,325 ****
  \begin{verbatim}
  mixer=ossaudiodev.openmixer()
! if mixer.channels() & (1 << ossaudiodev.SOUND_MIXER_PCM):
! 	# PCM is supported
! 	<code>
  \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.
--- 316,327 ----
  \begin{verbatim}
  mixer=ossaudiodev.openmixer()
! if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
!     # PCM is supported
!     ... code ...
  \end{verbatim}

! For most purposes, the \constant{SOUND_MIXER_VOLUME} (master volume) and
! \constant{SOUND_MIXER_PCM} controls should suffice---but code that uses the
! mixer should be flexible when it comes to choosing mixer controls.  On
  the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not
  exist.
***************
*** 327,336 ****

  \begin{methoddesc}[mixer device]{stereocontrols}{}
! Returns a bitmask indicating stereo mixer channels.  If a bit is set,
! 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}
--- 329,338 ----

  \begin{methoddesc}[mixer device]{stereocontrols}{}
! Returns a bitmask indicating stereo mixer controls.  If a bit is set,
! the corresponding control is stereo; if it is unset, the control is
  either monophonic or not supported by the mixer (use in combination with
! \method{controls()} to determine which).

! See the code example for the \method{controls()} function for an example
  of getting data from a bitmask.
  \end{methoddesc}
***************
*** 342,357 ****
  \end{methoddesc}

! \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
  the same.

! If an unknown channel is specified, \exception{error} is raised.
  \end{methoddesc}

! \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.
--- 344,360 ----
  \end{methoddesc}

! \begin{methoddesc}[mixer device]{get}{control}
! Returns the volume of a given mixer control.  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 control is
! monophonic, a 2-tuple is still returned, but both volumes are
  the same.

! Raises \exception{OSSAudioError} if an invalid control was is specified,
! or \exception{IOError} if an unsupported control is specified.
  \end{methoddesc}

! \begin{methoddesc}[mixer device]{set}{control, (left, right)}
! Sets the volume for a given mixer control 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.
***************
*** 359,369 ****
  because of the limited resolution of some soundcard's mixers.

! Raises \exception{IOError} if an invalid mixer channel was specified;
! \exception{TypeError} if the argument format was incorrect, and
! \exception{error} if the specified volumes were out-of-range.
  \end{methoddesc}

  \begin{methoddesc}[mixer device]{get_recsrc}{}
! This method returns a bitmask indicating which channel or channels are
  currently being used as a recording source.
  \end{methoddesc}
--- 362,371 ----
  because of the limited resolution of some soundcard's mixers.

! Raises \exception{OSSAudioError} if an invalid mixer control was
! specified, or if the specified volumes were out-of-range.
  \end{methoddesc}

  \begin{methoddesc}[mixer device]{get_recsrc}{}
! This method returns a bitmask indicating which control(s) are
  currently being used as a recording source.
  \end{methoddesc}