include/SDL_audio.h
changeset 9012 aa058c87737b
parent 8149 681eb46b8ac4
child 9619 b94b6d0bff0f
     1.1 --- a/include/SDL_audio.h	Sat Jul 26 16:52:26 2014 -0700
     1.2 +++ b/include/SDL_audio.h	Tue Jul 22 21:41:49 2014 -0400
     1.3 @@ -155,6 +155,9 @@
     1.4   *
     1.5   *  Once the callback returns, the buffer will no longer be valid.
     1.6   *  Stereo samples are stored in a LRLRLR ordering.
     1.7 + *
     1.8 + *  You can choose to avoid callbacks and use SDL_QueueAudio() instead, if
     1.9 + *  you like. Just open your audio device with a NULL callback.
    1.10   */
    1.11  typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
    1.12                                              int len);
    1.13 @@ -171,8 +174,8 @@
    1.14      Uint16 samples;             /**< Audio buffer size in samples (power of 2) */
    1.15      Uint16 padding;             /**< Necessary for some compile environments */
    1.16      Uint32 size;                /**< Audio buffer size in bytes (calculated) */
    1.17 -    SDL_AudioCallback callback;
    1.18 -    void *userdata;
    1.19 +    SDL_AudioCallback callback; /**< Callback that feeds the audio device (NULL to use SDL_QueueAudio()). */
    1.20 +    void *userdata;             /**< Userdata passed to callback (ignored for NULL callbacks). */
    1.21  } SDL_AudioSpec;
    1.22  
    1.23  
    1.24 @@ -273,9 +276,11 @@
    1.25   *      to the audio buffer, and the length in bytes of the audio buffer.
    1.26   *      This function usually runs in a separate thread, and so you should
    1.27   *      protect data structures that it accesses by calling SDL_LockAudio()
    1.28 - *      and SDL_UnlockAudio() in your code.
    1.29 + *      and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
    1.30 + *      pointer here, and call SDL_QueueAudio() with some frequency, to queue
    1.31 + *      more audio samples to be played.
    1.32   *    - \c desired->userdata is passed as the first parameter to your callback
    1.33 - *      function.
    1.34 + *      function. If you passed a NULL callback, this value is ignored.
    1.35   *
    1.36   *  The audio device starts out playing silence when it's opened, and should
    1.37   *  be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
    1.38 @@ -475,6 +480,100 @@
    1.39                                                  Uint32 len, int volume);
    1.40  
    1.41  /**
    1.42 + *  Queue more audio on non-callback devices.
    1.43 + *
    1.44 + *  SDL offers two ways to feed audio to the device: you can either supply a
    1.45 + *  callback that SDL triggers with some frequency to obtain more audio
    1.46 + *  (pull method), or you can supply no callback, and then SDL will expect
    1.47 + *  you to supply data at regular intervals (push method) with this function.
    1.48 + *
    1.49 + *  There are no limits on the amount of data you can queue, short of
    1.50 + *  exhaustion of address space. Queued data will drain to the device as
    1.51 + *  necessary without further intervention from you. If the device needs
    1.52 + *  audio but there is not enough queued, it will play silence to make up
    1.53 + *  the difference. This means you will have skips in your audio playback
    1.54 + *  if you aren't routinely queueing sufficient data.
    1.55 + *
    1.56 + *  This function copies the supplied data, so you are safe to free it when
    1.57 + *  the function returns. This function is thread-safe, but queueing to the
    1.58 + *  same device from two threads at once does not promise which buffer will
    1.59 + *  be queued first.
    1.60 + *
    1.61 + *  You may not queue audio on a device that is using an application-supplied
    1.62 + *  callback; doing so returns an error. You have to use the audio callback
    1.63 + *  or queue audio with this function, but not both.
    1.64 + *
    1.65 + *  You should not call SDL_LockAudio() on the device before queueing; SDL
    1.66 + *  handles locking internally for this function.
    1.67 + *
    1.68 + *  \param dev The device ID to which we will queue audio.
    1.69 + *  \param data The data to queue to the device for later playback.
    1.70 + *  \param len The number of bytes (not samples!) to which (data) points.
    1.71 + *  \return zero on success, -1 on error.
    1.72 + *
    1.73 + *  \sa SDL_GetQueuedAudioSize
    1.74 + *  \sa SDL_ClearQueuedAudio
    1.75 + */
    1.76 +extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
    1.77 +
    1.78 +/**
    1.79 + *  Get the number of bytes of still-queued audio.
    1.80 + *
    1.81 + *  This is the number of bytes that have been queued for playback with
    1.82 + *  SDL_QueueAudio(), but have not yet been sent to the hardware.
    1.83 + *
    1.84 + *  Once we've sent it to the hardware, this function can not decide the exact
    1.85 + *  byte boundary of what has been played. It's possible that we just gave the
    1.86 + *  hardware several kilobytes right before you called this function, but it
    1.87 + *  hasn't played any of it yet, or maybe half of it, etc.
    1.88 + *
    1.89 + *  You may not queue audio on a device that is using an application-supplied
    1.90 + *  callback; calling this function on such a device always returns 0.
    1.91 + *  You have to use the audio callback or queue audio with SDL_QueueAudio(),
    1.92 + *  but not both.
    1.93 + *
    1.94 + *  You should not call SDL_LockAudio() on the device before querying; SDL
    1.95 + *  handles locking internally for this function.
    1.96 + *
    1.97 + *  \param dev The device ID of which we will query queued audio size.
    1.98 + *  \return Number of bytes (not samples!) of queued audio.
    1.99 + *
   1.100 + *  \sa SDL_QueueAudio
   1.101 + *  \sa SDL_ClearQueuedAudio
   1.102 + */
   1.103 +extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
   1.104 +
   1.105 +/**
   1.106 + *  Drop any queued audio data waiting to be sent to the hardware.
   1.107 + *
   1.108 + *  Immediately after this call, SDL_GetQueuedAudioSize() will return 0 and
   1.109 + *  the hardware will start playing silence if more audio isn't queued.
   1.110 + *
   1.111 + *  This will not prevent playback of queued audio that's already been sent
   1.112 + *  to the hardware, as we can not undo that, so expect there to be some
   1.113 + *  fraction of a second of audio that might still be heard. This can be
   1.114 + *  useful if you want to, say, drop any pending music during a level change
   1.115 + *  in your game.
   1.116 + *
   1.117 + *  You may not queue audio on a device that is using an application-supplied
   1.118 + *  callback; calling this function on such a device is always a no-op.
   1.119 + *  You have to use the audio callback or queue audio with SDL_QueueAudio(),
   1.120 + *  but not both.
   1.121 + *
   1.122 + *  You should not call SDL_LockAudio() on the device before clearing the
   1.123 + *  queue; SDL handles locking internally for this function.
   1.124 + *
   1.125 + *  This function always succeeds and thus returns void.
   1.126 + *
   1.127 + *  \param dev The device ID of which to clear the audio queue.
   1.128 + *
   1.129 + *  \sa SDL_QueueAudio
   1.130 + *  \sa SDL_GetQueuedAudioSize
   1.131 + */
   1.132 +extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
   1.133 +
   1.134 +
   1.135 +/**
   1.136   *  \name Audio lock functions
   1.137   *
   1.138   *  The lock manipulated by these functions protects the callback function.