File: cdrom.rsd

package info (click to toggle)
ruby-sdl 2.2.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, buster, sid, stretch
  • size: 1,544 kB
  • ctags: 1,359
  • sloc: cpp: 7,598; ansic: 4,498; ruby: 2,246; makefile: 106; sh: 102
file content (448 lines) | stat: -rw-r--r-- 7,253 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
= CD-ROM
* ((<CD-ROM outline>))
* ((<SDL::CD>))
* ((<CD-ROM methods>))
TOC

== CD-ROM outline
SDL supports audio control of up to 32 local CD-ROM drives at once.

You use this API to perform all the basic functions of a CD player, including
listing the tracks, playing, stopping, and ejecting the CD-ROM. (Currently,
multi-changer CD drives are not supported.)

Before you call any of the SDL CD-ROM functions, you must first call
@[init](SDL::INIT_CDROM),
which scans the system for CD-ROM drives, and sets the program
up for audio control.

After you have initialized the library, you can find out how many drives are
available using the @[CD.num_drives]. The first drive listed is the
system default CD-ROM drive. After you have chosen a drive, and have opened it
with @[CD.open], you can check the status and start playing if there's a CD in
the drive.

A CD-ROM is organized into one or more tracks, each consisting of a certain number
of "frames". Each frame is ~2K in size, and at normal playing speed,
a CD plays 75(SDL::CD::FPS)
frames per second. SDL works with the number of frames on a CD, but this can
easily be converted to the more familiar minutes/seconds format by using
@[CD.frames_to_msf].

== SDL::CD
This class represents opened CDROM device and stores information on the
layout of the tracks on the disc.

== CD-ROM methods
%%%
NAME num_drives
MOD CD
TYPE .
PURPOSE Returns the number of CD-ROM drives on the system.
RVAL Integer

PROTO
num_drives
numDrives

DESC
Returns the number of CD-ROM drives on the system.

SEEALSO
CD.open

%%
NAME index_name
MOD CD
TYPE .
PURPOSE Returns a human-readable, system-dependent identifier for the CD-ROM.
RVAL String

PROTO
index_name(drive)
indexName(drive)

DESC
Returns a human-readable, system-dependent identifier for the CD-ROM. $[drive]
is the index of the drive.
Drive indices start to 0 and end at @[CD.num_drives]-1.

Examples of return strings.
* "/dev/cdrom"
* "E:"
* "/dev/disk/ide/1/master"

SEEALSO
CD.num_drives

%%
NAME open
MOD CD
TYPE .
PURPOSE Opens a CD-ROM drive for access.
RVAL SDL::CD

PROTO
open(drive)

DESC
Opens a CD-ROM drive for access. It returns @[CD] object on success.

Drives are numbered starting with 0. Drive 0 is the system default CD-ROM.

EXCEPTION
Raise @[Error] if the drive was invalid or busy.

EXAMPLE
SDL.init SDL::INIT_CDROM

# Check for CD drives
if SDL::CD.num_drives == 0
  # None found
  STDERR.print "No CDROM devices available\n"
  exit 255
end

begin
  # Open the default drive
  cdrom = SDL::CD.open(0)
rescue SDL::Error
  STDERR.puts "Couldn't open drive"
  exit 255
end

# Print volume info
printf "Name: %s\n", SDL::CD.index_name(0)
printf "Tracks: %d\n", cdrom.num_tracks
num_tracks.times do |cur_track|
  min, sec, frame = SDL::CD.frames_to_msf(cdrom.track_length(cur_track))
  printf "\tTrack %d: Length %d:%d\n", cur_track, min, sec
end

%%
NAME status
MOD CD
TYPE #
PURPOSE Returns the current status of the given drive.
RVAL UINT

PROTO
status

DESC
This method returns the current status of the given drive. Status is described
like so:
* SDL::CD::TRAYEMPTY
* SDL::CD::STOPPED
* SDL::CD::PLAYING
* SDL::CD::PAUSED
* SDL::CD::ERROR

If the drive has a CD in it,
@[current_track], @[current_frame], @[num_tracks], @[track_type],
and @[track_length] are updated.

EXAMPLE
def play_track(track)
  raise "not cd in drive" unless $cdrom.in_drive?

  # clamp to the actual number of tracks on the CD
  track = $cdrom.num_tracks-1 if track >= $cdrom.num_tracks
  $cdrom.play_tracks(track, 0, 1, 0)
end

%%
NAME play
MOD CD
TYPE #
PURPOSE Play a CD

PROTO
play(start, length)

DESC
Plays the given cdrom, starting a frame $[start] for length $[frames].

EXCEPTION *

SEEALSO
CD#play_tracks

