|
Size: 2525
Comment: update content for consistency - non-zero
|
Size: 3223
Comment: Updated docs
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 20: | Line 20: |
| ||'''iscapture'''||non-zero to specify a device that has recording capability|| | ||'''iscapture'''||non-zero to specify a device should be opened for recording, not playback.|| |
| Line 26: | Line 26: |
| Returns a valid device ID that is >= 2 on success or 0 on failure; call [[SDL_GetError]]() for more information. | Returns a valid device ID that is > 0 on success or 0 on failure; call [[SDL_GetError]]() for more information. |
| Line 28: | Line 28: |
| <<Color2(green,Although it is implied here and in Remarks would it be of value to specify that the ID is >=2 because device 1 is already open or is otherwise the default?)>> | For compatibility with SDL 1.2, this will never return 1, since SDL reserves that ID for the legacy [[SDL_OpenAudio|SDL_OpenAudio]]() function. |
| Line 36: | Line 36: |
| <<Anchor(device)>> Passing in a '''device''' name of NULL requests the most reasonable default (and is equivalent to calling [[SDL_OpenAudio]]()). | <<Anchor(device)>> Passing in a '''device''' name of NULL requests the most reasonable default (and is equivalent to what [[SDL_OpenAudio]]() does to choose a device). |
| Line 45: | Line 45: |
| [[SDL_OpenAudio]](), unlike this function, always acts on device ID 1. | These flags specify how SDL should behave when a device cannot offer a specific feature. If the application requests a feature that the hardware doesn't offer, SDL will always try to get the closest equivalent. For example, if you ask for float32 audio format, but the sound card only supports int16, SDL will set the hardware to int16. If SDL_AUDIO_ALLOW_FORMAT_CHANGE is set, SDL will change the format in the '''obtained''' structure. If the SDL_AUDIO_ALLOW_FORMAT_CHANGE is ''not'' set, SDL will prepare to convert your callback's float32 audio to int16 before feeding it to the hardware. [[SDL_OpenAudio]](), unlike this function, always acts on device ID 1. As such, this function will never return a 1 so as not to conflict with the legacy function. |
SDL_OpenAudioDevice
Use this function to open a specific audio device.
Contents
Syntax
SDL_AudioDeviceID SDL_OpenAudioDevice(const char* device,
int iscapture,
const SDL_AudioSpec* desired,
SDL_AudioSpec* obtained,
int allowed_changes)
Function Parameters
device |
a UTF-8 string reported by SDL_GetAudioDeviceName(); see Remarks |
iscapture |
non-zero to specify a device should be opened for recording, not playback. |
desired |
the desired audio parameters -or- an SDL_AudioSpec structure representing the desired output format; see SDL_OpenAudio() for more information |
obtained |
an SDL_AudioSpec structure filled in with the actual output format; see SDL_OpenAudio() for more information |
allowed_changes |
0, or one or more flags OR'd together; see Remarks for details |
Return Value
Returns a valid device ID that is > 0 on success or 0 on failure; call SDL_GetError() for more information.
For compatibility with SDL 1.2, this will never return 1, since SDL reserves that ID for the legacy SDL_OpenAudio() function.
Code Examples
You can add your code example here
Remarks
Passing in a device name of NULL requests the most reasonable default (and is equivalent to what SDL_OpenAudio() does to choose a device). The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but some drivers allow arbitrary and driver-specific strings, such as a hostname/IP address for a remote audio server, or a filename in the diskaudio driver.
allowed_changes can have the following flags OR'd together:
SDL_AUDIO_ALLOW_FREQUENCY_CHANGE |
SDL_AUDIO_ALLOW_FORMAT_CHANGE |
SDL_AUDIO_ALLOW_CHANNELS_CHANGE |
SDL_AUDIO_ALLOW_ANY_CHANGE |
These flags specify how SDL should behave when a device cannot offer a specific feature. If the application requests a feature that the hardware doesn't offer, SDL will always try to get the closest equivalent.
For example, if you ask for float32 audio format, but the sound card only supports int16, SDL will set the hardware to int16. If SDL_AUDIO_ALLOW_FORMAT_CHANGE is set, SDL will change the format in the obtained structure. If the SDL_AUDIO_ALLOW_FORMAT_CHANGE is not set, SDL will prepare to convert your callback's float32 audio to int16 before feeding it to the hardware.
SDL_OpenAudio(), unlike this function, always acts on device ID 1. As such, this function will never return a 1 so as not to conflict with the legacy function.
