Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit ffd6de1

Browse files
sjoerdmullendersjoerdmullender
committed
New documentation on the CD module.
1 parent 3caad8c commit ffd6de1

5 files changed

Lines changed: 579 additions & 0 deletions

File tree

‎Doc/Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \
100100
LIBFILES = lib.tex \
101101
libal.tex libaifc.tex libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \
102102
libbltin.tex \
103+
libcd.tex \
103104
libcgi.tex libcopy.tex libctb.tex libcrypto.tex \
104105
libdbm.tex \
105106
libexcs.tex \

‎Doc/lib.tex‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,7 @@
135135
\input{libsgi} % SGI IRIX ONLY
136136
\input{libal}
137137
%\input{libaudio}
138+
\input{libcd}
138139
\input{libfl}
139140
\input{libfm}
140141
\input{libgl}

‎Doc/lib/lib.tex‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,7 @@
135135
\input{libsgi} % SGI IRIX ONLY
136136
\input{libal}
137137
%\input{libaudio}
138+
\input{libcd}
138139
\input{libfl}
139140
\input{libfm}
140141
\input{libgl}

‎Doc/lib/libcd.tex‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
\section{Built-in Module \sectcode{cd}}
2+
\bimodindex{cd}
3+
4+
This module provides an interface to the Silicon Graphics CD library.
5+
It is available only on Silicon Graphics systems.
6+
7+
The way the library works is as follows. A program opens the CD-ROM
8+
device with \code{cd.open()} and creates a parser to parse the data
9+
from the CD with \code{cd.createparser()}. The object returned by
10+
\code{cd.open()} can be used to read data from the CD, but also to get
11+
status information for the CD-ROM device, and to get information about
12+
the CD, such as the table of contents. Data from the CD is passed to
13+
the parser, which parses the frames, and calls any callback
14+
functions that have previously been added.
15+
16+
An audio CD is divided into \dfn{tracks} or \dfn{programs} (the terms
17+
are used interchangeably). Tracks can be subdivided into
18+
\dfn{indices}. An audio CD contains a \dfn{table of contents} which
19+
gives the starts of the tracks on the CD. Index 0 is usually the
20+
pause before the start of a track. The start of the track as given by
21+
the table of contents is normally the start of index 1.
22+
23+
Positions on a CD can be represented in two ways. Either a frame
24+
number or a tuple of three values, minutes, seconds and frames. Most
25+
functions use the latter representation. Positions can be both
26+
relative to the beginning of the CD, and to the beginning of the
27+
track.
28+
29+
Module \code{cd} defines the following functions:
30+
31+
\renewcommand{\indexsubitem}{(in module cd)}
32+
\begin{funcdesc}{createparser}{}
33+
Create and return an opaque parser object. The methods of the parser
34+
object are described below.
35+
\end{funcdesc}
36+
37+
\begin{funcdesc}{msftoframe}{min\, sec\, frame}
38+
Converts a \code{(minutes, seconds, frames)} triple representing time
39+
in absolute time code into the corresponding CD frame number.
40+
\end{funcdesc}
41+
42+
\begin{funcdesc}{open}{\optional{device\optional{\, mode}}}
43+
Open the CD-ROM device. The return value is an opaque player object;
44+
methods of the player object are described below. The device is the
45+
name of the SCSI device file, e.g. /dev/scsi/sc0d4l0, or \code{None}.
46+
If omited or \code{None}, the hardware inventory is consulted to
47+
locate a CD-ROM drive. The \code{mode}, if not omited, should be the
48+
string 'r'.
49+
\end{funcdesc}
50+
51+
The module defines the following variables:
52+
53+
\begin{datadesc}{error}
54+
Exception raised on various errors.
55+
\end{datadesc}
56+
57+
\begin{datadesc}{DATASIZE}
58+
The size of one frame's worth of audio data. This is the size of the
59+
audio data as passed to the callback of type \code{audio}.
60+
\end{datadesc}
61+
62+
\begin{datadesc}{BLOCKSIZE}
63+
The size of one uninterpreted frame of audio data.
64+
\end{datadesc}
65+
66+
The following variables are states as returned by \code{getstatus}:
67+
68+
\begin{datadesc}{READY}
69+
The drive is ready for operation loaded with an audio CD.
70+
\end{datadesc}
71+
72+
\begin{datadesc}{NODISC}
73+
The drive does not have a CD loaded.
74+
\end{datadesc}
75+
76+
\begin{datadesc}{CDROM}
77+
The drive is loaded with a CD-ROM. Subsequent play or read operations
78+
will return I/O errors.
79+
\end{datadesc}
80+
81+
\begin{datadesc}{ERROR}
82+
An error aoocurred while trying to read the disc or its table of
83+
contents.
84+
\end{datadesc}
85+
86+
\begin{datadesc}{PLAYING}
87+
The drive is in CD player mode playing an audio CD through its audio
88+
jacks.
89+
\end{datadesc}
90+
91+
\begin{datadesc}{PAUSED}
92+
The drive is in CD layer mode with play paused.
93+
\end{datadesc}
94+
95+
\begin{datadesc}{STILL}
96+
The equivalent of \code{PAUSED} on older (non 3301) model Toshiba
97+
CD-ROM drives. Such drives have never been shipped by SGI.
98+
\end{datadesc}
99+
100+
Player objects (returned by \code{cd.open()}) have the following
101+
methods:
102+
103+
\renewcommand{\indexsubitem}{(CD player object method)}
104+
\begin{funcdesc}{allowremoval}{}
105+
Unlocks the eject button on the CD-ROM drive permitting the user to
106+
eject the caddy if desired.
107+
\end{funcdesc}
108+
109+
\begin{funcdesc}{bestreadsize}{}
110+
Returns the best value to use for the \code{num_frames} parameter of
111+
the \code{readda} method. Best is defined as the value that permits a
112+
continuous flow of data from the CD-ROM drive.
113+
\end{funcdesc}
114+
115+
\begin{funcdesc}{close}{}
116+
Frees the resources associated with the player object. After calling
117+
\code{close}, the methods of the object should no longer be used.
118+
\end{funcdesc}
119+
120+
\begin{funcdesc}{eject}{}
121+
Ejects the caddy from the CD-ROM drive.
122+
\end{funcdesc}
123+
124+
\begin{funcdesc}{getstatus}{}
125+
Returns information pertaining to the current state of the CD-ROM
126+
drive. The returned information is a tuple with the following values:
127+
\code{state}, \code{track}, \code{rtime}, \code{atime}, \code{ttime},
128+
\code{first}, \code{last}, \code{scsi_audio}, \code{cur_block}.
129+
\code{rtime} is the time relative to the start of the current track;
130+
\code{atime} is the time relative to the beginning of the disc;
131+
\code{ttime} is the total time on the disc. For more information on
132+
the meaning of the values, see the manual for CDgetstatus.
133+
The value of \code{state} is one of the following: \code{cd.ERROR},
134+
\code{cd.NODISC}, \code{cd.READY}, \code{cd.PLAYING},
135+
\code{cd.PAUSED}, \code{cd.STILL}, or \code{cd.CDROM}.
136+
\end{funcdesc}
137+
138+
\begin{funcdesc}{gettrackinfo}{track}
139+
Returns information about the specified track. The returned
140+
information is a tuple consisting of two elements, the start time of
141+
the track and the duration of the track.
142+
\end{funcdesc}
143+
144+
\begin{funcdesc}{msftoblock}{min\, sec\, frame}
145+
Converts a minutes, seconds, frames triple representing a time in
146+
absolute time code into the corresponding logical block number for the
147+
given CD-ROM drive. You should use \code{cd.msftoframe()} rather than
148+
\code{msftoblock()} for comparing times. The logical block number
149+
differs from the frame number by an offset required by certain CD-ROM
150+
drives.
151+
\end{funcdesc}
152+
153+
\begin{funcdesc}{play}{start\, play}
154+
Starts playback of an audio CD in the CD-ROM drive at the specified
155+
track. The audio output appears on the CD-ROM drive's headphone and
156+
audio jacks (if fitted). Play stops at the end of the disc.
157+
\code{start} is the number of the track at which to start playing the
158+
CD; if \code{play} is 0, the CD will be set to an initial paused
159+
state. The method \code{togglepause()} can then be used to commence
160+
play.
161+
\end{funcdesc}
162+
163+
\begin{funcdesc}{playabs}{min\, sec\, frame\, play}
164+
Like \code{play()}, except that the start is given in minutes,
165+
seconds, frames instead of a track number.
166+
\end{funcdesc}
167+
168+
\begin{funcdesc}{playtrack}{start\, play}
169+
Like \code{play()}, except that playing stops at the end of the track.
170+
\end{funcdesc}
171+
172+
\begin{funcdesc}{playtrackabs}{track\, min\, sec\, frame\, play}
173+
Like \code{play()}, except that playing begins at the spcified
174+
absolute time and ends at the end of the specified track.
175+
\end{funcdesc}
176+
177+
\begin{funcdesc}{preventremoval}{}
178+
Locks the eject button on the CD-ROM drive thus preventing the user
179+
from arbitrarily ejecting the caddy.
180+
\end{funcdesc}
181+
182+
\begin{funcdesc}{readda}{num_frames}
183+
Reads the specified number of frames from an audio CD mounted in the
184+
CD-ROM drive. The return value is a string representing the audio
185+
frames. This string can be passed unaltered to the \code{parseframe}
186+
method of the parser object.
187+
\end{funcdesc}
188+
189+
\begin{funcdesc}{seek}{min\, sec\, frame}
190+
Sets the pointer that indicates the starting point of the next read of
191+
digital audio data from a CD-ROM. The pointer is set to an absolute
192+
time code location specified in minutes, seconds, and frames. The
193+
return value is the logical block number to which the pointer has been
194+
set.
195+
\end{funcdesc}
196+
197+
\begin{funcdesc}{seekblock}{block}
198+
Sets the pointer that indicates the starting point of the next read of
199+
digital audio data from a CD-ROM. The pointer is set to the specified
200+
logical block number. The return value is the logical block number to
201+
which the pointer has been set.
202+
\end{funcdesc}
203+
204+
\begin{funcdesc}{seektrack}{track}
205+
Sets the pointer that indicates the starting point of the next read of
206+
digital audio data from a CD-ROM. The pointer is set to the specified
207+
track. The return value is the logical block number to which the
208+
pointer has been set.
209+
\end{funcdesc}
210+
211+
\begin{funcdesc}{stop}{}
212+
Stops the current playing operation.
213+
\end{funcdesc}
214+
215+
\begin{funcdesc}{togglepause}{}
216+
Pauses the CD if it is playing, and makes it play if it is paused.
217+
\end{funcdesc}
218+
219+
Parser objects (returned by \code{cd.createparser()}) have the
220+
following methods:
221+
222+
\begin{funcdesc}{addcallback}{type\, func\, arg}
223+
Adds a callback for the parser. The parser has callbacks for eight
224+
different types of data in the digital audio data stream. The
225+
callback is called as follows \code{func(arg, type, data)}.
226+
\code{arg} is the user supplied argument, \code{type} is the
227+
particular type of callback, and \code{data} is the data returned for
228+
this \code{type} of callback. The type of the data depends on the
229+
\code{type} of callback as follows.
230+
\begin{datadesc}{audio}
231+
The argument is a string which can be passed unmodified to
232+
\code{al.writesamps}
233+
\end{datadesc}
234+
\begin{datadesc}{pnum}
235+
The argument is an integer giving the program (track) number.
236+
\end{datadesc}
237+
\begin{datadesc}{index}
238+
The argument is an integer giving the index number.
239+
\end{datadesc}
240+
\begin{datadesc}{ptime}
241+
The argument is a tuple consisting of the program time in minutes,
242+
seconds, and frames.
243+
\end{datadesc}
244+
\begin{datadesc}{atime}
245+
The argument is a tuple consisting of the absolute time in minutes,
246+
seconds, and frames.
247+
\end{datadesc}
248+
\begin{datadesc}{catalog}
249+
The argument is a string of 13 characters, giving the catalog number
250+
of the CD.
251+
\end{datadesc}
252+
\begin{datadesc}{ident}
253+
The argument is a string of 12 characters, giving the ISRC
254+
identification number of the recording. The string consists of two
255+
characters country code, three characters owner code, two characters
256+
giving the year, and five characters giving a serial number.
257+
\end{datadesc}
258+
\begin{datadesc}{control}
259+
The argument is an integer giving the control bits from the CD subcode
260+
data.
261+
\end{datadesc}
262+
\end{funcdesc}
263+
264+
\begin{funcdesc}{deleteparser}{}
265+
Deletes the parser and frees the memory it was using. The object
266+
should not be used after this call. This call is done automatically
267+
when the last reference to the object is removed.
268+
\end{funcdesc}
269+
270+
\begin{funcdesc}{parseframe}{frame}
271+
Parses one or more frames of digital audio data from a CD such as
272+
returned by \code{readda}. It determines which subcodes are present
273+
in the data. If these subcodes have changed since the last frame,
274+
then \code{parseframe} executes a callback of the appropriate type
275+
passing to it the subcode data found in the frame.
276+
Unlike the C function, more than one frame of digital audio data can
277+
be passed to this method.
278+
\end{funcdesc}
279+
280+
\begin{funcdesc}{removecallback}{type}
281+
Removes the callback for the given \code{type}.
282+
\end{funcdesc}
283+
284+
\begin{funcdesc}{resetparser}{}
285+
Resets the fields of the parser used for tracking subcodes to an
286+
initial state. \code{resetparser} should be called after the disc has
287+
been changed.
288+
\end{funcdesc}

0 commit comments

Comments
 (0)