ref: ae08430fba74624a971e7bf77ec1a31bbb26a034
parent: 560dc6848ad6fa9e7037f8f795a2194a4242511e
author: James Almer <jamrial@gmail.com>
date: Tue Nov 27 10:25:43 EST 2018
Add a simple API usage example to the doxy Based on the implementation from tools/dav1d.c
--- a/include/dav1d/dav1d.h
+++ b/include/dav1d/dav1d.h
@@ -128,6 +128,39 @@
*
* @note To drain buffered frames from the decoder (i.e. on end of stream),
* call this function until it returns -EAGAIN.
+ *
+ * @code{.c}+ * Dav1dData data = { 0 };+ * Dav1dPicture p = { 0 };+ * int res;
+ *
+ * read_data(&data);
+ * do {+ * res = dav1d_send_data(c, &data);
+ * // Keep going even if the function can't consume the current data
+ * packet. It eventually will after one or more frames have been
+ * returned in this loop.
+ * if (res < 0 && res != -EAGAIN)
+ * free_and_abort();
+ * res = dav1d_get_picture(c, &p);
+ * if (res < 0) {+ * if (res != -EAGAIN)
+ * free_and_abort();
+ * } else
+ * output_and_unref_picture(&p);
+ * // Stay in the loop as long as there's data to consume.
+ * } while (data.sz || read_data(&data) == SUCCESS);
+ *
+ * // Handle EOS by draining all buffered frames.
+ * do {+ * res = dav1d_get_picture(c, &p);
+ * if (res < 0) {+ * if (res != -EAGAIN)
+ * free_and_abort();
+ * } else
+ * output_and_unref_picture(&p);
+ * } while (res == 0);
+ * @endcode
*/
DAV1D_API int dav1d_get_picture(Dav1dContext *c, Dav1dPicture *out);