#pragma section-numbers off
#pragma disable-camelcase

= SDL_OpenAudio =
This function is a legacy means of opening the audio device. New programs might want to use [[SDL_OpenAudioDevice]]() instead.

<<TableOfContents()>>

== Syntax ==
{{{#!highlight cpp
int SDL_OpenAudio(SDL_AudioSpec* desired,
                  SDL_AudioSpec* obtained)
}}}

== Function Parameters ==
||'''desired''' ||an [[SDL_AudioSpec]] structure representing the desired output format||
||'''obtained''' ||an [[SDL_AudioSpec]] structure filled in with the actual parameters, or NULL||

== Return Value ==

This function opens the audio device with the desired parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by '''obtained'''.

If '''obtained''' is NULL, the audio data passed to the callback function will be guaranteed to be in the requested format, and will be automatically converted to the actual hardware audio format if necessary. If '''obtained''' is NULL, '''desired''' will have fields modified.

This function returns a negative error code on failure to open the audio device or failure to set up the audio thread; call [[SDL_GetError]]() for more information.

== Code Examples ==
{{{#!highlight cpp
SDL_AudioSpec want, have;

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 */

if (SDL_OpenAudio(&want, &have) < 0) {
    SDL_Log("Failed to open audio: %s", SDL_GetError());
} else {
    if (have.format != want.format) {
        SDL_Log("We didn't get Float32 audio format.");
    }
    SDL_PauseAudio(0); /* start audio playing. */
    SDL_Delay(5000); /* let the audio callback play some sound for 5 seconds. */
    SDL_CloseAudio();
}
}}}

== Remarks ==

This function remains for compatibility with SDL 1.2, but also because it's slightly easier to use than the new functions in SDL 2.0. The new, more powerful, and preferred way to do this is [[SDL_OpenAudioDevice]]().

This function is roughly equivalent to:
{{{#!highlight cpp
SDL_OpenAudioDevice(NULL, 0, desired, obtained, SDL_AUDIO_ALLOW_ANY_CHANGE);
}}}

With two notable exceptions:
 * If '''obtained''' is NULL, we use '''desired''' (and allow no changes), which means desired will be modified to have the correct values for silence, etc, and SDL will convert any differences between your app's specific request and the hardware behind the scenes.
 * The return value is always success or failure, and not a device ID, which means you can only have one device open at a time with this function.

== Related Functions ==
 .[[SDL_CloseAudio]]
 .[[SDL_LockAudio]]
 .[[SDL_PauseAudio]]
 .[[SDL_UnlockAudio]]

== Related Structures ==
 .[[SDL_AudioSpec]]

----
[[CategoryAPI]], CategoryAudio