New documentation on the CD module.

1 files changed, 288 insertions, 0 deletions

diff --git a/Doc/libcd.tex b/Doc/libcd.tex
new file mode 100644
index 0000000..814fb1b
--- /dev/null
+++ b/Doc/libcd.tex
@@ -0,0 +1,288 @@
+\section{Built-in Module \sectcode{cd}}
+\bimodindex{cd}
+
+This module provides an interface to the Silicon Graphics CD library.
+It is available only on Silicon Graphics systems.
+
+The way the library works is as follows.  A program opens the CD-ROM
+device with \code{cd.open()} and creates a parser to parse the data
+from the CD with \code{cd.createparser()}.  The object returned by
+\code{cd.open()} can be used to read data from the CD, but also to get
+status information for the CD-ROM device, and to get information about
+the CD, such as the table of contents.  Data from the CD is passed to
+the parser, which parses the frames, and calls any callback
+functions that have previously been added.
+
+An audio CD is divided into \dfn{tracks} or \dfn{programs} (the terms
+are used interchangeably).  Tracks can be subdivided into
+\dfn{indices}.  An audio CD contains a \dfn{table of contents} which
+gives the starts of the tracks on the CD.  Index 0 is usually the
+pause before the start of a track.  The start of the track as given by
+the table of contents is normally the start of index 1.
+
+Positions on a CD can be represented in two ways.  Either a frame
+number or a tuple of three values, minutes, seconds and frames.  Most
+functions use the latter representation.  Positions can be both
+relative to the beginning of the CD, and to the beginning of the
+track.
+
+Module \code{cd} defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module cd)}
+\begin{funcdesc}{createparser}{}
+Create and return an opaque parser object.  The methods of the parser
+object are described below.
+\end{funcdesc}
+
+\begin{funcdesc}{msftoframe}{min\, sec\, frame}
+Converts a \code{(minutes, seconds, frames)} triple representing time
+in absolute time code into the corresponding CD frame number.
+\end{funcdesc}
+
+\begin{funcdesc}{open}{\optional{device\optional{\, mode}}}
+Open the CD-ROM device.  The return value is an opaque player object;
+methods of the player object are described below.  The device is the
+name of the SCSI device file, e.g. /dev/scsi/sc0d4l0, or \code{None}.
+If omited or \code{None}, the hardware inventory is consulted to
+locate a CD-ROM drive.  The \code{mode}, if not omited, should be the
+string 'r'.
+\end{funcdesc}
+
+The module defines the following variables:
+
+\begin{datadesc}{error}
+Exception raised on various errors.
+\end{datadesc}
+
+\begin{datadesc}{DATASIZE}
+The size of one frame's worth of audio data.  This is the size of the
+audio data as passed to the callback of type \code{audio}.
+\end{datadesc}
+
+\begin{datadesc}{BLOCKSIZE}
+The size of one uninterpreted frame of audio data.
+\end{datadesc}
+
+The following variables are states as returned by \code{getstatus}:
+
+\begin{datadesc}{READY}
+The drive is ready for operation loaded with an audio CD.
+\end{datadesc}
+
+\begin{datadesc}{NODISC}
+The drive does not have a CD loaded.
+\end{datadesc}
+
+\begin{datadesc}{CDROM}
+The drive is loaded with a CD-ROM.  Subsequent play or read operations
+will return I/O errors.
+\end{datadesc}
+
+\begin{datadesc}{ERROR}
+An error aoocurred while trying to read the disc or its table of
+contents.
+\end{datadesc}
+
+\begin{datadesc}{PLAYING}
+The drive is in CD player mode playing an audio CD through its audio
+jacks.
+\end{datadesc}
+
+\begin{datadesc}{PAUSED}
+The drive is in CD layer mode with play paused.
+\end{datadesc}
+
+\begin{datadesc}{STILL}
+The equivalent of \code{PAUSED} on older (non 3301) model Toshiba
+CD-ROM drives.  Such drives have never been shipped by SGI.
+\end{datadesc}
+
+Player objects (returned by \code{cd.open()}) have the following
+methods:
+
+\renewcommand{\indexsubitem}{(CD player object method)}
+\begin{funcdesc}{allowremoval}{}
+Unlocks the eject button on the CD-ROM drive permitting the user to
+eject the caddy if desired.
+\end{funcdesc}
+
+\begin{funcdesc}{bestreadsize}{}
+Returns the best value to use for the \code{num_frames} parameter of
+the \code{readda} method.  Best is defined as the value that permits a
+continuous flow of data from the CD-ROM drive.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+Frees the resources associated with the player object.  After calling
+\code{close}, the methods of the object should no longer be used.
+\end{funcdesc}
+
+\begin{funcdesc}{eject}{}
+Ejects the caddy from the CD-ROM drive.
+\end{funcdesc}
+
+\begin{funcdesc}{getstatus}{}
+Returns information pertaining to the current state of the CD-ROM
+drive.  The returned information is a tuple with the following values:
+\code{state}, \code{track}, \code{rtime}, \code{atime}, \code{ttime},
+\code{first}, \code{last}, \code{scsi_audio}, \code{cur_block}.
+\code{rtime} is the time relative to the start of the current track;
+\code{atime} is the time relative to the beginning of the disc;
+\code{ttime} is the total time on the disc.  For more information on
+the meaning of the values, see the manual for CDgetstatus.
+The value of \code{state} is one of the following: \code{cd.ERROR},
+\code{cd.NODISC}, \code{cd.READY}, \code{cd.PLAYING},
+\code{cd.PAUSED}, \code{cd.STILL}, or \code{cd.CDROM}.
+\end{funcdesc}
+
+\begin{funcdesc}{gettrackinfo}{track}
+Returns information about the specified track.  The returned
+information is a tuple consisting of two elements, the start time of
+the track and the duration of the track.
+\end{funcdesc}
+
+\begin{funcdesc}{msftoblock}{min\, sec\, frame}
+Converts a minutes, seconds, frames triple representing a time in
+absolute time code into the corresponding logical block number for the
+given CD-ROM drive.  You should use \code{cd.msftoframe()} rather than
+\code{msftoblock()} for comparing times.  The logical block number
+differs from the frame number by an offset required by certain CD-ROM
+drives.
+\end{funcdesc}
+
+\begin{funcdesc}{play}{start\, play}
+Starts playback of an audio CD in the CD-ROM drive at the specified
+track.  The audio output appears on the CD-ROM drive's headphone and
+audio jacks (if fitted).  Play stops at the end of the disc.
+\code{start} is the number of the track at which to start playing the
+CD; if \code{play} is 0, the CD will be set to an initial paused
+state.  The method \code{togglepause()} can then be used to commence
+play.
+\end{funcdesc}
+
+\begin{funcdesc}{playabs}{min\, sec\, frame\, play}
+Like \code{play()}, except that the start is given in minutes,
+seconds, frames instead of a track number.
+\end{funcdesc}
+
+\begin{funcdesc}{playtrack}{start\, play}
+Like \code{play()}, except that playing stops at the end of the track.
+\end{funcdesc}
+
+\begin{funcdesc}{playtrackabs}{track\, min\, sec\, frame\, play}
+Like \code{play()}, except that playing begins at the spcified
+absolute time and ends at the end of the specified track.
+\end{funcdesc}
+
+\begin{funcdesc}{preventremoval}{}
+Locks the eject button on the CD-ROM drive thus preventing the user
+from arbitrarily ejecting the caddy.
+\end{funcdesc}
+
+\begin{funcdesc}{readda}{num_frames}
+Reads the specified number of frames from an audio CD mounted in the
+CD-ROM drive.  The return value is a string representing the audio
+frames.  This string can be passed unaltered to the \code{parseframe}
+method of the parser object.
+\end{funcdesc}
+
+\begin{funcdesc}{seek}{min\, sec\, frame}
+Sets the pointer that indicates the starting point of the next read of
+digital audio data from a CD-ROM.  The pointer is set to an absolute
+time code location specified in minutes, seconds, and frames.  The
+return value is the logical block number to which the pointer has been
+set.
+\end{funcdesc}
+
+\begin{funcdesc}{seekblock}{block}
+Sets the pointer that indicates the starting point of the next read of
+digital audio data from a CD-ROM.  The pointer is set to the specified
+logical block number.  The return value is the logical block number to
+which the pointer has been set.
+\end{funcdesc}
+
+\begin{funcdesc}{seektrack}{track}
+Sets the pointer that indicates the starting point of the next read of
+digital audio data from a CD-ROM.  The pointer is set to the specified
+track.  The return value is the logical block number to which the
+pointer has been set.
+\end{funcdesc}
+
+\begin{funcdesc}{stop}{}
+Stops the current playing operation.
+\end{funcdesc}
+
+\begin{funcdesc}{togglepause}{}
+Pauses the CD if it is playing, and makes it play if it is paused.
+\end{funcdesc}
+
+Parser objects (returned by \code{cd.createparser()}) have the
+following methods:
+
+\begin{funcdesc}{addcallback}{type\, func\, arg}
+Adds a callback for the parser.  The parser has callbacks for eight
+different types of data in the digital audio data stream.  The
+callback is called as follows \code{func(arg, type, data)}.
+\code{arg} is the user supplied argument, \code{type} is the
+particular type of callback, and \code{data} is the data returned for
+this \code{type} of callback.  The type of the data depends on the
+\code{type} of callback as follows.
+\begin{datadesc}{audio}
+The argument is a string which can be passed unmodified to
+\code{al.writesamps}
+\end{datadesc}
+\begin{datadesc}{pnum}
+The argument is an integer giving the program (track) number.
+\end{datadesc}
+\begin{datadesc}{index}
+The argument is an integer giving the index number.
+\end{datadesc}
+\begin{datadesc}{ptime}
+The argument is a tuple consisting of the program time in minutes,
+seconds, and frames.
+\end{datadesc}
+\begin{datadesc}{atime}
+The argument is a tuple consisting of the absolute time in minutes,
+seconds, and frames.
+\end{datadesc}
+\begin{datadesc}{catalog}
+The argument is a string of 13 characters, giving the catalog number
+of the CD.
+\end{datadesc}
+\begin{datadesc}{ident}
+The argument is a string of 12 characters, giving the ISRC
+identification number of the recording.  The string consists of two
+characters country code, three characters owner code, two characters
+giving the year, and five characters giving a serial number.
+\end{datadesc}
+\begin{datadesc}{control}
+The argument is an integer giving the control bits from the CD subcode
+data.
+\end{datadesc}
+\end{funcdesc}
+
+\begin{funcdesc}{deleteparser}{}
+Deletes the parser and frees the memory it was using.  The object
+should not be used after this call.  This call is done automatically
+when the last reference to the object is removed.
+\end{funcdesc}
+
+\begin{funcdesc}{parseframe}{frame}
+Parses one or more frames of digital audio data from a CD such as
+returned by \code{readda}.  It determines which subcodes are present
+in the data.  If these subcodes have changed since the last frame,
+then \code{parseframe} executes a callback of the appropriate type
+passing to it the subcode data found in the frame.
+Unlike the C function, more than one frame of digital audio data can
+be passed to this method.
+\end{funcdesc}
+
+\begin{funcdesc}{removecallback}{type}
+Removes the callback for the given \code{type}.
+\end{funcdesc}
+
+\begin{funcdesc}{resetparser}{}
+Resets the fields of the parser used for tracking subcodes to an
+initial state.  \code{resetparser} should be called after the disc has
+been changed.
+\end{funcdesc}