Clarify baseline scan checkpoint semantics

Author: telecos

crates/zune-jpeg/README.md

@@ -52,6 +52,13 @@ bodies, including baseline multi-SOS / non-interleaved images. Those images may
 still report no stable output rows until the later component scans have been
 decoded and final assembly has run.
 
+Scan checkpoints store only scalar resume state: stream position, next MCU
+row/column, restart countdown, SOS parameters, DC predictors, and bitstream
+state. Coefficients for already-decoded component scans stay on the decoder
+across retries. For multi-SOS images this means a retry can continue inside the
+current component scan, then decode later component scans, but output rows are
+not considered stable until final assembly has all component data.
+
 ```Rust
 use zune_core::bytestream::ZCursor;
 use zune_jpeg::JpegDecoder;

crates/zune-jpeg/src/decoder.rs

@@ -79,15 +79,15 @@ pub type IDCTPtr = fn(&mut [i32; 64], &mut [i16], usize);
 
 /// Scan-phase state kept so `decode_into` can retry or replay after SOS.
 ///
-/// Full replay starts at the first SOS; `rst_checkpoint` can resume from a
+/// Full replay starts at the first SOS; `scan_checkpoint` can resume from a
 /// later restart or row boundary when one is still valid.
 #[derive(Clone)]
 pub(crate) struct ScanDecodeState {
     pub(crate) scan_start_position: usize,
     pub(crate) append_snapshot:     HeaderAppendStateSnapshot,
     pub(crate) sos_snapshot:        SosParamsSnapshot,
     pub(crate) header_snapshot:     ScanHeaderStateSnapshot,
-    pub(crate) rst_checkpoint:      Option<Box<ScanCheckpoint>>
+    pub(crate) scan_checkpoint:     Option<Box<ScanCheckpoint>>
 }
 
 /// SOS fields restored before replaying scan data.
@@ -402,15 +402,15 @@ where
             append_snapshot,
             sos_snapshot,
             header_snapshot,
-            rst_checkpoint: None
+            scan_checkpoint: None
         }));
         Ok(())
     }
 
     pub(crate) fn scan_checkpoint(&self) -> Option<&ScanCheckpoint> {
         self.scan_state
             .as_deref()
-            .and_then(|state| state.rst_checkpoint.as_deref())
+            .and_then(|state| state.scan_checkpoint.as_deref())
     }
 
     // Save a scan checkpoint at the current restart or MCU-row boundary.
@@ -456,9 +456,9 @@ where
                 dc_predictions,
                 bitstream_state
             };
-            match &mut state.rst_checkpoint {
+            match &mut state.scan_checkpoint {
                 Some(existing) => **existing = snapshot,
-                None => state.rst_checkpoint = Some(Box::new(snapshot))
+                None => state.scan_checkpoint = Some(Box::new(snapshot))
             }
         }
         Ok(())
@@ -476,7 +476,7 @@ where
     /// replaying from scan start.
     pub(crate) fn invalidate_scan_checkpoint(&mut self) {
         if let Some(state) = self.scan_state.as_mut() {
-            state.rst_checkpoint = None;
+            state.scan_checkpoint = None;
         }
     }
 
@@ -1339,7 +1339,7 @@ where
             outer_append_snapshot: state.append_snapshot,
             outer_sos_snapshot:    state.sos_snapshot,
             outer_header_snapshot: state.header_snapshot.clone(),
-            checkpoint_view:       state.rst_checkpoint.as_deref().map(|checkpoint| {
+            checkpoint_view:       state.scan_checkpoint.as_deref().map(|checkpoint| {
                 CheckpointView {
                     append_snapshot: checkpoint.append_snapshot,
                     sos_snapshot:    checkpoint.sos_snapshot,
@@ -1461,15 +1461,15 @@ where
 
         match result {
             Ok(()) => {
-                // Drop the RST checkpoint so a post-success replay starts
+                // Drop the scan checkpoint so a post-success replay starts
                 // from scan-start with zeroed DC predictors instead of
                 // pointing at stale entropy data.
                 debug_assert!(
                     self.scan_state.is_some(),
                     "scan_state should be Some after a successful scan decode"
                 );
                 if let Some(state) = self.scan_state.as_deref_mut() {
-                    state.rst_checkpoint = None;
+                    state.scan_checkpoint = None;
                 }
                 self.pixels_decoded = expected_size;
                 Ok(())

crates/zune-jpeg/src/lib.rs

@@ -62,6 +62,13 @@
 //! still report no stable output rows until the later component scans have been
 //! decoded and final assembly has run.
 //!
+//! Scan checkpoints store only scalar resume state: stream position, next MCU
+//! row/column, restart countdown, SOS parameters, DC predictors, and bitstream
+//! state. Coefficients for already-decoded component scans stay on the decoder
+//! across retries. For multi-SOS images this means a retry can continue inside the
+//! current component scan, then decode later component scans, but output rows are
+//! not considered stable until final assembly has all component data.
+//!
 //! ```no_run
 //! use zune_core::bytestream::ZCursor;
 //! use zune_jpeg::errors::DecodeErrors;

crates/zune-jpeg/src/mcu.rs

@@ -67,7 +67,7 @@ impl<T: ZByteReaderTrait> JpegDecoder<T> {
         // Move the persistent multi-SOS coefficient buffer out of `self` so
         // the inner decoder can borrow it mutably while still calling methods
         // on `self`. The buffer is put back on return and survives across
-        // `decode_into` retries, which is what lets per-RST checkpoints stay
+        // `decode_into` retries, which is what lets scan checkpoints stay
         // allocation-free.
         let mut progressive_mcus = core::mem::take(&mut self.progressive_mcus_buffer);
         let result = self.decode_mcu_ycbcr_baseline_inner::<B>(pixels, &mut progressive_mcus);
@@ -147,7 +147,7 @@ impl<T: ZByteReaderTrait> JpegDecoder<T> {
         let mut tmp = [0_i32; DCT_BLOCK];
 
         let comp_len = self.components.len();
-        // True when we are resuming from a previously-saved RST checkpoint;
+        // True when we are resuming from a previously-saved scan checkpoint;
         // in that case the per-component `raw_coeff` and `progressive_mcus`
         // buffers still hold the data from the prior `decode_into` call and
         // must not be re-zeroed. On a fresh decode they are (re-)allocated.