[Python-checkins] python/dist/src/Doc/lib libossaudiodev.tex, 1.11, 1.12

Tue May 4 21:36:19 EDT 2004

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11574/lib
Modified Files:
	libossaudiodev.tex 
Log Message:
SF #814606: merge from release23-maint branch: clarify/cleanup
mixer docs; trim \platform{}, add \versionadded{}.
Index: libossaudiodev.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libossaudiodev.tex,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** libossaudiodev.tex	30 Sep 2003 20:00:43 -0000	1.11
--- libossaudiodev.tex	5 May 2004 01:36:16 -0000	1.12
***************
*** 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}