Proposed CD-ROM API

slouken · October 1, 1998, 9:00am

Here’s the proposed CD-ROM API.
I’ve looked at how Linux, Solaris, Win32, and BeOS do CD audio control,
and I think this can mostly be supported on all platforms:

/* Note: Track positions are in terms of frames (75 frames-per-second) */

typedef enum {
CD_STOPPED,
CD_PLAYING,
CD_PAUSED,
CD_ERROR = -1,
CD_TRAYEMPTY = -2
CD_INVALIDTRACK = -3, /* Used for error reporting /
CD_INVALIDFRAME = -4 / Used for error reporting */
} CDstatus;

/* Returns the number of CD-ROM drives on the system */
int SDL_CDNumDrives();

/* Opens a CD-ROM drive – a CD may or may not be in the drive */
SDL_CD *SDL_CDOpen(int drive);

/* Returns number of CD-ROMs available on this drive (multi-changer support) */
int SDL_CDNumCDs(SDL_CD *cdrom);

/* Selects which CD is to be played (multi-changer support) */
void SDL_CDSelectCD(SDL_CD *cdrom, int which);

/* Returns the serial number of the current CD-ROM */
CDstatus SDL_CDGetID(SDL_CD *cdrom, Uint8 id[8]);

/* Returns the number of tracks on the current CD-ROM */
CDstatus SDL_CDNumTracks(SDL_CD *cdrom);

/* Returns the length, in frames, of the given track */
CDstatus SDL_CDTrackLength(SDL_CD *cdrom, int track, int *length);

/* Returns whether the given track is audio or data */
CDstatus SDL_CDTrackType(SDL_CD *cdrom, int track);

/* Returns the current status and position of the CD-ROM */
CDstatus SDL_CDStatus(SDL_CD *cdrom, int *track, int *frame);

/* Reads a data track, if supported */
CDstatus SDL_CDRead(SDL_CD *cdrom, int start_track, int start_frame, int end_track, int end_frame);

/* Plays an audio track from start_track.start_frame to end_track.end_frame.
Values of 0 are “use current value” flags.
*/
CDstatus SDL_CDPlay(SDL_CD *cdrom, int start_track, int start_frame, int end_track, int end_frame);

/* Pause play – returns status before pause */
CDstatus SDL_CDPause(SDL_CD *cdrom);

/* Stop play – returns status before stop */
int SDL_CDStop(SDL_CD *cdrom);

/* Eject CD-ROM – returns status before eject */
int SDL_CDEject(SDL_CD *cdrom);

/* Set the current CD audio output volume – returns previous volume.
If ‘volume’ is -1, the current volume is unchanged.
*/
int SDL_CDVolume(SDL_CD *cdrom, int volume);

/* Close a previously opened CD-ROM drive */
void SDL_CDClose(SDL_CD *cdrom);----

This seems fairly complete. Did I miss anything?

Play stop notification will have to be done by polling.
Programming play sequences will have to be done by the application.
The functions (hopefully) will be thread-safe.

See ya!
-Sam Lantinga (slouken at devolution.com)

–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

Michael_Samuel · October 1, 1998, 1:58pm

/* Returns the number of CD-ROM drives on the system */
int SDL_CDNumDrives();

How many /dev/cdrom links can one system have?

/* Returns number of CD-ROMs available on this drive (multi-changer support) */

I thought you said you weren’t planning on supporting multi-changer drives?
Have you found out something new since yesterday?

/* Returns whether the given track is audio or data */
CDstatus SDL_CDTrackType(SDL_CD *cdrom, int track);

Wouldn’t it be better to return an integer (signed short int) with the track
mode? (eg. mode 1, 2…)

/* Reads a data track, if supported */
CDstatus SDL_CDRead(SDL_CD *cdrom, int start_track, int start_frame, int end_track, int end_frame);

That is really not in the scope of SDL. If you want to use a cdrom for data,
read a file off a mounted partition. Stick to audio controls. (BTW, which
variable returns the data? Is that part of CDstatus or (SDL_CD *)?)

This seems fairly complete. Did I miss anything?

What about a check for an ISO filesystem and return the base path to it? (Is
that portable?)On Thu, Oct 01, 1998 at 02:00:46AM -0700, Sam Lantinga wrote:

–
– Michael Samuel

slouken · October 1, 1998, 5:26pm

/* Returns the number of CD-ROM drives on the system */
int SDL_CDNumDrives();

How many /dev/cdrom links can one system have?

/dev/sr0 /dev/sr1 /dev/cdrom /dev/hdc /dev/hdd …

/* Returns number of CD-ROMs available on this drive (multi-changer support) */

I thought you said you weren’t planning on supporting multi-changer drives?
Have you found out something new since yesterday?

Yep, I figured out how to say “This isn’t a multi-changer” even when it is.

/* Returns whether the given track is audio or data */
CDstatus SDL_CDTrackType(SDL_CD *cdrom, int track);

Wouldn’t it be better to return an integer (signed short int) with the track
mode? (eg. mode 1, 2…)

