Tentative audio API

I’m thinking about extending the audio API to make it easier to port
some kinds of software:

These functions can only be used if you pass a NULL callback to the
SDL_OpenAudio(), as they are implemented using an internal callback.
They should be nearly as close to the hardware as the existing API.
I will improve the API until this is true, and if I can’t, I’ll trash it.



  • This function queues audio data to the internal audio buffers, blocking
  • until the data can be completely written.*
  • This function can only be used if you set a NULL callback in the audio
  • struct passed to SDL_OpenAudio().
    SDL_DEFUN(void, SDL_WriteAudio, (Uint8 *data, int len))


  • This function sets the internal audio buffers to a user-defined area
  • of memory. If ‘area’ is NULL, the default internal buffers are used.
  • It returns 0 if everything went well, or -1 if the buffer was too small
  • (smaller than the audio fragment size in audiospec.samples) or if you
  • did not set a NULL callback in the audio struct passed to SDL_OpenAudio()
    SDL_DEFUN(int, SDL_SetAudioBuf, (Uint8 *bufp, int len))


  • This function locks the audio thread and returns the current audio
  • buffer and position within that buffer. The position is the current
  • write position, which is typically one fragment size later than the
  • current play position. You may pass NULL for any parameter.
  • The audio buffer is only valid until you unlock the buffer with a
  • call to SDL_LockAudioBuf(). You shouldn’t leave the audio buffer
  • locked for long, or the audio may pause, or crackle and pop.
    SDL_DEFUN(void, SDL_LockAudioBuf, (Uint8 **bufp, int *len, int *pos))


  • This function unlocks the audio thread after a previous call to

  • SDL_LockAudioBuf().
    SDL_DEFUN(void, SDL_UnlockAudioBuf, (void))

    -Sam Lantinga (slouken at devolution.com)

Lead Programmer, Loki Entertainment Software

“Any sufficiently advanced bug is indistinguishable from a feature”
– Rich Kulawiec