Mercurial > sdl-ios-xcode
annotate include/SDL_cdrom.h @ 942:41a59de7f2ed
Here are patches for SDL12 and SDL_mixer for 4 or 6 channel
surround sound on Linux using the Alsa driver. To use them, naturally
you need a sound card that will do 4 or 6 channels and probably also a
recent version of the Alsa drivers and library. Since the only SDL
output driver that knows about surround sound is the Alsa driver,
you���ll want to choose it, using:
export SDL_AUDIODRIVER=alsa
There are no syntactic changes to the programming API. No new
library calls, no differences in arguments.
There are two semantic changes:
(1) For library calls with number of channels as an argument, formerly
you could use only 1 or 2 for the number of channels. Now you
can also use 4 or 6.
(2) The two "left" and "right" arguments to Mix_SetPanning, for the
case of 4 or 6 channels, no longer simply control the volumes of
the left and right channels. Now the "left" argument is converted
to an angle and Mix_SetPosition is called, and the "right" argu-
ment is ignored.
With two exceptions, so far as I know, the modified SDL12 and
SDL_mixer work the same way as the original versions, when opened for
1 or 2 channel output. The two exceptions are bugs which I fixed.
Well, the first, anyway, is a bug for sure. When rate conversions up
or down by a factor of two are applied (in src/audio/SDL_audiocvt.c),
streams with different numbers of channels (that is, mono and stereo)
are treated the same way: either each sample is copied or every other
sample is omitted. This is ok for mono, but for stereo, it is frames
that should be copied or omitted, where by "frame" I mean a portion of
the stream containing one sample for each channel. (In the SDL source,
confusingly, sometimes frames are called "samples".) So for these
rate conversions, stereo streams have to be treated differently, and
they are, in my modified version.
The other problem that might be characterized as a bug arises
when SDL_mixer is passed a multichannel chunk which does not have an
integral number of frames. Due to the way the effect_position code
loops over frames, when the chunk ends with a partial frame, memory
outside the chunk buffer will be accessed. In the case of stereo,
it���s possible that because malloc may give more memory than requested,
this potential problem never actually causes a segment fault. I don���t
know. For 6 channel chunks, I do know, and it does cause segment
faults.
If SDL_mixer is passed defective chunks and this causes a segment
fault, arguably, that���s not a bug in SDL_mixer. Still, whether or not
it counts as a bug, it���s easy to protect against, so why not? I added
code in mixer.c to discard any partial frame at the end of a chunk.
Then what about when SDL or SDL_mixer is opened for 4 or 6 chan-
nel output? What happens with the parts of the current library
designed for stereo? I don���t know whether I���ve covered all the bases,
but I���ve tried:
(1) For playing 2 channel waves, or other cases where SDL knows it has
to match up a 2 channel source with a 4 or 6 channel output, I���ve
added code in SDL_audiocvt.c to make the necessary conversions.
(2) For playing midis using timidity, I���ve converted timidity to do 4
or 6 channel output, upon request.
(3) For playing mods using mikmod, I put ad hoc code in music.c to
convert the stereo output that mikmod produces to 4 or 6 chan-
nels. Obviously it would be better to change the mikmod code to
mix down into 4 or 6 channels, but I have a hard time following
the code in mikmod, so I didn���t do that.
(4) For playing mp3s, I put ad hoc code in smpeg to copy channels in
the case when 4 or 6 channel output is needed.
(5) There seems to be no problem with .ogg files - stereo .oggs can be
up converted as .wavs are.
(6) The effect_position code in SDL_mixer is now generalized to in-
clude the cases of 4 and 6 channel streams.
I���ve done a very limited amount of compatibility testing for some
of the games using SDL I happen to have. For details, see the file
TESTS.
I���ve put into a separate archive, Surround-SDL-testfiles.tgz, a
couple of 6 channel wave files for testing and a 6 channel ogg file.
If you have the right hardware and version of Alsa, you should be able
to play the wave files with the Alsa utility aplay (and hear all
channels, except maybe lfe, for chan-id.wav, since it���s rather faint).
Don���t expect aplay to give good sound, though. There���s something
wrong with the current version of aplay.
The canyon.ogg file is to test loading of 6 channel oggs. After
patching and compiling, you can play it with playmus. (My version of
ogg123 will not play it, and I had to patch mplayer to get it to play
6 channel oggs.)
Greg Lee <greg@ling.lll.hawaii.edu>
Thus, July 1, 2004
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Sat, 21 Aug 2004 12:27:02 +0000 |
parents | 04a403e4ccf5 |
children | f09d5edfc7a3 |
rev | line source |
---|---|
0 | 1 /* |
2 SDL - Simple DirectMedia Layer | |
769
b8d311d90021
Updated copyright information for 2004 (Happy New Year!)
Sam Lantinga <slouken@libsdl.org>
parents:
337
diff
changeset
|
3 Copyright (C) 1997-2004 Sam Lantinga |
0 | 4 |
5 This library is free software; you can redistribute it and/or | |
6 modify it under the terms of the GNU Library General Public | |
7 License as published by the Free Software Foundation; either | |
8 version 2 of the License, or (at your option) any later version. | |
9 | |
10 This library is distributed in the hope that it will be useful, | |
11 but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
13 Library General Public License for more details. | |
14 | |
15 You should have received a copy of the GNU Library General Public | |
16 License along with this library; if not, write to the Free | |
17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
18 | |
19 Sam Lantinga | |
251
b8688cfdc232
Updated the headers with the correct e-mail address
Sam Lantinga <slouken@libsdl.org>
parents:
0
diff
changeset
|
20 slouken@libsdl.org |
0 | 21 */ |
22 | |
23 #ifdef SAVE_RCSID | |
24 static char rcsid = | |
25 "@(#) $Id$"; | |
26 #endif | |
27 | |
28 /* This is the CD-audio control API for Simple DirectMedia Layer */ | |
29 | |
30 #ifndef _SDL_cdrom_h | |
31 #define _SDL_cdrom_h | |
32 | |
33 #include "SDL_types.h" | |
34 | |
35 #include "begin_code.h" | |
36 /* Set up for C function definitions, even when using C++ */ | |
37 #ifdef __cplusplus | |
38 extern "C" { | |
39 #endif | |
40 | |
41 /* In order to use these functions, SDL_Init() must have been called | |
42 with the SDL_INIT_CDROM flag. This causes SDL to scan the system | |
43 for CD-ROM drives, and load appropriate drivers. | |
44 */ | |
45 | |
46 /* The maximum number of CD-ROM tracks on a disk */ | |
47 #define SDL_MAX_TRACKS 99 | |
48 | |
49 /* The types of CD-ROM track possible */ | |
50 #define SDL_AUDIO_TRACK 0x00 | |
51 #define SDL_DATA_TRACK 0x04 | |
52 | |
53 /* The possible states which a CD-ROM drive can be in. */ | |
54 typedef enum { | |
55 CD_TRAYEMPTY, | |
56 CD_STOPPED, | |
57 CD_PLAYING, | |
58 CD_PAUSED, | |
59 CD_ERROR = -1 | |
60 } CDstatus; | |
61 | |
62 /* Given a status, returns true if there's a disk in the drive */ | |
63 #define CD_INDRIVE(status) ((int)status > 0) | |
64 | |
911
04a403e4ccf5
Date: Mon, 3 May 2004 03:15:01 +0100
Sam Lantinga <slouken@libsdl.org>
parents:
769
diff
changeset
|
65 typedef struct SDL_CDtrack { |
0 | 66 Uint8 id; /* Track number */ |
67 Uint8 type; /* Data or audio track */ | |
68 Uint16 unused; | |
69 Uint32 length; /* Length, in frames, of this track */ | |
70 Uint32 offset; /* Offset, in frames, from start of disk */ | |
71 } SDL_CDtrack; | |
72 | |
73 /* This structure is only current as of the last call to SDL_CDStatus() */ | |
74 typedef struct SDL_CD { | |
75 int id; /* Private drive identifier */ | |
76 CDstatus status; /* Current drive status */ | |
77 | |
78 /* The rest of this structure is only valid if there's a CD in drive */ | |
79 int numtracks; /* Number of tracks on disk */ | |
80 int cur_track; /* Current track position */ | |
81 int cur_frame; /* Current frame offset within current track */ | |
82 SDL_CDtrack track[SDL_MAX_TRACKS+1]; | |
83 } SDL_CD; | |
84 | |
85 /* Conversion functions from frames to Minute/Second/Frames and vice versa */ | |
86 #define CD_FPS 75 | |
87 #define FRAMES_TO_MSF(f, M,S,F) { \ | |
88 int value = f; \ | |
89 *(F) = value%CD_FPS; \ | |
90 value /= CD_FPS; \ | |
91 *(S) = value%60; \ | |
92 value /= 60; \ | |
93 *(M) = value; \ | |
94 } | |
95 #define MSF_TO_FRAMES(M, S, F) ((M)*60*CD_FPS+(S)*CD_FPS+(F)) | |
96 | |
97 /* CD-audio API functions: */ | |
98 | |
99 /* Returns the number of CD-ROM drives on the system, or -1 if | |
100 SDL_Init() has not been called with the SDL_INIT_CDROM flag. | |
101 */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
102 extern DECLSPEC int SDLCALL SDL_CDNumDrives(void); |
0 | 103 |
104 /* Returns a human-readable, system-dependent identifier for the CD-ROM. | |
105 Example: | |
106 "/dev/cdrom" | |
107 "E:" | |
108 "/dev/disk/ide/1/master" | |
109 */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
110 extern DECLSPEC const char * SDLCALL SDL_CDName(int drive); |
0 | 111 |
112 /* Opens a CD-ROM drive for access. It returns a drive handle on success, | |
113 or NULL if the drive was invalid or busy. This newly opened CD-ROM | |
114 becomes the default CD used when other CD functions are passed a NULL | |
115 CD-ROM handle. | |
116 Drives are numbered starting with 0. Drive 0 is the system default CD-ROM. | |
117 */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
118 extern DECLSPEC SDL_CD * SDLCALL SDL_CDOpen(int drive); |
0 | 119 |
120 /* This function returns the current status of the given drive. | |
121 If the drive has a CD in it, the table of contents of the CD and current | |
122 play position of the CD will be stored in the SDL_CD structure. | |
123 */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
124 extern DECLSPEC CDstatus SDLCALL SDL_CDStatus(SDL_CD *cdrom); |
0 | 125 |
126 /* Play the given CD starting at 'start_track' and 'start_frame' for 'ntracks' | |
127 tracks and 'nframes' frames. If both 'ntrack' and 'nframe' are 0, play | |
128 until the end of the CD. This function will skip data tracks. | |
129 This function should only be called after calling SDL_CDStatus() to | |
130 get track information about the CD. | |
131 For example: | |
132 // Play entire CD: | |
133 if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) | |
134 SDL_CDPlayTracks(cdrom, 0, 0, 0, 0); | |
135 // Play last track: | |
136 if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) { | |
137 SDL_CDPlayTracks(cdrom, cdrom->numtracks-1, 0, 0, 0); | |
138 } | |
139 // Play first and second track and 10 seconds of third track: | |
140 if ( CD_INDRIVE(SDL_CDStatus(cdrom)) ) | |
141 SDL_CDPlayTracks(cdrom, 0, 0, 2, 10); | |
142 | |
143 This function returns 0, or -1 if there was an error. | |
144 */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
145 extern DECLSPEC int SDLCALL SDL_CDPlayTracks(SDL_CD *cdrom, |
0 | 146 int start_track, int start_frame, int ntracks, int nframes); |
147 | |
148 /* Play the given CD starting at 'start' frame for 'length' frames. | |
149 It returns 0, or -1 if there was an error. | |
150 */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
151 extern DECLSPEC int SDLCALL SDL_CDPlay(SDL_CD *cdrom, int start, int length); |
0 | 152 |
153 /* Pause play -- returns 0, or -1 on error */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
154 extern DECLSPEC int SDLCALL SDL_CDPause(SDL_CD *cdrom); |
0 | 155 |
156 /* Resume play -- returns 0, or -1 on error */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
157 extern DECLSPEC int SDLCALL SDL_CDResume(SDL_CD *cdrom); |
0 | 158 |
159 /* Stop play -- returns 0, or -1 on error */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
160 extern DECLSPEC int SDLCALL SDL_CDStop(SDL_CD *cdrom); |
0 | 161 |
162 /* Eject CD-ROM -- returns 0, or -1 on error */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
163 extern DECLSPEC int SDLCALL SDL_CDEject(SDL_CD *cdrom); |
0 | 164 |
165 /* Closes the handle for the CD-ROM drive */ | |
337
9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents:
297
diff
changeset
|
166 extern DECLSPEC void SDLCALL SDL_CDClose(SDL_CD *cdrom); |
0 | 167 |
168 | |
169 /* Ends C function definitions when using C++ */ | |
170 #ifdef __cplusplus | |
171 } | |
172 #endif | |
173 #include "close_code.h" | |
174 | |
175 #endif /* _SDL_video_h */ |