rpdfium_codec/

scanline.rs

// Derived from PDFium's scanline decoder concepts
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! Scanline-based image decoding — yields one row of pixels at a time.
//!
//! The [`ScanlineDecoder`] trait provides a row-by-row interface for
//! decompressing image data, useful for large images where loading the
//! entire bitmap into memory at once is undesirable.
//!
//! The trait mirrors PDFium's `ScanlineDecoder` base class, including
//! `GetWidth()`, `GetHeight()`, `CountComps()`, and `GetBPC()` accessors
//! so that any code holding only a `&dyn ScanlineDecoder` can query the
//! full image geometry without consulting the PDF stream dictionary.

use crate::error::DecodeError;

/// Compute the byte stride (bytes per scanline row).
///
/// Matches PDFium's pitch formula: `(width * comps * bpc + 7) / 8`.
fn compute_row_stride(width: u32, comps: u8, bpc: u8) -> usize {
    (width as usize * comps as usize * bpc as usize).div_ceil(8)
}

/// A scanline-based image decoder that yields one row of pixels at a time.
///
/// After construction, call [`decode_scanline`](ScanlineDecoder::decode_scanline)
/// repeatedly to get each row. Returns `Ok(None)` after the last row.
/// Call [`reset`](ScanlineDecoder::reset) to restart from the first row.
///
/// Mirrors PDFium's `ScanlineDecoder` base class interface, including the
/// image-geometry accessors `GetWidth()`, `GetHeight()`, `CountComps()`,
/// and `GetBPC()`.
pub trait ScanlineDecoder {
    /// Image width in pixels. Mirrors PDFium's `GetWidth()`.
    fn width(&self) -> u32;

    /// Image height in pixels. Mirrors PDFium's `GetHeight()`.
    fn height(&self) -> u32;

    /// Number of color components per pixel (e.g. 1 for gray, 3 for RGB, 4
    /// for CMYK). Mirrors PDFium's `CountComps()`.
    fn count_comps(&self) -> u8;

    /// Bits per color component (e.g. 1, 8, 16). Mirrors PDFium's `GetBPC()`.
    fn bpc(&self) -> u8;

    /// Number of bytes per row: `(width * count_comps * bpc + 7) / 8`.
    fn row_stride(&self) -> usize;

    /// Decode and return the next scanline.
    ///
    /// Returns `Ok(Some(data))` for each row, `Ok(None)` when all rows are
    /// done.
    fn decode_scanline(&mut self) -> Result<Option<&[u8]>, DecodeError>;

    /// Reset the decoder to the first scanline.
    fn reset(&mut self) -> Result<(), DecodeError>;

    /// Current line index (0-based), or `None` if no lines have been read yet.
    fn current_line(&self) -> Option<usize>;
}

/// Random-access scanline decoder wrapper.
///
/// Wraps any [`ScanlineDecoder`] and adds `get_scanline(line)` support with
/// caching and rewind logic. Ported from upstream PDFium's
/// `ScanlineDecoder::GetScanline(int line)`.
pub struct RandomAccessDecoder<D: ScanlineDecoder> {
    inner: D,
    next_line: i32,
    last_scanline: Vec<u8>,
}

impl<D: ScanlineDecoder> RandomAccessDecoder<D> {
    /// Wrap a scanline decoder with random access capability.
    pub fn new(inner: D) -> Self {
        Self {
            inner,
            next_line: -1,
            last_scanline: Vec::new(),
        }
    }

