include/SDL_audio.h
changeset 10262 aaed7b1f783a
parent 9998 f67cf37e9cd4
child 10638 d11daa346140
     1.1 --- a/include/SDL_audio.h	Sat Aug 06 02:45:51 2016 -0400
     1.2 +++ b/include/SDL_audio.h	Sat Aug 06 02:47:27 2016 -0400
     1.3 @@ -278,7 +278,8 @@
     1.4   *      protect data structures that it accesses by calling SDL_LockAudio()
     1.5   *      and SDL_UnlockAudio() in your code. Alternately, you may pass a NULL
     1.6   *      pointer here, and call SDL_QueueAudio() with some frequency, to queue
     1.7 - *      more audio samples to be played.
     1.8 + *      more audio samples to be played (or for capture devices, call
     1.9 + *      SDL_DequeueAudio() with some frequency, to obtain audio samples).
    1.10   *    - \c desired->userdata is passed as the first parameter to your callback
    1.11   *      function. If you passed a NULL callback, this value is ignored.
    1.12   *
    1.13 @@ -482,6 +483,10 @@
    1.14  /**
    1.15   *  Queue more audio on non-callback devices.
    1.16   *
    1.17 + *  (If you are looking to retrieve queued audio from a non-callback capture
    1.18 + *  device, you want SDL_DequeueAudio() instead. This will return -1 to
    1.19 + *  signify an error if you use it with capture devices.)
    1.20 + *
    1.21   *  SDL offers two ways to feed audio to the device: you can either supply a
    1.22   *  callback that SDL triggers with some frequency to obtain more audio
    1.23   *  (pull method), or you can supply no callback, and then SDL will expect
    1.24 @@ -517,20 +522,75 @@
    1.25  extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *data, Uint32 len);
    1.26  
    1.27  /**
    1.28 + *  Dequeue more audio on non-callback devices.
    1.29 + *
    1.30 + *  (If you are looking to queue audio for output on a non-callback playback
    1.31 + *  device, you want SDL_QueueAudio() instead. This will always return 0
    1.32 + *  if you use it with playback devices.)
    1.33 + *
    1.34 + *  SDL offers two ways to retrieve audio from a capture device: you can
    1.35 + *  either supply a callback that SDL triggers with some frequency as the
    1.36 + *  device records more audio data, (push method), or you can supply no
    1.37 + *  callback, and then SDL will expect you to retrieve data at regular
    1.38 + *  intervals (pull method) with this function.
    1.39 + *
    1.40 + *  There are no limits on the amount of data you can queue, short of
    1.41 + *  exhaustion of address space. Data from the device will keep queuing as
    1.42 + *  necessary without further intervention from you. This means you will
    1.43 + *  eventually run out of memory if you aren't routinely dequeueing data.
    1.44 + *
    1.45 + *  Capture devices will not queue data when paused; if you are expecting
    1.46 + *  to not need captured audio for some length of time, use
    1.47 + *  SDL_PauseAudioDevice() to stop the capture device from queueing more
    1.48 + *  data. This can be useful during, say, level loading times. When
    1.49 + *  unpaused, capture devices will start queueing data from that point,
    1.50 + *  having flushed any capturable data available while paused.
    1.51 + *
    1.52 + *  This function is thread-safe, but dequeueing from the same device from
    1.53 + *  two threads at once does not promise which thread will dequeued data
    1.54 + *  first.
    1.55 + *
    1.56 + *  You may not dequeue audio from a device that is using an
    1.57 + *  application-supplied callback; doing so returns an error. You have to use
    1.58 + *  the audio callback, or dequeue audio with this function, but not both.
    1.59 + *
    1.60 + *  You should not call SDL_LockAudio() on the device before queueing; SDL
    1.61 + *  handles locking internally for this function.
    1.62 + *
    1.63 + *  \param dev The device ID from which we will dequeue audio.
    1.64 + *  \param data A pointer into where audio data should be copied.
    1.65 + *  \param len The number of bytes (not samples!) to which (data) points.
    1.66 + *  \return number of bytes dequeued, which could be less than requested.
    1.67 + *
    1.68 + *  \sa SDL_GetQueuedAudioSize
    1.69 + *  \sa SDL_ClearQueuedAudio
    1.70 + */
    1.71 +extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *data, Uint32 len);
    1.72 +
    1.73 +/**
    1.74   *  Get the number of bytes of still-queued audio.
    1.75   *
    1.76 - *  This is the number of bytes that have been queued for playback with
    1.77 - *  SDL_QueueAudio(), but have not yet been sent to the hardware.
    1.78 + *  For playback device:
    1.79   *
    1.80 - *  Once we've sent it to the hardware, this function can not decide the exact
    1.81 - *  byte boundary of what has been played. It's possible that we just gave the
    1.82 - *  hardware several kilobytes right before you called this function, but it
    1.83 - *  hasn't played any of it yet, or maybe half of it, etc.
    1.84 + *    This is the number of bytes that have been queued for playback with
    1.85 + *    SDL_QueueAudio(), but have not yet been sent to the hardware. This
    1.86 + *    number may shrink at any time, so this only informs of pending data.
    1.87 + *
    1.88 + *    Once we've sent it to the hardware, this function can not decide the
    1.89 + *    exact byte boundary of what has been played. It's possible that we just
    1.90 + *    gave the hardware several kilobytes right before you called this
    1.91 + *    function, but it hasn't played any of it yet, or maybe half of it, etc.
    1.92 + *
    1.93 + *  For capture devices:
    1.94 + *
    1.95 + *    This is the number of bytes that have been captured by the device and
    1.96 + *    are waiting for you to dequeue. This number may grow at any time, so
    1.97 + *    this only informs of the lower-bound of available data.
    1.98   *
    1.99   *  You may not queue audio on a device that is using an application-supplied
   1.100   *  callback; calling this function on such a device always returns 0.
   1.101 - *  You have to use the audio callback or queue audio with SDL_QueueAudio(),
   1.102 - *  but not both.
   1.103 + *  You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
   1.104 + *  the audio callback, but not both.
   1.105   *
   1.106   *  You should not call SDL_LockAudio() on the device before querying; SDL
   1.107   *  handles locking internally for this function.
   1.108 @@ -544,10 +604,17 @@
   1.109  extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev);
   1.110  
   1.111  /**
   1.112 - *  Drop any queued audio data waiting to be sent to the hardware.
   1.113 + *  Drop any queued audio data. For playback devices, this is any queued data
   1.114 + *  still waiting to be submitted to the hardware. For capture devices, this
   1.115 + *  is any data that was queued by the device that hasn't yet been dequeued by
   1.116 + *  the application.
   1.117   *
   1.118 - *  Immediately after this call, SDL_GetQueuedAudioSize() will return 0 and
   1.119 - *  the hardware will start playing silence if more audio isn't queued.
   1.120 + *  Immediately after this call, SDL_GetQueuedAudioSize() will return 0. For
   1.121 + *  playback devices, the hardware will start playing silence if more audio
   1.122 + *  isn't queued. Unpaused capture devices will start filling the queue again
   1.123 + *  as soon as they have more data available (which, depending on the state
   1.124 + *  of the hardware and the thread, could be before this function call
   1.125 + *  returns!).
   1.126   *
   1.127   *  This will not prevent playback of queued audio that's already been sent
   1.128   *  to the hardware, as we can not undo that, so expect there to be some
   1.129 @@ -557,8 +624,8 @@
   1.130   *
   1.131   *  You may not queue audio on a device that is using an application-supplied
   1.132   *  callback; calling this function on such a device is always a no-op.
   1.133 - *  You have to use the audio callback or queue audio with SDL_QueueAudio(),
   1.134 - *  but not both.
   1.135 + *  You have to queue audio with SDL_QueueAudio()/SDL_DequeueAudio(), or use
   1.136 + *  the audio callback, but not both.
   1.137   *
   1.138   *  You should not call SDL_LockAudio() on the device before clearing the
   1.139   *  queue; SDL handles locking internally for this function.