X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/1c95530676f55d612383883ff383e24ecc7dc17d..f2620548144b356661614eba36c9de12ef31395c:/lib/uaudio.h

diff --git a/lib/uaudio.h b/lib/uaudio.h
index aa686d0..6592d53 100644
--- a/lib/uaudio.h
+++ b/lib/uaudio.h
@@ -34,6 +34,15 @@ extern size_t uaudio_sample_size;
  * @param max_samples How many samples to supply
  * @param userdata As passed to uaudio_open()
  * @return Number of samples filled
+ *
+ * This function should not block if possible (better to fill the buffer with
+ * 0s) and should definitely not block indefinitely.  This great caution with
+ * any locks or syscalls!  In particular avoid it taking a lock that may be
+ * held while any of the @ref uaudio members are called.
+ *
+ * If it's more convenient, it's OK to return less than the maximum number of
+ * samples (including 0) provided you expect to be called again for more
+ * samples immediately.
  */
 typedef size_t uaudio_callback(void *buffer,
                                size_t max_samples,
@@ -42,11 +51,33 @@ typedef size_t uaudio_callback(void *buffer,
 /** @brief Callback to play audio data
  * @param buffer Pointer to audio buffer
  * @param samples Number of samples to play
+ * @param flags Flags word
  * @return Number of samples played
  *
  * Used with uaudio_thread_start() etc.
+ *
+ * @p flags is a bitmap giving the current pause state and transitions:
+ * - @ref UAUDIO_PAUSE if this is the first call of a pause
+ * - @ref UAUDIO_RESUME if this is the first call of a resumse
+ * - @ref UAUDIO_PLAYING if this is outside a pause
+ * - @ref UAUDIO_PAUSED if this is in a pause
+ *
+ * During a pause, the sample data is guaranteed to be 0.
  */
-typedef size_t uaudio_playcallback(void *buffer, size_t samples);
+typedef size_t uaudio_playcallback(void *buffer, size_t samples,
+                                   unsigned flags);
+
+/** @brief Start of a pause */
+#define UAUDIO_PAUSE 0x0001
+
+/** @brief End of a pause */
+#define UAUDIO_RESUME 0x0002
+
+/** @brief Currently playing */
+#define UAUDIO_PLAYING 0x0004
+
+/** @brief Currently paused */
+#define UAUDIO_PAUSED 0x0008
 
 /** @brief Audio API definition */
 struct uaudio {
@@ -127,12 +158,14 @@ void uaudio_thread_start(uaudio_callback *callback,
 			 void *userdata,
 			 uaudio_playcallback *playcallback,
 			 size_t min,
-                         size_t max);
+                         size_t max,
+                         unsigned flags);
+
 void uaudio_thread_stop(void);
 void uaudio_thread_activate(void);
 void uaudio_thread_deactivate(void);
-void uaudio_schedule_synchronize(void);
-void uaudio_schedule_update(size_t written_samples);
+uint32_t uaudio_schedule_sync(void);
+void uaudio_schedule_sent(size_t nsamples_sent);
 void uaudio_schedule_init(void);
 const struct uaudio *uaudio_find(const char *name);