Document that get_picture() should be called only once per submitte…

…d input frame

Otherwise the decoder can't make best use of frame threading and will
also more likely run into a race condition in dav1d that causes a
deadlock.

Instead calling it in a loop should only happen at the very end to drain
all pending frames.

Update the example accordingly.

Fixes #72

src/lib.rs

@@ -320,6 +320,10 @@ impl Decoder {
     ///
     /// If this returns `Err([Error::Again])` then further data has to be sent to the decoder
     /// before further decoded frames become available.
+    ///
+    /// To make most use of frame threading this function should only be called once per submitted
+    /// input frame and not until it returns `Err([Error::Again])`. Calling it in a loop should
+    /// only be done to drain all pending frames at the end.
     pub fn get_picture(&mut self) -> Result<Picture, Error> {
         unsafe {
             let mut pic: Dav1dPicture = mem::zeroed();

tools/src/main.rs

@@ -74,7 +74,7 @@ struct Opt {
 use std::fs::File;
 use std::io::BufReader;
 
-fn handle_pending_pictures(dec: &mut dav1d::Decoder) {
+fn handle_pending_pictures(dec: &mut dav1d::Decoder, drain: bool) {
     loop {
         match dec.get_picture() {
             Ok(p) => println!("{:?}", p),
@@ -84,6 +84,10 @@ fn handle_pending_pictures(dec: &mut dav1d::Decoder) {
                 panic!("Error getting decoded pictures: {}", e);
             }
         }
+
+        if !drain {
+            break;
+        }
     }
 }
 
@@ -107,7 +111,7 @@ fn main() -> std::io::Result<()> {
                 // pending pictures and send pending data to the decoder
                 // until it is all used up.
                 loop {
-                    handle_pending_pictures(&mut dec);
+                    handle_pending_pictures(&mut dec, false);
 
                     match dec.send_pending_data() {
                         Err(e) if e.is_again() => continue,
@@ -125,8 +129,11 @@ fn main() -> std::io::Result<()> {
         }
 
         // Handle all pending pictures before sending the next data.
-        handle_pending_pictures(&mut dec);
+        handle_pending_pictures(&mut dec, false);
     }
 
+    // Handle all pending pictures that were not output yet.
+    handle_pending_pictures(&mut dec, true);
+
     Ok(())
 }