    /// Get a specific scanline by line index (0-based).
    ///
    /// If the requested line is the one just decoded, returns a cached copy.
    /// If the requested line is before the current position, rewinds and
    /// re-reads sequentially. Matches upstream PDFium's caching pattern.
    pub fn get_scanline(&mut self, line: usize) -> Result<Option<&[u8]>, DecodeError> {
        let line_i32 = line as i32;

        // Quick return if we just decoded this line
        if self.next_line == line_i32 + 1 && !self.last_scanline.is_empty() {
            return Ok(Some(&self.last_scanline));
        }

        // Need to rewind if we're past the target or haven't started
        if self.next_line < 0 || self.next_line > line_i32 {
            self.inner.reset()?;
            self.next_line = 0;
        }

        // Skip forward to target line
        while self.next_line < line_i32 {
            if self.inner.decode_scanline()?.is_none() {
                return Ok(None);
            }
            self.next_line += 1;
        }

        // Fetch the target line
        match self.inner.decode_scanline()? {
            Some(data) => {
                self.last_scanline.clear();
                self.last_scanline.extend_from_slice(data);
                self.next_line += 1;
                Ok(Some(&self.last_scanline))
            }
            None => Ok(None),
        }
    }

    /// Get a reference to the underlying decoder.
    pub fn inner(&self) -> &D {
        &self.inner
    }

    /// Image width in pixels.
    pub fn width(&self) -> u32 {
        self.inner.width()
    }

    /// Image height in pixels.
    pub fn height(&self) -> u32 {
        self.inner.height()
    }

    /// Number of color components per pixel.
    pub fn count_comps(&self) -> u8 {
        self.inner.count_comps()
    }

    /// Bits per color component.
    pub fn bpc(&self) -> u8 {
        self.inner.bpc()
    }

    /// Number of bytes per row.
    pub fn row_stride(&self) -> usize {
        self.inner.row_stride()
    }
}

/// Scanline decoder for FlateDecode (zlib/deflate) data.
///
/// Decompresses the full data internally on construction, then yields
/// `row_stride` bytes per [`decode_scanline`](ScanlineDecoder::decode_scanline) call.
pub struct FlateScanlineDecoder {
    data: Vec<u8>,
    width: u32,
    height: u32,
    comps: u8,
    bpc: u8,
    row_stride: usize,
    offset: usize,
}

impl FlateScanlineDecoder {
    /// Create a new scanline decoder from compressed Flate data.
    ///
    /// The row stride is computed automatically as
    /// `(width * comps * bpc + 7) / 8`, matching PDFium's pitch formula.
    pub fn new(
        compressed: &[u8],
        width: u32,
        height: u32,
        comps: u8,
        bpc: u8,
    ) -> Result<Self, DecodeError> {
        let data = crate::flate::decode(compressed, None, None, None, None)?;
        let row_stride = compute_row_stride(width, comps, bpc);
        Ok(Self {
            data,
            width,
            height,
            comps,
            bpc,
            row_stride,
            offset: 0,
        })
    }

    /// Create from already-decompressed pixel data.
    pub fn from_decoded(data: Vec<u8>, width: u32, height: u32, comps: u8, bpc: u8) -> Self {
        let row_stride = compute_row_stride(width, comps, bpc);
        Self {
            data,
            width,
            height,
            comps,
            bpc,
            row_stride,
            offset: 0,
        }
    }
}

impl ScanlineDecoder for FlateScanlineDecoder {
    fn width(&self) -> u32 {
        self.width
    }

    fn height(&self) -> u32 {
        self.height
    }

    fn count_comps(&self) -> u8 {
        self.comps
    }

    fn bpc(&self) -> u8 {
        self.bpc
    }

    fn row_stride(&self) -> usize {
        self.row_stride
    }

    fn decode_scanline(&mut self) -> Result<Option<&[u8]>, DecodeError> {
        if self.row_stride == 0 || self.offset >= self.data.len() {
            return Ok(None);
        }
        let end = (self.offset + self.row_stride).min(self.data.len());
        let row = &self.data[self.offset..end];
        self.offset = end;
        Ok(Some(row))
    }

    fn reset(&mut self) -> Result<(), DecodeError> {
        self.offset = 0;
        Ok(())
    }

    fn current_line(&self) -> Option<usize> {
        if self.row_stride == 0 || self.offset == 0 {
            None
        } else {
            Some(self.offset / self.row_stride - 1)
        }
    }
}

/// Scanline decoder for DCTDecode (JPEG) data.
///
/// Decodes the full JPEG internally on construction, then yields
/// one scanline at a time based on the decoded pixel stride.
pub struct DctScanlineDecoder {
    data: Vec<u8>,
    width: u32,
    height: u32,
    comps: u8,
    bpc: u8,
    row_stride: usize,
    offset: usize,
}

