docs(jpeg): clarify incremental decode contract

Author: telecos

crates/zune-jpeg/README.md

@@ -27,6 +27,51 @@ fn main()->Result<(),DecoderErrors> {
 The decoder supports more manipulations via `DecoderOptions`,
 see additional documentation in the library.
 
+### Incremental input
+
+`JpegDecoder` can be retried on the same decoder when the underlying reader can
+see more bytes later. Callers should treat `DecodeErrors::is_recoverable_eof()`
+as the signal to feed more input and retry; any other error is a hard decode
+failure.
+
+After `decode_headers()` succeeds, `info()` and `output_buffer_size()` are
+available. During `decode_into()`, the same decoder and output buffer must be
+kept across retries. If scan decoding returns recoverable EOF,
+`decoded_output_bytes()` and `decoded_scanlines()` report the stable prefix of
+the output buffer that can be displayed or copied before retrying.
+
+```Rust
+use zune_core::bytestream::ZCursor;
+use zune_jpeg::JpegDecoder;
+
+let mut decoder = JpegDecoder::new(ZCursor::new(&jpeg_bytes));
+
+loop {
+  match decoder.decode_headers() {
+    Ok(()) => break,
+    Err(error) if error.is_recoverable_eof() => {
+      // Make more input bytes visible to the same reader, then retry.
+    }
+    Err(error) => return Err(error)
+  }
+}
+
+let mut pixels = vec![0; decoder.output_buffer_size().unwrap()];
+
+loop {
+  match decoder.decode_into(&mut pixels) {
+    Ok(()) => break,
+    Err(error) if error.is_recoverable_eof() => {
+      let stable_bytes = decoder.decoded_output_bytes().unwrap_or(0);
+      let stable_scanlines = decoder.decoded_scanlines().unwrap_or(0);
+      // Display or copy the stable prefix, feed more input, then retry
+      // with the same decoder and `pixels` buffer.
+    }
+    Err(error) => return Err(error)
+  }
+}
+```
+
 ## Goals
 
 The implementation aims to have the following goals achieved,

crates/zune-jpeg/src/decoder.rs

@@ -621,6 +621,17 @@ where
         };
     }
 
+    /// Return the number of output bytes known to be stable after the most
+    /// recent `decode_into` attempt.
+    ///
+    /// On recoverable EOF this is the prefix the caller may display or copy,
+    /// provided the next retry uses the same decoder and output buffer. It is
+    /// `None` until headers are complete and the output layout is known.
+    #[must_use]
+    pub fn decoded_output_bytes(&self) -> Option<usize> {
+        Some(self.pixels_decoded.min(self.output_buffer_size()?))
+    }
+
     /// Return the number of output scanlines known to be stable after the
     /// most recent `decode_into` attempt.
     ///
@@ -629,17 +640,14 @@ where
     /// call `decode_into` again to continue decoding.
     #[must_use]
     pub fn decoded_scanlines(&self) -> Option<usize> {
-        if !self.headers_decoded {
-            return None;
-        }
-
+        let decoded_output_bytes = self.decoded_output_bytes()?;
         let row_stride = usize::from(self.width())
             .checked_mul(self.options.jpeg_get_out_colorspace().num_components())?;
         if row_stride == 0 {
             return Some(0);
         }
 
-        Some((self.pixels_decoded / row_stride).min(usize::from(self.height())))
+        Some((decoded_output_bytes / row_stride).min(usize::from(self.height())))
     }
 
     /// Get an immutable reference to the decoder options
@@ -1220,7 +1228,15 @@ where
     ///
     /// On a recoverable EOF (`DecodeErrors::is_recoverable_eof()`) the
     /// decoder keeps enough state to resume; the caller can grow the input
-    /// stream and call `decode_into` again.
+    /// stream and call `decode_into` again. The caller must keep using the
+    /// same decoder and output buffer for retries. After a recoverable scan
+    /// EOF, [`decoded_output_bytes`](Self::decoded_output_bytes) and
+    /// [`decoded_scanlines`](Self::decoded_scanlines) describe the stable
+    /// prefix in that output buffer.
+    ///
+    /// Embedders should use the returned error to distinguish retryable EOF
+    /// from hard failures: `Err(e)` where `e.is_recoverable_eof()` means feed
+    /// more input and retry, while any other `Err` is non-recoverable.
     ///
     /// On success the decoder keeps scan-start replay state, so a later
     /// `decode_into` call is well-defined and produces bit-identical pixels.