%%
NAME play_tracks
MOD CD
TYPE #
PURPOSE Play the given CD track(s)

PROTO
play_tracks(start_track, start_frame, ntracks, nframes)

DESC
This method plays the given CD starting at track $[start_track], for $[ntracks]
tracks.

$[start_frame] is the frame offset, from the beginning of the $[start_track],
at which to start. $nframes] is the frame offset, from the beginning
of the last track
($[start_track]+$[ntracks]), at which to end playing.

THis methods should only be called after calling @[CD#status] to get track
information about the CD.

NOTES
Data tracks are ignored.

EXCEPTION *

EXAMPLE
# assuming cdrom is a previously opened device
# Play the entire CD
if cdrom.in_drive?
  cdrom.play_tracks 0, 0, 0, 0
end
# Play the first track
if cdrom.in_drive?
  cdrom.play_tracks 0, 0, 1, 0
end
# 2 Play first 15 seconds of the 2nd track
if cdrom.in_drive?
  cdrom.play_tracks 1, 0, 0, SDL::CD::FPS*15
end
SEEALSO
CD#play
CD#status

%%
NAME pause
MOD CD
TYPE #
PURPOSE Pauses a CDROM

PROTO
pause

DESC
Pauses play on the given cdrom.

EXCEPTION *

SEEALSO
CD#play
CD#resume

%%
NAME resume
MOD CD
TYPE #
PURPOSE Resumes a CDROM

PROTO
resume

DESC
Resumes play on the given cdrom.

EXCEPTION *

SEEALSO
CD#play
CD#pause

%%
NAME stop
MOD CD
TYPE #
PURPOSE Stops a CDROM

PROTO
stop

DESC
Stops play on the given cdrom.

EXCEPTION *

SEEALSO
CD#play

%%
NAME eject
MOD CD
TYPE #
PURPOSE Ejects a CDROM

PROTO
eject

DESC
Ejects the given cdrom.

EXCEPTION *

%%
NAME num_tracks
MOD CD
TYPE #
PURPOSE Gets number of tracks on the CD.
RVAL Integer

PROTO
num_tracks
numTracks

DESC
Returns the number of tracks on the given cdrom.
@[CD#status] updates this value.

SEEALSO
CD#status

%%
NAME current_track
MOD CD
TYPE #
PURPOSE Gets current track.
RVAL Integer

PROTO
current_track
currentTrack

DESC
Returns the currently playing track.
@[CD#status] updates this value.

SEEALSO
CD#status

%%
NAME current_frame
MOD CD
TYPE #
PURPOSE Gets current frame offset within the track
RVAL Integer

PROTO
current_frame
currentFrame

DESC
Returns the current frame offset with the playing track.
@[CD#status] updates this value.

SEEALSO
CD#status

%%
NAME track_type
MOD CD
TYPE #
PURPOSE Gets track type.
RVAL UINT

PROTO
track_type(track)
trackType(track)

DESC
Returns the track type in $[track].
SDL::CD::AUDIO_TRACK or SDL::CD::DATA_TRACK is returned.

%%
NAME track_length
MOD CD
TYPE #
PURPOSE Gets length of track.
RVAL Integer

PROTO
track_length(track)
trackLength(track)

DESC
Returns length, in frame, of $[track].

%%
NAME in_drive?
MOD CD
TYPE #
PURPOSE Check disc in drive
RVAL true/false

PROTO
in_drive?

DESC
Returns true if drive is not empty, otherwise returns false.

SEEALSO
CD#status

%%
NAME frames_to_msf
MOD CD
TYPE .
PURPOSE Convert frames into minitus/seconds/frames
RVAL [Integer, Integer, Integer]

PROTO
frames_to_msf(frames)
framesToMSF(frames)

DESC
Converts frames into minitus/seconds/frames, and returns an array like
[min, sec, frames].

SEEALSO
CD.msf_to_frames

%%
NAME msf_to_frames
MOD CD
TYPE .
PURPOSE Convert minitus/seconds/frames into frames
RVAL Integer

PROTO
msf_to_frames(min, sec, frames)
MSFToFrames(min, sec, frames)

DESC
Convert minitus/seconds/frames into frames and returns frames.

SEEALSO
CD.frames_to_msf

%%
NAME close
MOD CD
TYPE #
PURPOSE Closes a CD handle

PROTO
close

DESC 
Closes $[self].

SEEALSO
CD.open
CD#closed?

%%
NAME closed?
MOD CD
TYPE #
PURPOSE Returns whether CD is closed

PROTO
closed?

DESC 
Returns whether CD handle is closed by
@[CD#close]

SEEALSO
CD#close