Mercurial > sdl-ios-xcode

view README.MiNT @ 942:41a59de7f2ed

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 6b3dfe0198bb
children 92c247cec42d
line wrap: on
line source


==============================================================================
Using the Simple DirectMedia Layer on Atari
==============================================================================

==============================================================================
I.  Building the Simple DirectMedia Layer libraries:
    (This step isn't necessary if you have the SDL binary distribution)

  Do the classic configure, with --disable-shared --enable-static and:

    Tos version (should run everywhere):
      --disable-threads
    Tos does not support threads.

    MiNT version (maybe Magic, only for multitasking OS):
      --disable-pthreads --enable-pth
    Mint and Magic may supports threads, so audio can be used with current
    devices, like Sun audio, or disk-writing support. Like Tos, interrupt
    audio without threads is more suited for Atari machines.

  Then you can make ; make install it.

==============================================================================
II. Building the Simple DirectMedia Layer test programs:

  Do the classic configure, then make.

  Run them !

==============================================================================
III.  Enjoy! :)

  If you have a project you'd like me to know about, or want to ask questions,
  go ahead and join the SDL developer's mailing list by sending e-mail to:

	sdl-request@libsdl.org

  and put "subscribe" into the subject of the message. Or alternatively you
  can use the web interface:

	http://www.libsdl.org/mailman/listinfo/sdl
  
==============================================================================
IV.  What is supported:

Keyboard (GEMDOS, BIOS, GEM, Ikbd)
Mouse (XBIOS, GEM, Ikbd)
Video (XBIOS (Fullscreen), GEM (Windowed and Fullscreen))
Timer (VBL vector, GNU pth library)
Joystick and joypad (Ikbd, Hardware)
Audio (Hardware, XBIOS, GSXB, MCSN, STFA, /dev/audio if threads enabled)
Threads (Multitasking OS only via GNU pth library)
Shared object loader (using LDG library from http://ldg.atari.org/)
Audio CD (MetaDOS)

- Driver combinations:
Video	Kbd	Mouse	Timer	Joystick
xbios	ikbd	ikbd	vbl(2)	ikbd
xbios	gemdos	xbios	vbl(2)	xbios
xbios	bios	xbios	vbl(2)	xbios
gem	gem	gem(1)	vbl(2)	xbios

(1) GEM does not report relative mouse motion, so xbios mouse driver is used
to report this type event.

(2) If you build SDL with threads using the GNU pth library, timers are
supported via the pth library.

==============================================================================
V.  Environment variables:

SDL_VIDEODRIVER:
	Set to 'xbios' to force xbios video driver
	Set to 'gem' to force gem video driver

SDL_AUDIODRIVER:
	Set to 'mint_gsxb' to force Atari GSXB audio driver
	Set to 'mint_mcsn' to force Atari MCSN audio driver
	Set to 'mint_stfa' to force Atari STFA audio driver
	Set to 'mint_xbios' to force Atari Xbios audio driver
	Set to 'mint_dma8' to force Atari 8 bits DMA audio driver
	Set to 'audio' to force Sun /dev/audio audio driver
	Set to 'disk' to force disk-writing audio driver

SDL_ATARI_EVENTSDRIVER
	Set to 'ikbd' to force IKBD 6301 keyboard driver
	Set to 'gemdos' to force gemdos keyboard driver
	Set to 'bios' to force bios keyboard driver

SDL_JOYSTICK_ATARI:
	Use any of these strings in the environment variable to enable or
	disable a joystick:

	'ikbd-joy1-[on|off]' for IKBD joystick on port 1 (hardware access)
	'xbios-joy1-[on|off]' for IKBD joystick on port 1 (xbios access)
	'porta-pad-[on|off]' for joypad on port A
	'porta-joy0-[on|off]' for joystick 0 on port A
	'porta-joy1-[on|off]' for joystick 1 on port A
	'porta-lp-[on|off]' for lightpen on port A
	'porta-anpad-[on|off]' for analog paddle on port A
	'portb-pad-[on|off]' for joypad on port B
	'portb-joy0-[on|off]' for joystick 0 on port B
	'portb-joy1-[on|off]' for joystick 1 on port B
	'portb-anpad-[on|off]' for analog paddle on port B

	Default configuration is:
		'ikbd-joy1-on' (if IKBD events driver enabled)
		'xbios-joy1-on' (if gemdos/bios/gem events driver enabled)
		'porta-pad-on portb-pad-on' (if available on the machine)

	port[a|b]-[pad|joy?|lp|anpad]-* strings are mutually exclusives.
	On such a port, you can only use a joypad OR 1 or 2 joysticks OR
	a lightpen OR an analog paddle. You must disable joypad before
	setting another controller.

	The second joystick port on IKBD is used by the mouse, so not usable.

	Joypads are multibuttons controller (Atari Jaguar console-like).
	Joysticks are 1 button, 2 axis controllers.
	Lightpen and analog paddle are 2 buttons, 2 axis controllers. The 2
	buttons are those affected to 1 button joysticks on the same port.

==============================================================================
VI.  More informations about drivers:

Xbios video:
	Video chip is detected using the _VDO cookie.
	Screen enhancers are not supported, but could be if you know how to
	use them.

	ST, STE, Mega ST, Mega STE:
		320x200x4 bits, shades of grey, available only for the purpose
		of testing SDL.
	TT:
		320x480x8 and 320x240x8 (software double-lined mode).
	Falcon:
		All modes supported by the current monitor (RVB or VGA).
	Clones and any machine with monochrome monitor:
		Not supported.

Gem video:
	Automatically used if xbios not available.

	All machines:
		Only the current resolution, if 8 bits or higher depth.

IKBD keyboard, mouse and joystick driver:
	Available if _MCH cookie is ST, Mega ST, STE, Mega STE, TT or Falcon.

	Hades has an IKBD, but xbios is not available for video, so IKBD
	driver is disabled.

Gemdos and bios keyboard driver:
	Available on all machines.

Mouse and joystick xbios driver:
	Available on all machines (I think).

Joypad driver:
	Available if _MCH cookie is STE or Falcon.

PTH timer driver:
	Available with multitasking OS.

VBL timer driver:
	Available on all machines (I think).

Audio drivers:
	Cookies _SND, MCSN, STFA and GSXB used to detect supported audio
	capabilities.

	STE, Mega STE, TT:
		8 bits DMA (hardware access)
		STFA, MCSN or GSXB driver if installed
	Falcon:
		8 bits DMA (hardware access)
		Xbios functions
		STFA, MCSN or GSXB driver if installed
	Other machines:
		STFA, MCSN or GSXB driver if installed

	STFA driver:
		http://removers.free.fr/softs/stfa.html
	GSXB driver:
		http://assemsoft.atari.org/gsxb/
	MacSound driver:
		http://jf.omnis.ch/software/tos/
	MagicSound driver (MCSN,GSXB compatible):
		http://perso.wanadoo.fr/didierm/
	X-Sound driver (GSXB compatible):
		http://www.uni-ulm.de/~s_thuth/atari/xsound_e.html

-- 
Patrice Mandin <pmandin@caramail.com>
http://membres.lycos.fr/pmandin/