@@ -1431,7 +1447,9 @@ where
     ///
     /// If the reader runs out of data the error will satisfy
     /// [`is_recoverable_eof()`](crate::errors::DecodeErrors::is_recoverable_eof);
-    /// the caller may retry after providing more data.
+    /// the caller may retry after providing more data. After success,
+    /// [`output_buffer_size`](Self::output_buffer_size) and [`info`](Self::info)
+    /// are available.
     pub fn decode_headers(&mut self) -> Result<(), DecodeErrors> {
         self.decode_headers_internal()?;
         Ok(())

crates/zune-jpeg/tests/incremental.rs

@@ -236,8 +236,16 @@ fn decode_into_replay_after_success_matches_oneshot() {
 fn incomplete_data_returns_recoverable_eof() {
     // Empty input → recoverable EOF
     let mut dec = JpegDecoder::new(ZCursor::new(&[] as &[u8]));
+    assert!(dec.info().is_none());
+    assert_eq!(dec.output_buffer_size(), None);
+    assert_eq!(dec.decoded_output_bytes(), None);
+    assert_eq!(dec.decoded_scanlines(), None);
     let err = dec.decode_headers().unwrap_err();
     assert!(err.is_recoverable_eof(), "empty input: expected recoverable EOF, got: {err:?}");
+    assert!(dec.info().is_none());
+    assert_eq!(dec.output_buffer_size(), None);
+    assert_eq!(dec.decoded_output_bytes(), None);
+    assert_eq!(dec.decoded_scanlines(), None);
 
     // Truncated just after SOI → recoverable EOF
     let data = include_bytes!("../../../test-images/jpeg/synthetic_image.jpg");
@@ -249,6 +257,10 @@ fn incomplete_data_returns_recoverable_eof() {
     let mut dec = JpegDecoder::new(ZCursor::new(&[0x00, 0x00]));
     let err = dec.decode_headers().unwrap_err();
     assert!(!err.is_recoverable_eof(), "bad magic: should not be recoverable, got: {err:?}");
+    assert!(dec.info().is_none());
+    assert_eq!(dec.output_buffer_size(), None);
+    assert_eq!(dec.decoded_output_bytes(), None);
+    assert_eq!(dec.decoded_scanlines(), None);
 
     // Non-EOF error variants → NOT recoverable
     use zune_jpeg::errors::DecodeErrors;
@@ -1271,6 +1283,8 @@ fn per_row_checkpoint_avoids_full_scan_replay() {
     decoder
         .decode_headers()
         .expect("headers should be fully visible at cutoff");
+    assert_eq!(decoder.decoded_output_bytes(), Some(0));
+    assert_eq!(decoder.decoded_scanlines(), Some(0));
     let mut out = vec![0u8; decoder.output_buffer_size().unwrap()];
 
     // First decode attempt — should fail with recoverable EOF.
@@ -1285,6 +1299,11 @@ fn per_row_checkpoint_avoids_full_scan_replay() {
     let first_scanlines = decoder
         .decoded_scanlines()
         .expect("headers are decoded, so partial progress should be known");
+    let first_bytes = decoder
+        .decoded_output_bytes()
+        .expect("headers are decoded, so partial progress should be known");
+    assert!(first_bytes > 0, "scan EOF should expose a stable output prefix");
+    assert!(first_bytes < out.len(), "truncated decode should not report full output");
     assert!(
         first_scanlines > 0 && first_scanlines < usize::from(decoder.info().unwrap().height),
         "expected a stable partial prefix, got {first_scanlines} scanlines"
@@ -1300,6 +1319,8 @@ fn per_row_checkpoint_avoids_full_scan_replay() {
         err.is_recoverable_eof(),
         "expected recoverable EOF on second attempt, got {err:?}"
     );
+    assert!(decoder.decoded_output_bytes().unwrap() >= first_bytes);
+    assert!(decoder.decoded_scanlines().unwrap() >= first_scanlines);
 
     // Third attempt — expose full data. Should resume from the per-row
     // checkpoint saved during the second attempt.
@@ -1309,6 +1330,11 @@ fn per_row_checkpoint_avoids_full_scan_replay() {
         .decode_into(&mut out)
         .expect("full data should allow decode to complete");
     assert_pixels_match(&out, &expected, "per_row_checkpoint", data.len());
+    assert_eq!(
+        decoder.decoded_output_bytes(),
+        Some(out.len()),
+        "successful decode should report the full output buffer as stable"
+    );
     assert_eq!(
         decoder.decoded_scanlines(),
         Some(usize::from(decoder.info().unwrap().height)),