include/SDL_audio.h
changeset 2049 5f6550e5184f
parent 1985 8055185ae4ed
child 2655 b8e736c8a5a8
child 2720 4eb759edddf5
     1.1 --- a/include/SDL_audio.h	Sun Oct 01 16:10:41 2006 +0000
     1.2 +++ b/include/SDL_audio.h	Tue Oct 17 09:15:21 2006 +0000
     1.3 @@ -153,7 +153,7 @@
     1.4  
     1.5  /* Function prototypes */
     1.6  
     1.7 -/* These functions return the list of built in video drivers, in the 
     1.8 +/* These functions return the list of built in audio drivers, in the
     1.9   * order that they are normally initialized by default.
    1.10   */
    1.11  extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
    1.12 @@ -212,7 +212,7 @@
    1.13   * may modify the requested size of the audio buffer, you should allocate
    1.14   * any local mixing buffers after you open the audio device.
    1.15   */
    1.16 -extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
    1.17 +extern DECLSPEC int SDLCALL SDL_OpenAudio(const SDL_AudioSpec * desired,
    1.18                                            SDL_AudioSpec * obtained);
    1.19  
    1.20  /*
    1.21 @@ -228,6 +228,13 @@
    1.22  /*
    1.23   * Get the number of available devices exposed by the current driver.
    1.24   *  Only valid after a successfully initializing the audio subsystem.
    1.25 + *  Returns -1 if an explicit list of devices can't be determined; this is
    1.26 + *  not an error. For example, if SDL is set up to talk to a remote audio
    1.27 + *  server, it can't list every one available on the Internet, but it will
    1.28 + *  still allow a specific host to be specified to SDL_OpenAudioDevice().
    1.29 + * In many common cases, when this function returns a value <= 0, it can still
    1.30 + *  successfully open the default device (NULL for first argument of
    1.31 + *  SDL_OpenAudioDevice()).
    1.32   */
    1.33  extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
    1.34  
    1.35 @@ -235,15 +242,28 @@
    1.36   * Get the human-readable name of a specific audio device.
    1.37   *  Must be a value between 0 and (number of audio devices-1).
    1.38   *  Only valid after a successfully initializing the audio subsystem.
    1.39 + *  The values returned by this function reflect the latest call to
    1.40 + *  SDL_GetNumAudioDevices(); recall that function to redetect available
    1.41 + *  hardware.
    1.42 + *
    1.43 + * The string returned by this function is UTF-8 encoded, read-only, and
    1.44 + *  managed internally. You are not to free it. If you need to keep the
    1.45 + *  string for any length of time, you should make your own copy of it, as it
    1.46 + *  will be invalid next time any of several other SDL functions is called.
    1.47   */
    1.48 -extern DECLSPEC const char *SDLCALL SDL_GetAudioDevice(int index,
    1.49 -                                                       int iscapture);
    1.50 +extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
    1.51 +                                                           int iscapture);
    1.52  
    1.53  
    1.54  /*
    1.55 - * Open a specific audio device. Passing in a device name of NULL is
    1.56 - *  equivalent to SDL_OpenAudio(). Returns 0 on error, a valid device ID
    1.57 - *  on success.
    1.58 + * Open a specific audio device. Passing in a device name of NULL requests
    1.59 + *  the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
    1.60 + * The device name is a UTF-8 string reported by SDL_GetAudioDevice(), but
    1.61 + *  some drivers allow arbitrary and driver-specific strings, such as a
    1.62 + *  hostname/IP address for a remote audio server, or a filename in the
    1.63 + *  diskaudio driver.
    1.64 + * Returns 0 on error, a valid device ID that is >= 2 on success.
    1.65 + *  SDL_OpenAudio(), unlike this function, always acts on device ID 1.
    1.66   */
    1.67  extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
    1.68                                                                *device,