impl DctScanlineDecoder {
    /// Create a new scanline decoder from JPEG-compressed data.
    ///
    /// The row stride is computed automatically as
    /// `(width * comps * bpc + 7) / 8`, matching PDFium's pitch formula.
    pub fn new(
        jpeg_data: &[u8],
        width: u32,
        height: u32,
        comps: u8,
        bpc: u8,
    ) -> Result<Self, DecodeError> {
        let data = crate::jpeg::decode(jpeg_data)?;
        let row_stride = compute_row_stride(width, comps, bpc);
        Ok(Self {
            data,
            width,
            height,
            comps,
            bpc,
            row_stride,
            offset: 0,
        })
    }

    /// Create from already-decoded pixel data.
    pub fn from_decoded(data: Vec<u8>, width: u32, height: u32, comps: u8, bpc: u8) -> Self {
        let row_stride = compute_row_stride(width, comps, bpc);
        Self {
            data,
            width,
            height,
            comps,
            bpc,
            row_stride,
            offset: 0,
        }
    }
}

impl ScanlineDecoder for DctScanlineDecoder {
    fn width(&self) -> u32 {
        self.width
    }

    fn height(&self) -> u32 {
        self.height
    }

    fn count_comps(&self) -> u8 {
        self.comps
    }

    fn bpc(&self) -> u8 {
        self.bpc
    }

    fn row_stride(&self) -> usize {
        self.row_stride
    }

    fn decode_scanline(&mut self) -> Result<Option<&[u8]>, DecodeError> {
        if self.row_stride == 0 || self.offset >= self.data.len() {
            return Ok(None);
        }
        let end = (self.offset + self.row_stride).min(self.data.len());
        let row = &self.data[self.offset..end];
        self.offset = end;
        Ok(Some(row))
    }

    fn reset(&mut self) -> Result<(), DecodeError> {
        self.offset = 0;
        Ok(())
    }

