New public API: pub fn expand_interlaced_row.

This also exposes `InterlaceInfo` as a public API.

src/adam7.rs

@@ -138,27 +138,39 @@ fn expand_adam7_bits(
         .map(move |bits_offset| bits_offset + line_start)
 }
 
-/// Expands an Adam 7 pass
+/// Copies pixels from `interlaced_row` into the right location in `img`.
+///
+/// First bytes of `img` should belong to the top-left corner of the currently decoded frame.
+///
+/// `img_row_stride` specifies an offset in bytes between subsequent rows of `img`.
+/// This can be the width of the current frame being decoded, but this is not required - a bigger
+/// stride may be useful if the frame being decoded is a sub-region of `img`.
+///
+/// `interlaced_row` and `interlace_info` typically come from `Reader.next_interlaced_row`, but
+/// this is not required.  In particular, before calling `expand_interlaced_row` one may need to
+/// expand the decoded row, so that its format and `bits_per_pixel` matches that of `img`.
+/// Note that in initial Adam7 passes the `interlaced_row` may contain less pixels that the width
+/// of the frame being decoded (e.g. it contains only 1/8th of pixels in the initial pass).
 pub fn expand_pass(
     img: &mut [u8],
-    stride: usize,
-    scanline: &[u8],
-    info: &InterlaceInfo,
-    bits_pp: u8,
+    img_row_stride: usize,
+    interlaced_row: &[u8],
+    interlace_info: &InterlaceInfo,
+    bits_per_pixel: u8,
 ) {
-    let bits_pp = bits_pp as usize;
+    let bits_pp = bits_per_pixel as usize;
 
-    let bit_indices = expand_adam7_bits(stride, info, bits_pp);
+    let bit_indices = expand_adam7_bits(img_row_stride, interlace_info, bits_pp);
 
     if bits_pp < 8 {
-        for (pos, px) in bit_indices.zip(subbyte_pixels(scanline, bits_pp)) {
+        for (pos, px) in bit_indices.zip(subbyte_pixels(interlaced_row, bits_pp)) {
             let rem = 8 - pos % 8 - bits_pp;
             img[pos / 8] |= px << rem as u8;
         }
     } else {
         let bytes_pp = bits_pp / 8;
 
-        for (bitpos, px) in bit_indices.zip(scanline.chunks(bytes_pp)) {
+        for (bitpos, px) in bit_indices.zip(interlaced_row.chunks(bytes_pp)) {
             for (offset, val) in px.iter().enumerate() {
                 img[bitpos / 8 + offset] = *val;
             }

src/lib.rs

@@ -71,9 +71,11 @@ mod srgb;
 pub mod text_metadata;
 mod traits;
 
+pub use crate::adam7::expand_pass as expand_interlaced_row;
 pub use crate::common::*;
 pub use crate::decoder::{
-    DecodeOptions, Decoded, Decoder, DecodingError, Limits, OutputInfo, Reader, StreamingDecoder,
+    DecodeOptions, Decoded, Decoder, DecodingError, InterlaceInfo, InterlacedRow, Limits,
+    OutputInfo, Reader, StreamingDecoder,
 };
 pub use crate::encoder::{Encoder, EncodingError, StreamWriter, Writer};
 pub use crate::filter::{AdaptiveFilterType, FilterType};