include/SDL_audio.h
changeset 2049 5f6550e5184f
parent 1985 8055185ae4ed
child 2655 b8e736c8a5a8
child 2720 4eb759edddf5
equal deleted inserted replaced
2048:6067c7f9a672 2049:5f6550e5184f
   151 } SDL_AudioCVT;
   151 } SDL_AudioCVT;
   152 
   152 
   153 
   153 
   154 /* Function prototypes */
   154 /* Function prototypes */
   155 
   155 
   156 /* These functions return the list of built in video drivers, in the 
   156 /* These functions return the list of built in audio drivers, in the
   157  * order that they are normally initialized by default.
   157  * order that they are normally initialized by default.
   158  */
   158  */
   159 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
   159 extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
   160 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
   160 extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
   161 
   161 
   210  * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
   210  * be enabled for playing by calling SDL_PauseAudio(0) when you are ready
   211  * for your audio callback function to be called.  Since the audio driver
   211  * for your audio callback function to be called.  Since the audio driver
   212  * may modify the requested size of the audio buffer, you should allocate
   212  * may modify the requested size of the audio buffer, you should allocate
   213  * any local mixing buffers after you open the audio device.
   213  * any local mixing buffers after you open the audio device.
   214  */
   214  */
   215 extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
   215 extern DECLSPEC int SDLCALL SDL_OpenAudio(const SDL_AudioSpec * desired,
   216                                           SDL_AudioSpec * obtained);
   216                                           SDL_AudioSpec * obtained);
   217 
   217 
   218 /*
   218 /*
   219  * SDL Audio Device IDs.
   219  * SDL Audio Device IDs.
   220  * A successful call to SDL_OpenAudio() is always device id 1, and legacy
   220  * A successful call to SDL_OpenAudio() is always device id 1, and legacy
   226 typedef Uint32 SDL_AudioDeviceID;
   226 typedef Uint32 SDL_AudioDeviceID;
   227 
   227 
   228 /*
   228 /*
   229  * Get the number of available devices exposed by the current driver.
   229  * Get the number of available devices exposed by the current driver.
   230  *  Only valid after a successfully initializing the audio subsystem.
   230  *  Only valid after a successfully initializing the audio subsystem.
       
   231  *  Returns -1 if an explicit list of devices can't be determined; this is
       
   232  *  not an error. For example, if SDL is set up to talk to a remote audio
       
   233  *  server, it can't list every one available on the Internet, but it will
       
   234  *  still allow a specific host to be specified to SDL_OpenAudioDevice().
       
   235  * In many common cases, when this function returns a value <= 0, it can still
       
   236  *  successfully open the default device (NULL for first argument of
       
   237  *  SDL_OpenAudioDevice()).
   231  */
   238  */
   232 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
   239 extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
   233 
   240 
   234 /*
   241 /*
   235  * Get the human-readable name of a specific audio device.
   242  * Get the human-readable name of a specific audio device.
   236  *  Must be a value between 0 and (number of audio devices-1).
   243  *  Must be a value between 0 and (number of audio devices-1).
   237  *  Only valid after a successfully initializing the audio subsystem.
   244  *  Only valid after a successfully initializing the audio subsystem.
   238  */
   245  *  The values returned by this function reflect the latest call to
   239 extern DECLSPEC const char *SDLCALL SDL_GetAudioDevice(int index,
   246  *  SDL_GetNumAudioDevices(); recall that function to redetect available
   240                                                        int iscapture);
   247  *  hardware.
   241 
   248  *
   242 
   249  * The string returned by this function is UTF-8 encoded, read-only, and
   243 /*
   250  *  managed internally. You are not to free it. If you need to keep the
   244  * Open a specific audio device. Passing in a device name of NULL is
   251  *  string for any length of time, you should make your own copy of it, as it
   245  *  equivalent to SDL_OpenAudio(). Returns 0 on error, a valid device ID
   252  *  will be invalid next time any of several other SDL functions is called.
   246  *  on success.
   253  */
       
   254 extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
       
   255                                                            int iscapture);
       
   256 
       
   257 
       
   258 /*
       
   259  * Open a specific audio device. Passing in a device name of NULL requests
       
   260  *  the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
       
   261  * The device name is a UTF-8 string reported by SDL_GetAudioDevice(), but
       
   262  *  some drivers allow arbitrary and driver-specific strings, such as a
       
   263  *  hostname/IP address for a remote audio server, or a filename in the
       
   264  *  diskaudio driver.
       
   265  * Returns 0 on error, a valid device ID that is >= 2 on success.
       
   266  *  SDL_OpenAudio(), unlike this function, always acts on device ID 1.
   247  */
   267  */
   248 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
   268 extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
   249                                                               *device,
   269                                                               *device,
   250                                                               int iscapture,
   270                                                               int iscapture,
   251                                                               const
   271                                                               const