diff options
| -rw-r--r-- | Doc/Makefile | 1 | ||||
| -rw-r--r-- | Doc/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libcd.tex | 288 | ||||
| -rw-r--r-- | Doc/libcd.tex | 288 |
5 files changed, 579 insertions, 0 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index 5b43f89..57ec616 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -100,6 +100,7 @@ ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \ LIBFILES = lib.tex \ libal.tex libaifc.tex libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \ libbltin.tex \ +libcd.tex \ libcgi.tex libcopy.tex libctb.tex libcrypto.tex \ libdbm.tex \ libexcs.tex \ diff --git a/Doc/lib.tex b/Doc/lib.tex index 3a25342..8d6db1c 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -135,6 +135,7 @@ language. \input{libsgi} % SGI IRIX ONLY \input{libal} %\input{libaudio} +\input{libcd} \input{libfl} \input{libfm} \input{libgl} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 3a25342..8d6db1c 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -135,6 +135,7 @@ language. \input{libsgi} % SGI IRIX ONLY \input{libal} %\input{libaudio} +\input{libcd} \input{libfl} \input{libfm} \input{libgl} diff --git a/Doc/lib/libcd.tex b/Doc/lib/libcd.tex new file mode 100644 index 0000000..814fb1b --- /dev/null +++ b/Doc/lib/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} 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} |