Yep, typo.

/* Reads a data track, if supported */
CDstatus SDL_CDRead(SDL_CD *cdrom, int start_track, int start_frame, int end_track, int end_frame);

That is really not in the scope of SDL. If you want to use a cdrom for data,
read a file off a mounted partition. Stick to audio controls. (BTW, which
variable returns the data? Is that part of CDstatus or (SDL_CD *)?)

Erm. Um, I’m not sure if that’s really beyond the scope of SDL. Most APIs
do provide a method of reading data tracks, and most games generally
don’t rely on the user to “mount” the ISO formatted drive and tell it
where the data files are. It’s much simpler to allow the program to
scan the drives, read the serial numbers, and read the proper data tracks
of the drive with their CD-ROM.
(I forgot to add the data return argument)

This seems fairly complete. Did I miss anything?

What about a check for an ISO filesystem and return the base path to it? (Is
that portable?)

It’s not really portable. If it’s an ISO CD-ROM, and the application treats
it as a normal filesystem, then it should be mounted normally and then given
to the app as a regular pathname.

It’s just a different philosophy of games. I don’t expect games that have
any sort of copy protection to use ISO formatted CD-ROMs, and if so, the
ISO fileysstem wouldn’t be any different than a regular removable-media
filesystem.

See ya!
-Sam Lantinga (slouken at devolution.com)> On Thu, Oct 01, 1998 at 02:00:46AM -0700, Sam Lantinga wrote:

–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

Michael_Samuel · October 2, 1998, 8:02am

How many /dev/cdrom links can one system have?

/dev/sr0 /dev/sr1 /dev/cdrom /dev/hdc /dev/hdd …

How about this one goes into /etc/sdl.conf?

I thought you said you weren’t planning on supporting multi-changer drives?
Have you found out something new since yesterday?

Yep, I figured out how to say “This isn’t a multi-changer” even when it is.

Hmm… I love API functions that are simple and don’t try to take on too much
work, but this might be going too far

That is really not in the scope of SDL. If you want to use a cdrom for data,
read a file off a mounted partition. Stick to audio controls. (BTW, which
variable returns the data? Is that part of CDstatus or (SDL_CD *)?)

Erm. Um, I’m not sure if that’s really beyond the scope of SDL. Most APIs
do provide a method of reading data tracks, and most games generally
don’t rely on the user to “mount” the ISO formatted drive and tell it
where the data files are. It’s much simpler to allow the program to
scan the drives, read the serial numbers, and read the proper data tracks
of the drive with their CD-ROM.
(I forgot to add the data return argument)

I suppose, but then again, I’d hate to have to implement a filesystem into my
software, when my OS provides filesystem support for me.

What about a check for an ISO filesystem and return the base path to it? (Is
that portable?)

It’s not really portable. If it’s an ISO CD-ROM, and the application treats
^^^^^^^^^^^^^^^^^^^^^^^^^^
'nuff said.

It’s just a different philosophy of games. I don’t expect games that have
any sort of copy protection to use ISO formatted CD-ROMs, and if so, the
ISO fileysstem wouldn’t be any different than a regular removable-media
filesystem.

Yes, but any copy protection that can work will need to know the media type
of the CD…On Thu, Oct 01, 1998 at 10:26:26AM -0700, Sam Lantinga wrote:

–
– Michael Samuel

slouken · October 2, 1998, 8:11am

How many /dev/cdrom links can one system have?

/dev/sr0 /dev/sr1 /dev/cdrom /dev/hdc /dev/hdd …

How about this one goes into /etc/sdl.conf?

I like the auto-detection routines. They work nicely for me, and there’s
still no need for an /etc/sdl.conf. grin

The initial API is out, with a Linux implementation. See the new CVS snapshot.

I punted three ways:
Multi-changers are not supported
There’s no way to get the disk id.
There’s no support for reading data tracks.

Adding multi-changer support will just involve two new API functions,
no big deal.
Apparently there is no “official” disk id. The disk id is calculated
from an algorithm that uses the track and frame info of the current
disk. This is possible using the current SDL API.
Adding support for data tracks would be easy, but I don’t know how the
layout of these disks affects the play of audio tracks (ordering, etc.)
This should be relatively easy to add later, if there is demand for it.

Note that most CD-ROM device files under Linux are only readable by root.

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

Michael_Samuel · October 2, 1998, 12:07pm

I punted three ways:
Multi-changers are not supported
There’s no way to get the disk id.
There’s no support for reading data tracks.

Adding multi-changer support will just involve two new API functions,
no big deal.

Apparently there is no “official” disk id. The disk id is calculated
from an algorithm that uses the track and frame info of the current
disk. This is possible using the current SDL API.

Is it too hard, or just not worth the code bloat? (eg. if you can point me to
a spec, I could write a function/macro that does it using the current SDL API)

Note that most CD-ROM device files under Linux are only readable by root.

Well, if root trusts the users of the SDL-based program enough to let them use
the CD-ROM device, root can give them permission (either world-read+write, or
some kind of group setup)

