CHANGES
author Sam Lantinga <slouken@libsdl.org>
Sat, 21 Aug 2004 12:27:02 +0000
changeset 245 63b3650714de
parent 240 df2d45dbed91
child 246 9fa5d0f9d042
permissions -rw-r--r--
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
     1 1.2.6:
     2 Greg Lee - Wed, 14 Jul 2004 05:13:14 -1000
     3  * Added 4 and 6 channel surround sound output support
     4  * Added support for RMID format MIDI files
     5 Sam Lantinga - Wed Nov 19 00:23:44 PST 2003
     6  * Updated libtool support for new mingw32 DLL build process
     7 Ryan C. Gordon - Sun Nov  9 23:34:47 EST 2003
     8  * Patch from Steven Fuller to fix positioning effect on bigendian systems.
     9 Laurent Ganter - Mon, 6 Oct 2003 11:51:33 +0200
    10  * Fixed bug with MIDI volume in native Windows playback
    11 Andre Leiradella - Fri, 30 May 2003 16:12:03 -0300
    12  * Added SDL_RWops support for reading MOD files
    13 Kyle Davenport - Sat, 19 Apr 2003 17:13:31 -0500
    14  * Added .la files to the development RPM, fixing RPM build on RedHat 8
    15 
    16 1.2.5:
    17 Darrell Walisser - Tue Mar  4 09:24:01 PST 2003
    18  * Worked around MacOS X deadlock between CoreAudio and QuickTime
    19 Darrell Walisser - Fri, 14 Feb 2003 20:56:08 -0500
    20  * Fixed crash in native midi code with files with more than 32 tracks
    21 Marc Le Douarain - Sat, 15 Feb 2003 14:46:41 +0100
    22  * Added 8SVX format support to the AIFF loader
    23 Sam Lantinga Wed Feb 12 21:03:57 PST 2003
    24  * Fixed volume control on WAVE music chunks
    25 Ben Nason - Mon, 10 Feb 2003 11:50:27 -0800
    26  * Fixed volume control on MOD music chunks
    27 Patrice Mandin - Fri, 31 Jan 2003 15:17:30 +0100
    28  * Added support for the Atari platform
    29 Ryan C. Gordon - Fri Dec 27 10:14:07 EST 2002
    30  * Patch from Steven Fuller to fix panning effect with 8-bit sounds.
    31 Ryan C. Gordon - Thu Jan  2 12:31:48 EST 2003
    32  * Patch from guy on 3DRealms forums to fix native win32 midi volume.
    33 Ryan C. Gordon - Wed Oct 30 07:12:06 EST 2002
    34  * Small, looping music samples should now be able to fade out correctly.
    35 Sam Lantinga - Sun Oct 20 20:52:24 PDT 2002
    36  * Added shared library support for MacOS X
    37 Pete Shinners - Wed Oct 16 17:10:08 EDT 2002
    38  * Correctly report an error when using an unknown filetype
    39 Vaclav Slavik - Sun Sep  8 18:57:38 PDT 2002
    40  * Added support for loading Ogg Vorbis samples as an audio chunk
    41 Martin Storsj - Tue Jul 16 10:38:12 PDT 2002
    42  * Fixed to start playing another sample immediately when one finishes
    43 Martin Storsj - Tue May 28 13:08:29 PDT 2002
    44  * Fixed a volume bug when calling Mix_HaltChannel() on unused channel
    45 Xavier Wielemans - Wed Jun 12 14:28:14 EDT 2002
    46  * Fixed volume reset bug at end of channel fade.
    47 Ryan C. Gordon - Wed Jun 26 16:30:59 EDT 2002
    48  * Mix_LoadMUS() will now accept an MP3 by file extension, instead of relying
    49     entirely on the magic number.
    50 
    51 1.2.4:
    52 Sam Lantinga - Mon May 20 09:11:22 PDT 2002
    53  * Updated the CodeWarrior project files
    54 Sam Lantinga - Sun May 19 13:46:29 PDT 2002
    55  * Added a function to query the music format: Mix_GetMusicType()
    56 Sam Lantinga - Sat May 18 12:45:16 PDT 2002
    57  * Added a function to load audio data from memory: Mix_QuickLoad_RAW()
    58 Sam Lantinga - Thu May 16 11:26:46 PDT 2002
    59  * Cleaned up threading issues in the music playback code
    60 Ryan Gordon - Thu May  2 21:08:48 PDT 2002
    61  * Fixed deadlock introduced in the last release
    62 
    63 1.2.3:
    64 Sam Lantinga - Sat Apr 13 07:49:47 PDT 2002
    65  * Updated autogen.sh for new versions of automake
    66  * Specify the SDL API calling convention (C by default)
    67 Ryan Gordon - Sat Apr 13 07:33:37 PDT 2002
    68  * Fixed recursive audio lock in the mixing function
    69 jean-julien Filatriau - Sat Mar 23 18:05:37 PST 2002
    70  * Fixed setting invalid volume when querying mixer and music volumes
    71 Guillaume Cottenceau - Wed Feb 13 15:43:20 PST 2002
    72  * Implemented Ogg Vorbis stream rewinding
    73 Peter Kutak - Wed Feb 13 10:26:57 PST 2002
    74  * Added native midi support on Linux, using GPL code
    75 	--enable-music-native-midi-gpl
    76 Pete Shinners - Mon Jan 14 11:31:26 PST 2002
    77  * Added seek support for MP3 files
    78 Ryan Gordon - Mon Jan 14 11:30:44 PST 2002
    79  * Sample "finished" callbacks are now always called when a sample is stopped.
    80 
    81 1.2.2:
    82 Guillaume Cottenceau - Wed Dec 19 08:59:05 PST 2001
    83  * Added an API for seeking in music files (implemented for MOD and Ogg music)
    84 	Mix_FadeInMusicPos(), Mix_SetMusicPosition()
    85  * Exposed the mikmod synchro value for music synchronization
    86 	Mix_SetSynchroValue(), Mix_GetSynchroValue()
    87 
    88 1.2.1:
    89 Yi-Huang Han - Wed Oct 24 21:55:47 PDT 2001
    90  * Fixed MOD music volume when looping
    91 David Hedbor - Thu Oct 18 10:01:41 PDT 2001
    92  * Stop implicit looping, set fade out and other flags on MOD files
    93 Sam Lantinga - Tue Oct 16 11:17:12 PDT 2001
    94  * The music file type is now determined by extension as well as magic
    95 Ryan C. Gordon - Tue Sep 11 12:05:54 PDT 2001
    96  * Reworked playwave.c to make it more useful as a mixer testbed
    97  * Added a realtime sound effect API to SDL_mixer.h
    98  * Added the following standard sound effects:
    99 	panning, distance attenuation, basic positional audio, stereo reversal
   100  * Added API for mixer versioning: Mix_Linked_Version() and MIX_VERSION()
   101 Sam Lantinga - Tue Sep 11 11:48:53 PDT 2001
   102  * Updated MikMod code to version 3.1.9a
   103 Torbjrn Andersson - Tue Sep 11 11:22:29 PDT 2001
   104  * Added support for loading AIFF audio chunks
   105 Max Horn - Tue Sep  4 20:38:11 PDT 2001
   106  * Added native MIDI music support on MacOS and MacOS X
   107 Florian Schulze - Sun Aug 19 14:55:37 PDT 2001
   108  * Added native MIDI music support on Windows
   109 Sam Lantinga - Sun Aug 19 02:20:55 PDT 2001
   110  * Added Project Builder projects for building MacOS X framework
   111 Darrell Walisser - Sun Aug 19 00:47:22 PDT 2001
   112  * Fixed compilation problems with mikmod under MacOS X
   113 Torbjrn Andersson - Sun, 19 Aug 2001 16:03:30
   114  * Fixed AIFF music playing support
   115 Sam Lantinga - Sat Aug 18 04:14:13 PDT 2001
   116  * Fixed building Ogg Vorbis support on Windows
   117 Ryan C. Gordon - Thu, 7 Jun 2001 13:15:51
   118  * Added Mix_ChannelFinished() and Mix_GetChunk()
   119 Ryan C. Gordon - Tue, 5 Jun 2001 11:01:51
   120  * Added VOC sound file support
   121 Guillaume Cottenceau - Thu May 10 11:17:55 PDT 2001
   122  * Fixed crashes when API used with audio not initialized
   123 Paul Jenner - Sat, 14 Apr 2001 09:20:38 -0700 (PDT)
   124  * Added support for building RPM directly from tar archive
   125 
   126 1.2.0:
   127 Sam Lantinga - Wed Apr  4 12:42:20 PDT 2001
   128  * Synchronized release version with SDL 1.2.0
   129 
   130 1.1.1:
   131 John Hall - Tue Jan  2 13:46:54 PST 2001
   132  * Added support to playmus for track switching with Ctrl-C
   133  * Added support to playmus for multiple command line files
   134 
   135 1.1.0:
   136 Sam Lantinga - Wed Nov 29 20:47:13 PST 2000
   137  * Package specifically for SDL 1.1 (no real reason API-wise, but for clarity)
   138 
   139 1.0.7:
   140 Sam Lantinga - Tue Nov  7 10:22:09 PST 2000
   141  * Fixed hang in mikmod re-initialization
   142 Stephane Peter - Oct 17 13:07:32 PST 2000
   143  * Fixed music fading
   144 Ray Kelm - Fri, 04 Aug 2000 20:58:00 -0400
   145  * Added support for cross-compiling Windows DLL from Linux
   146 
   147 1.0.6:
   148 Sam Lantinga - Sun Jul  2 14:16:44 PDT 2000
   149  * Added support for the Ogg Vorbis music format: http://www.vorbis.org/
   150 Darrell Walisser - Wed Jun 28 11:59:40 PDT 2000
   151  * Added Codewarrior projects for MacOS
   152 Sam Lantinga - Mon Jun 26 12:01:11 PDT 2000
   153  * Fixed symbol aliasing problem with "channel"
   154 Matt - Wed, 12 Apr 2000 15:36:13 -0700
   155  * Added SDL_RWops support for mikmod loading (not hooked into music.c yet)
   156 
   157 1.0.5:
   158 Paul Furber - Fri Mar  3 14:58:50 PST 2000
   159  * Fixed MP3 detection with compilers that use signed char datatypes
   160 
   161 1.0.4:
   162 Sam Lantinga - Thu Feb 10 19:42:03 PST 2000
   163  * Ported the base mixer and mikmod libraries to MacOS
   164 Markus Oberhumer - Wed Feb  2 13:16:17 PST 2000
   165  * Fixed problem with short looping sounds
   166 Sam Lantinga - Tue Feb  1 13:25:44 PST 2000
   167  * Added Visual C++ project file
   168 Markus Oberhumer - Tue Feb  1 13:23:11 PST 2000
   169  * Cleaned up code for compiling with Visual C++
   170  * Don't hang in Mix_HaltMusic() if the music is paused
   171 Sam Lantinga - Fri Jan 28 08:54:56 PST 2000
   172  * Fixed looping WAVE chunks that are not aligned on sample boundaries
   173 
   174 1.0.3:
   175 Sam Lantinga - Mon Jan 17 19:48:09 PST 2000
   176  * Changed the name of the library from "mixer" to "SDL_mixer"
   177  * Instead of including "mixer.h", include "SDL_mixer.h",
   178  * Instead of linking with libmixer.a, link with libSDL_mixer.a
   179 
   180 1.0.2:
   181 Sam Lantinga - Fri Jan 14 11:06:56 PST 2000
   182  * Made the CHANGELOG entries Y2K compliant. :)
   183 MFX -	Updated the mikmod support to MikMod 3.1.8
   184 MFX -	Added Mix_HookMusicFinished() API function
   185 
   186 1.0.1:
   187 SOL -	Added a post-mixing callback
   188 SP  -	A few music-related bugfixes
   189 
   190 1.0.0:
   191 SOL -   Added autoconf support
   192 SP  -   Added MP3 support using SMPEG
   193 SP  -   Added fading in/out of music and samples
   194 SP  -   Added dynamic allocation of channels
   195 SP  -   Added channel grouping functions
   196 SP  -   Added expiration delay for samples
   197 
   198 Initial Key:
   199 SOL - Sam Lantinga (hercules@lokigames.com)
   200 SP  - Stephane Peter (megastep@lokigames.com)
   201 MFX - Markus Oberhumer (markus.oberhumer@jk.uni-linz.ac.at)