[SDL] SDL 1.3 audio API proposal...

[Ryan C. Gordon]

Ok, here's the current proposal for SDL 1.3 audio API changes. Nothing 
in here is final, including new symbol names. Comments and complaints 
are welcome.

http://www.libsdl.org/cgi/viewvc.cgi/trunk/SDL/include/SDL_audio.h?r1=2609&r2=2685

The API changes are in Subversion for 1.3, but the actual 
implementations are not, yet.


The basic gist:

- Macros to extract information from AUDIO_* values:

      printf("AUDIO_S16LSB is %d bits per sample.\n",
             (int) SDL_AUDIO_BITSIZE(AUDIO_S16LSB));

      if (SDL_AUDIO_ISSIGNED(AUDIO_S16LSB))
          printf("AUDIO_S16LSB is a signed data type.\n");
      if (SDL_AUDIO_ISBIGENDIAN(AUDIO_S16MSB))
          printf("AUDIO_S16LSB is bigendian.\n");


- New data types: 32-bit int and floating point samples (AUDIO_S32LSB, 
AUDIO_F32LSB, etc). This will allow better range, and a fast path for 
Mac OS X's CoreAudio. 32-bit types are always signed, but can be in 
either byte order.

- Multiple audio devices. If a given API exposes multiple devices--for 
example, DirectSound can see a Sound Blaster Live, the motherboard's 
ac97 chip, and a USB headset--then all three will be available for 
seperate control by the application. Opening a specific device with the 
new APIs will give you an SDL_AudioDeviceID handle. The old APIs will 
continue to exist (and treat the unnamed device as ID #1), which allows 
backwards compatibility for those that don't care about multiple 
devices. APIs to match the old functionality but accept a device ID are 
being added, as well as functionality to enumerate available devices.

- Audio disconnect notifications. The app can be notified if a 
USB/firewire device has been unplugged, or an esound server has dropped 
the connection, etc.

- SDL_MixAudioFormat(): mix a sound buffer in an arbitrary format, 
instead of whatever format the audio device is opened to use. Doesn't 
require an open audio device at all.

- Capture support: the multiple device support also allows for devices 
to be opened for capture (recording). These function as separate logical 
devices, even if it's all on the same sound card.

--ryan.