So none of you get any funny ideas of suid-root programs over a CD-ROM device
file ;-)On Fri, Oct 02, 1998 at 01:11:55AM -0700, Sam Lantinga wrote:

–
– Michael Samuel

slouken · October 2, 1998, 1:06pm

Apparently there is no “official” disk id. The disk id is calculated
from an algorithm that uses the track and frame info of the current
disk. This is possible using the current SDL API.

Is it too hard, or just not worth the code bloat? (eg. if you can point me to
a spec, I could write a function/macro that does it using the current SDL API)

I’m not sure that an official “disk id” algorithm exists.
The one CDDB uses can be found in the source code for xmcd 2.3, in the
directory cddb_d …

Note that most CD-ROM device files under Linux are only readable by root.

Well, if root trusts the users of the SDL-based program enough to let them use
the CD-ROM device, root can give them permission (either world-read+write, or
some kind of group setup)

So none of you get any funny ideas of suid-root programs over a CD-ROM device
file

grin
I just wanted people to be aware that permissions might be a problem and
that it’s not SDL’s fault.

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

slouken · October 2, 1998, 1:09pm

The initial API is out, with a Linux implementation. See the new CVS snapshot.

The BeOS implementation is almost complete. It works fine with IDE drives,
but doesn’t know how to detect SCSI drives yet. I don’t know what a path
to a SCSI CD-ROM looks like: /dev/disk/scsi/???

It’s just a matter of knowing the form of the SCSI CD pathname and it should
be done!

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

Knight_Walker · October 2, 1998, 1:18pm

Does the Linux implementation have any problems with SCSI CD-ROMs?On 2 Oct, Sam Lantinga wrote:

The BeOS implementation is almost complete. It works fine with IDE drives,
but doesn’t know how to detect SCSI drives yet. I don’t know what a path
to a SCSI CD-ROM looks like: /dev/disk/scsi/???

–

| |/ | | | _ | | | mailto:@Knight_Walker |
| / | / / | | http://www.aros.net/~kwalker |
| \ | ___ | | |
| |\ | | / \ | | The Kobran Imperium (801)265-1299 |
|| || || || _____________________________________/

slouken · October 2, 1998, 6:42pm

It shouldn’t, though I haven’t tested it.

See ya!
-Sam Lantinga (slouken at devolution.com)> On 2 Oct, Sam Lantinga wrote:

The BeOS implementation is almost complete. It works fine with IDE drives,
but doesn’t know how to detect SCSI drives yet. I don’t know what a path
to a SCSI CD-ROM looks like: /dev/disk/scsi/???

Does the Linux implementation have any problems with SCSI CD-ROMs?

–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

slouken · October 3, 1998, 5:32am

Quick CVS update:
Much improved CD-ROM driver for Linux and BeOS
Tested:
IDE CD-ROM under BeOS x86
IDE CD-ROM and SCSI CD-ROM simultaneously under Linux

Anyway, have fun!

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

slouken · October 5, 1998, 5:13pm

The new CVS snapshot should have the finished single-CD audio API:

            SDL_CDNumDrives()
            SDL_CDName()
            SDL_CDOpen()
            SDL_CDStatus()
            SDL_CDPlayTracks()
            SDL_CDPlay()
            SDL_CDPause()
            SDL_CDResume()
            SDL_CDStop()
            SDL_CDEject()
            SDL_CDClose()

It doesn’t work on Win32 yet, but it should be fairly complete on Linux
and BeOS (Linux x86 and PPC tested, BeOS x86 tested)

Under Mach-based PPC Linux, opening the CD-ROM stops play.

There’s only one bug that XMCD works around that I haven’t addressed yet,
and that’s firmware that reports positions in BCD format instead of in
minutes-seconds-frames. If you have a CD that does this, please let me
know. You’ll be able to tell if the output from “testcdrom -list” is
completely inaccurate.

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

slouken · October 6, 1998, 5:29pm

The new CVS snapshot should have the finished single-CD audio API:

            SDL_CDNumDrives()
            SDL_CDName()
            SDL_CDOpen()
            SDL_CDStatus()
            SDL_CDPlayTracks()
            SDL_CDPlay()
            SDL_CDPause()
            SDL_CDResume()
            SDL_CDStop()
            SDL_CDEject()
            SDL_CDClose()

It should work on Win32 now too.

Proposed CD-ROM API

– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

See ya! -Sam Lantinga (slouken at devolution.com)– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

See ya! -Sam Lantinga (slouken at devolution.com)– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

See ya! -Sam Lantinga (slouken at devolution.com)– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

See ya! -Sam Lantinga (slouken at devolution.com)– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

See ya! -Sam Lantinga (slouken at devolution.com)– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

See ya! -Sam Lantinga (slouken at devolution.com)– Author of Simple DirectMedia Layer - http://www.devolution.com/~slouken/SDL/

–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/

See ya!
-Sam Lantinga (slouken at devolution.com)–
Author of Simple DirectMedia Layer -
http://www.devolution.com/~slouken/SDL/