This is new wiki software and old wiki content. It's a work in progress!
Here's the explanation.
Be gentle, report bugs, leave feedback on pages, or just edit them yourself! Thanks!

SDL Wiki

SDL_OpenAudioDevice

Open a specific audio device.

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() or a driver-specific name as appropriate. NULL requests the most reasonable default device.

iscapture

non-zero to specify a device should be opened for recording, not playback

desired

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

Return Value

Returns a valid device ID that is > 0 on success or 0 on failure; call SDL_GetError() for more information.

Remarks

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.

Please note that SDL 2.0 before 2.0.5 did not support recording; as such, this function would fail if iscapture was not zero. Starting with SDL 2.0.5, recording is implemented and this value can be non-zero.

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.

When filling in the desired audio spec structure:

allowed_changes can have the following flags OR'd together:

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 you had set SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the obtained structure. If that flag was ''not* set, SDL will prepare to convert your callback's float32 audio to int16 before feeding it to the hardware and will keep the originally requested format in the obtained structure.

If your application can only handle one specific data format, pass a zero for allowed_changes and let SDL transparently handle any differences.

An opened audio device starts out paused, and should be enabled for playing by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio callback function to be called. Since the audio driver may modify the requested size of the audio buffer, you should allocate any local mixing buffers after you open the audio device.

The audio callback runs in a separate thread in most cases; you can prevent race conditions between your callback and other threads without fully pausing playback with SDL_LockAudioDevice(). For more information about the callback, see SDL_AudioSpec.

Version

This function is available since SDL 2.0.0.

Code Examples


SDL_AudioSpec want, have;
SDL_AudioDeviceID dev;

SDL_memset(&want, 0, sizeof(want)); /* or SDL_zero(want) */
want.freq = 48000;
want.format = AUDIO_F32;
want.channels = 2;
want.samples = 4096;
want.callback = MyAudioCallback; /* you wrote this function elsewhere -- see SDL_AudioSpec for details */

dev = SDL_OpenAudioDevice(NULL, 0, &want, &have, SDL_AUDIO_ALLOW_FORMAT_CHANGE);
if (dev == 0) {
    SDL_Log("Failed to open audio: %s", SDL_GetError());
} else {
    if (have.format != want.format) { /* we let this one thing change. */
        SDL_Log("We didn't get Float32 audio format.");
    }
    SDL_PauseAudioDevice(dev, 0); /* start audio playing. */
    SDL_Delay(5000); /* let the audio callback play some sound for 5 seconds. */
    SDL_CloseAudioDevice(dev);
}
SDL_CloseAudioDevice
SDL_GetAudioDeviceName
SDL_LockAudioDevice
SDL_OpenAudio
SDL_PauseAudioDevice
SDL_UnlockAudioDevice

CategoryAPI, CategoryAudio


[ edit | delete | history | feedback | raw ]

[ front page | index | search | recent changes | git repo | offline html ]

All wiki content is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Wiki powered by ghwikipp.