    fn current_line(&self) -> Option<usize> {
        if self.row_stride == 0 || self.offset == 0 {
            None
        } else {
            Some(self.offset / self.row_stride - 1)
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use flate2::Compression;
    use flate2::write::ZlibEncoder;
    use std::io::Write;

    fn zlib_compress(data: &[u8]) -> Vec<u8> {
        let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default());
        encoder.write_all(data).unwrap();
        encoder.finish().unwrap()
    }

    #[test]
    fn flate_scanline_basic() {
        // 3 rows × 4 bytes (width=4, comps=1, bpc=8)
        let raw = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
        let compressed = zlib_compress(&raw);
        let mut decoder = FlateScanlineDecoder::new(&compressed, 4, 3, 1, 8).unwrap();

        assert_eq!(decoder.row_stride(), 4);
        assert_eq!(decoder.width(), 4);
        assert_eq!(decoder.height(), 3);
        assert_eq!(decoder.count_comps(), 1);
        assert_eq!(decoder.bpc(), 8);

        let row1 = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(row1, &[1, 2, 3, 4]);

        let row2 = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(row2, &[5, 6, 7, 8]);

        let row3 = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(row3, &[9, 10, 11, 12]);

        // No more rows
        assert!(decoder.decode_scanline().unwrap().is_none());
    }

    #[test]
    fn flate_scanline_count() {
        // 10 rows × 10 bytes (width=10, comps=1, bpc=8)
        let raw = vec![0u8; 100];
        let compressed = zlib_compress(&raw);
        let mut decoder = FlateScanlineDecoder::new(&compressed, 10, 10, 1, 8).unwrap();

        let mut count = 0;
        while decoder.decode_scanline().unwrap().is_some() {
            count += 1;
        }
        assert_eq!(count, 10);
    }

    #[test]
    fn flate_scanline_matches_batch() {
        // 12 rows × 10 bytes (width=10, comps=1, bpc=8)
        let raw: Vec<u8> = (0..120).map(|i| (i % 256) as u8).collect();
        let compressed = zlib_compress(&raw);
        let mut decoder = FlateScanlineDecoder::new(&compressed, 10, 12, 1, 8).unwrap();

        let mut collected = Vec::new();
        while let Some(row) = decoder.decode_scanline().unwrap() {
            collected.extend_from_slice(row);
        }
        assert_eq!(collected, raw);
    }

    #[test]
    fn flate_scanline_none_after_last() {
        // 1 row × 4 bytes (width=4, comps=1, bpc=8)
        let raw = vec![1u8; 4];
        let compressed = zlib_compress(&raw);
        let mut decoder = FlateScanlineDecoder::new(&compressed, 4, 1, 1, 8).unwrap();

        assert!(decoder.decode_scanline().unwrap().is_some());
        assert!(decoder.decode_scanline().unwrap().is_none());
        assert!(decoder.decode_scanline().unwrap().is_none());
    }

    #[test]
    fn flate_scanline_reset() {
        // 2 rows × 4 bytes (width=4, comps=1, bpc=8)
        let raw = vec![1, 2, 3, 4, 5, 6, 7, 8];
        let compressed = zlib_compress(&raw);
        let mut decoder = FlateScanlineDecoder::new(&compressed, 4, 2, 1, 8).unwrap();

        let row1 = decoder.decode_scanline().unwrap().unwrap().to_vec();
        decoder.decode_scanline().unwrap(); // consume row2
        assert!(decoder.decode_scanline().unwrap().is_none());

        decoder.reset().unwrap();
        let row1_again = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(row1, row1_again);
    }

    #[test]
    fn flate_scanline_row_stride_calc() {
        // 640×480 RGB image: row_stride = (640 * 3 * 8 + 7) / 8 = 1920
        let raw = vec![0u8; 1920 * 2];
        let compressed = zlib_compress(&raw);
        let decoder = FlateScanlineDecoder::new(&compressed, 640, 2, 3, 8).unwrap();
        assert_eq!(decoder.row_stride(), 1920);
        assert_eq!(decoder.width(), 640);
        assert_eq!(decoder.count_comps(), 3);
    }

    #[test]
    fn flate_scanline_zero_stride() {
        // width=0 produces row_stride=0; decode_scanline must return None immediately
        let decoder = FlateScanlineDecoder::from_decoded(vec![1, 2, 3], 0, 1, 1, 8);
        let mut decoder: Box<dyn ScanlineDecoder> = Box::new(decoder);
        assert!(decoder.decode_scanline().unwrap().is_none());
    }

    #[test]
    fn dct_scanline_from_decoded() {
        // 2 rows × 3 bytes (width=1, comps=3, bpc=8)
        let raw = vec![10, 20, 30, 40, 50, 60];
        let mut decoder = DctScanlineDecoder::from_decoded(raw.clone(), 1, 2, 3, 8);

        assert_eq!(decoder.width(), 1);
        assert_eq!(decoder.height(), 2);
        assert_eq!(decoder.count_comps(), 3);
        assert_eq!(decoder.bpc(), 8);
        assert_eq!(decoder.row_stride(), 3);

        let row1 = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(row1, &[10, 20, 30]);

        let row2 = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(row2, &[40, 50, 60]);

        assert!(decoder.decode_scanline().unwrap().is_none());
    }

    #[test]
    fn dct_scanline_reset() {
        // 2 rows × 3 bytes (width=1, comps=3, bpc=8)
        let raw = vec![1, 2, 3, 4, 5, 6];
        let mut decoder = DctScanlineDecoder::from_decoded(raw, 1, 2, 3, 8);

        decoder.decode_scanline().unwrap();
        decoder.decode_scanline().unwrap();
        assert!(decoder.decode_scanline().unwrap().is_none());

        decoder.reset().unwrap();
        let first = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(first, &[1, 2, 3]);
    }

    #[test]
    fn scanline_decoder_trait_object_safety() {
        fn assert_obj_safe(_: &dyn ScanlineDecoder) {}
        // width=2, height=1, comps=1, bpc=8 → row_stride=2
        let decoder = FlateScanlineDecoder::from_decoded(vec![0; 4], 2, 1, 1, 8);
        assert_obj_safe(&decoder);
    }

    #[test]
    fn partial_last_row() {
        // Data that doesn't fill the last row completely.
        // width=3, height=2, comps=1, bpc=8 → row_stride=3, total expected=6 but data=5
        let raw = vec![1, 2, 3, 4, 5];
        let mut decoder = FlateScanlineDecoder::from_decoded(raw, 3, 2, 1, 8);

        let row1 = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(row1, &[1, 2, 3]);

        let row2 = decoder.decode_scanline().unwrap().unwrap();
        assert_eq!(row2, &[4, 5]); // partial last row

        assert!(decoder.decode_scanline().unwrap().is_none());
    }

    #[test]
    fn metadata_getters_flate() {
        // Verify that width/height/count_comps/bpc survive a round-trip
        let raw = vec![0u8; 8 * 6 * 2]; // 8px wide, 6 rows, 16bpc grayscale
        let compressed = zlib_compress(&raw);
        // row_stride = (8 * 1 * 16 + 7) / 8 = 16
        let decoder = FlateScanlineDecoder::new(&compressed, 8, 6, 1, 16).unwrap();
        assert_eq!(decoder.width(), 8);
        assert_eq!(decoder.height(), 6);
        assert_eq!(decoder.count_comps(), 1);
        assert_eq!(decoder.bpc(), 16);
        assert_eq!(decoder.row_stride(), 16);
    }

    #[test]
    fn metadata_getters_dct() {
        // Verify that metadata is stored correctly in DctScanlineDecoder
        let data = vec![0u8; 10 * 4]; // 10px wide, 4 rows, 1 comp, 8bpc
        let decoder = DctScanlineDecoder::from_decoded(data, 10, 4, 1, 8);
        assert_eq!(decoder.width(), 10);
        assert_eq!(decoder.height(), 4);
        assert_eq!(decoder.count_comps(), 1);
        assert_eq!(decoder.bpc(), 8);
        assert_eq!(decoder.row_stride(), 10);
    }

    #[test]
    fn compute_row_stride_1bpc() {
        // 1bpc packed: 8 pixels → 1 byte, 9 pixels → 2 bytes
        let d8 = FlateScanlineDecoder::from_decoded(vec![0; 1], 8, 1, 1, 1);
        assert_eq!(d8.row_stride(), 1);
        let d9 = FlateScanlineDecoder::from_decoded(vec![0; 2], 9, 1, 1, 1);
        assert_eq!(d9.row_stride(), 2);
    }

    #[test]
    fn compute_row_stride_16bpc() {
        // 16bpc RGB: 4 pixels → 4 * 3 * 2 = 24 bytes
        let decoder = FlateScanlineDecoder::from_decoded(vec![0; 24], 4, 1, 3, 16);
        assert_eq!(decoder.row_stride(), 24);
    }

    // -----------------------------------------------------------------------
    // RandomAccessDecoder tests
    // -----------------------------------------------------------------------

    #[test]
    fn random_access_sequential() {
        // 3 rows × 4 bytes (width=4, comps=1, bpc=8)
        let raw = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
        let decoder = FlateScanlineDecoder::from_decoded(raw, 4, 3, 1, 8);
        let mut ra = RandomAccessDecoder::new(decoder);

        let row0 = ra.get_scanline(0).unwrap().unwrap().to_vec();
        assert_eq!(row0, &[1, 2, 3, 4]);

        let row1 = ra.get_scanline(1).unwrap().unwrap().to_vec();
        assert_eq!(row1, &[5, 6, 7, 8]);

        let row2 = ra.get_scanline(2).unwrap().unwrap().to_vec();
        assert_eq!(row2, &[9, 10, 11, 12]);
    }

    #[test]
    fn random_access_cached() {
        // 2 rows × 3 bytes (width=1, comps=3, bpc=8)
        let raw = vec![10, 20, 30, 40, 50, 60];
        let decoder = FlateScanlineDecoder::from_decoded(raw, 1, 2, 3, 8);
        let mut ra = RandomAccessDecoder::new(decoder);

        let row0 = ra.get_scanline(0).unwrap().unwrap().to_vec();
        assert_eq!(row0, &[10, 20, 30]);

        // Read same line again — should return cached copy
        let row0_again = ra.get_scanline(0).unwrap().unwrap().to_vec();
        assert_eq!(row0_again, &[10, 20, 30]);
    }

    #[test]
    fn random_access_rewind() {
        // 3 rows × 3 bytes (width=3, comps=1, bpc=8)
        let raw = vec![1, 2, 3, 4, 5, 6, 7, 8, 9];
        let decoder = FlateScanlineDecoder::from_decoded(raw, 3, 3, 1, 8);
        let mut ra = RandomAccessDecoder::new(decoder);

        // Read line 2 (skip 0, 1)
        let row2 = ra.get_scanline(2).unwrap().unwrap().to_vec();
        assert_eq!(row2, &[7, 8, 9]);

        // Read line 0 — requires rewind
        let row0 = ra.get_scanline(0).unwrap().unwrap().to_vec();
        assert_eq!(row0, &[1, 2, 3]);

        let row1 = ra.get_scanline(1).unwrap().unwrap().to_vec();
        assert_eq!(row1, &[4, 5, 6]);
    }

    #[test]
    fn random_access_skip_forward() {
        // 4 rows × 10 bytes (width=10, comps=1, bpc=8)
        let raw: Vec<u8> = (0..40).collect();
        let decoder = FlateScanlineDecoder::from_decoded(raw, 10, 4, 1, 8);
        let mut ra = RandomAccessDecoder::new(decoder);

        // Jump to line 3 directly
        let row3 = ra.get_scanline(3).unwrap().unwrap().to_vec();
        assert_eq!(row3, &[30, 31, 32, 33, 34, 35, 36, 37, 38, 39]);
    }

    #[test]
    fn random_access_out_of_bounds() {
        // 1 row × 3 bytes (width=3, comps=1, bpc=8)
        let raw = vec![1, 2, 3];
        let decoder = FlateScanlineDecoder::from_decoded(raw, 3, 1, 1, 8);
        let mut ra = RandomAccessDecoder::new(decoder);

        // Only 1 row exists; line 1 should return None
        let result = ra.get_scanline(1).unwrap();
        assert!(result.is_none());
    }

    #[test]
    fn random_access_inner_ref() {
        // 1 row × 2 bytes (width=2, comps=1, bpc=8)
        let raw = vec![1, 2, 3, 4];
        let decoder = FlateScanlineDecoder::from_decoded(raw, 2, 1, 1, 8);
        let ra = RandomAccessDecoder::new(decoder);
        assert_eq!(ra.inner().row_stride(), 2);
        assert_eq!(ra.row_stride(), 2);
        assert_eq!(ra.width(), 2);
        assert_eq!(ra.height(), 1);
        assert_eq!(ra.count_comps(), 1);
        assert_eq!(ra.bpc(), 8);
    }

    #[test]
    fn current_line_before_read() {
        // width=2, height=2, comps=1, bpc=8 → row_stride=2
        let decoder = FlateScanlineDecoder::from_decoded(vec![1, 2, 3, 4], 2, 2, 1, 8);
        assert_eq!(decoder.current_line(), None);
    }

    #[test]
    fn current_line_after_read() {
        let mut decoder = FlateScanlineDecoder::from_decoded(vec![1, 2, 3, 4], 2, 2, 1, 8);
        decoder.decode_scanline().unwrap();
        assert_eq!(decoder.current_line(), Some(0));
        decoder.decode_scanline().unwrap();
        assert_eq!(decoder.current_line(), Some(1));
    }

    #[test]
    fn current_line_after_reset() {
        let mut decoder = FlateScanlineDecoder::from_decoded(vec![1, 2, 3, 4], 2, 2, 1, 8);
        decoder.decode_scanline().unwrap();
        decoder.reset().unwrap();
        assert_eq!(decoder.current_line(), None);
    }
}