html-to-markdown 2.24.6 → 2.25.1

data/rust-vendor/png/src/adam7.rs

@@ -2,11 +2,14 @@
 //! [the Adam7 algorithm](https://en.wikipedia.org/wiki/Adam7_algorithm).
 use core::ops::RangeTo;
 
+#[cfg(doc)]
+use crate::decoder::Reader;
+
 /// Describes which stage of
 /// [the Adam7 algorithm](https://en.wikipedia.org/wiki/Adam7_algorithm)
 /// applies to a decoded row.
 ///
-/// See also [Reader.next_interlaced_row](crate::decoder::Reader::next_interlaced_row).
+/// See also [`Reader::next_interlaced_row`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct Adam7Info {
     /// The Adam7 pass number, 1..7.
@@ -41,12 +44,12 @@ impl Adam7Info {
     /// * `width` describes how many pixels are in a full row of the image. The bytes in each
     ///   passline of the Adam7 are calculated from this number.
     ///
-    /// Note that in typical usage, `Adam7Info`s are returned by [Reader.next_interlaced_row]
+    /// Note that in typical usage, `Adam7Info`s are returned by [`Reader::next_interlaced_row`]
     /// and there is no need to create them by calling `Adam7Info::new`.  `Adam7Info::new` is
     /// nevertheless exposed as a public API, because it helps to provide self-contained example
-    /// usage of [expand_interlaced_row](crate::expand_interlaced_row).
+    /// usage of [`expand_interlaced_row`](crate::expand_interlaced_row).
     pub fn new(pass: u8, line: u32, width: u32) -> Self {
-        assert!(1 <= pass && pass <= 7);
+        assert!((1..=7).contains(&pass));
         assert!(width > 0);
 
         let info = PassConstants::PASSES[pass as usize - 1];
@@ -79,7 +82,7 @@ impl Adam7Info {
 }
 
 #[derive(Clone, Copy)]
-struct PassConstants {
+pub(crate) struct PassConstants {
     x_sampling: u8,
     x_offset: u8,
     y_sampling: u8,
@@ -95,13 +98,13 @@ impl PassConstants {
         self.y_sampling - self.y_offset
     }
 
-    fn count_samples(self, width: u32) -> u32 {
+    pub fn count_samples(self, width: u32) -> u32 {
         width
             .saturating_sub(u32::from(self.x_offset))
             .div_ceil(u32::from(self.x_sampling))
     }
 
-    fn count_lines(self, height: u32) -> u32 {
+    pub fn count_lines(self, height: u32) -> u32 {
         height
             .saturating_sub(u32::from(self.y_offset))
             .div_ceil(u32::from(self.y_sampling))
@@ -221,7 +224,9 @@ pub enum Adam7Variant {
     /// are complete. At least the invalid pixels in the buffer should be masked. However, this
     /// performs the least amount of writes and is optimal when you're only reading full frames.
     ///
-    /// This corresponds to [`crate::expand_interlaced_row`].
+    /// This corresponds to [`expand_interlaced_row`].
+    ///
+    /// [`expand_interlaced_row`]: crate::expand_interlaced_row.
     #[default]
     Sparse,
     /// A variant of the Adam7 de-interlace that ensures that all pixels are initialized after each
@@ -229,7 +234,9 @@ pub enum Adam7Variant {
     /// other variant as some pixels are touched repeatedly, but ensures the buffer can be used as
     /// directly as possible for presentation.
     ///
-    /// This corresponds to [`crate::splat_interlaced_row`].
+    /// This corresponds to [`splat_interlaced_row`].
+    ///
+    /// [`splat_interlaced_row`]: crate::splat_interlaced_row
     Splat,
 }
 
@@ -313,7 +320,7 @@ fn expand_adam7_bytes(
 /// stride may be useful if the frame being decoded is a sub-region of `img`.
 ///
 /// `interlaced_row` and `interlace_info` typically come from
-/// [crate::decoder::Reader::next_interlaced_row], but this is not required.  In particular, before
+/// [`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

data/rust-vendor/png/src/common.rs

@@ -53,7 +53,7 @@ impl ColorType {
     pub(crate) fn checked_raw_row_length(self, depth: BitDepth, width: u32) -> Option<usize> {
         // No overflow can occur in 64 bits, we multiply 32-bit with 5 more bits.
         let bits = u64::from(width) * u64::from(self.samples_u8()) * u64::from(depth.into_u8());
-        TryFrom::try_from(1 + (bits + 7) / 8).ok()
+        TryFrom::try_from(1 + bits.div_ceil(8)).ok()
     }
 
     pub(crate) fn raw_row_length_from_width(self, depth: BitDepth, width: u32) -> usize {
@@ -320,7 +320,7 @@ impl AnimationControl {
 /// the appropriate DEFLATE compression mode and PNG filter.
 ///
 /// If you need more control over the encoding parameters,
-/// you can set the [DeflateCompression] and [Filter] manually.
+/// you can set the [`DeflateCompression`] and [`Filter`] manually.
 #[derive(Debug, Clone, Copy)]
 #[non_exhaustive]
 pub enum Compression {
@@ -338,7 +338,7 @@ pub enum Compression {
     /// implementation tuned for PNG](https://crates.io/crates/fdeflate), while still providing
     /// better compression ratio than the fastest modes of other encoders.
     ///
-    /// Like `Compression::Fast` this can currently produce files larger than `NoCompression` in
+    /// Like [`Compression::Fastest`] this can currently produce files larger than `NoCompression` in
     /// streaming mode when given incompressible data. This may change in the future.
     Fast,
     /// Balances encoding speed and compression ratio
@@ -353,11 +353,11 @@ impl Default for Compression {
     }
 }
 
-/// Advanced compression settings with more customization options than [Compression].
+/// Advanced compression settings with more customization options than [`Compression`].
 ///
 /// Note that this setting only affects DEFLATE compression.
 /// Another setting that influences the compression ratio and lets you choose
-/// between encoding speed and compression ratio is the [Filter].
+/// between encoding speed and compression ratio is the [`Filter`].
 ///
 /// ### Stability guarantees
 ///
@@ -375,7 +375,7 @@ pub enum DeflateCompression {
     /// Useful for incompressible images, or when speed is paramount and you don't care about size
     /// at all.
     ///
-    /// This mode also disables filters, forcing [Filter::NoFilter].
+    /// This mode also disables filters, forcing [`Filter::NoFilter`].
     NoCompression,
 
     /// Excellent for creating lightly compressed PNG images very quickly.
@@ -420,12 +420,12 @@ impl DeflateCompression {
 }
 
 /// An unsigned integer scaled version of a floating point value,
-/// equivalent to an integer quotient with fixed denominator (100_000)).
+/// equivalent to an integer quotient with [fixed denominator][ScaledFloat::SCALING]).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ScaledFloat(u32);
 
 impl ScaledFloat {
-    const SCALING: f32 = 100_000.0;
+    pub const SCALING: f32 = 100_000.0;
 
     /// Gets whether the value is within the clamped range of this type.
     pub fn in_range(value: f32) -> bool {

data/rust-vendor/png/src/decoder/mod.rs

@@ -180,8 +180,10 @@ impl<R: BufRead + Seek> Decoder<R> {
 
     /// Read the PNG header and return the information contained within.
     ///
-    /// Most image metadata will not be read until `read_info` is called, so those fields will be
+    /// Most image metadata will not be read until [`read_info`] is called, so those fields will be
     /// None or empty.
+    ///
+    /// [`read_info`]: Self::read_info
     pub fn read_header_info(&mut self) -> Result<&Info<'static>, DecodingError> {
         self.read_decoder.read_header_info()
     }
@@ -227,7 +229,9 @@ impl<R: BufRead + Seek> Decoder<R> {
         reader.remaining_frames = match reader.info().animation_control.as_ref() {
             None => 1, // No `acTL` => only expecting `IDAT` frame.
             Some(animation) => {
-                let mut num_frames = animation.num_frames as usize;
+                // Note: limited to (2^32 - 1) frames by the APNG spec so addition does not
+                // overflow on 32-bit targets nor 64-bit targets.
+                let mut num_frames = animation.num_frames;
                 if reader.info().frame_control.is_none() {
                     // No `fcTL` before `IDAT` => `IDAT` is not part of the animation, but
                     // represents an *extra*, default frame for non-APNG-aware decoders.
@@ -292,7 +296,7 @@ pub struct Reader<R: BufRead + Seek> {
     bpp: BytesPerPixel,
     subframe: SubframeInfo,
     /// How many frames remain to be decoded.  Decremented after each `IDAT` or `fdAT` sequence.
-    remaining_frames: usize,
+    remaining_frames: u32,
     /// Buffer with not-yet-`unfilter`-ed image rows
     unfiltering_buffer: UnfilteringBuffer,
     /// Output transformations
@@ -325,12 +329,15 @@ struct SubframeInfo {
 
 impl<R: BufRead + Seek> Reader<R> {
     /// Advances to the start of the next animation frame and
-    /// returns a reference to the `FrameControl` info that describes it.
+    /// returns a reference to the [`FrameControl`] info that describes it.
     /// Skips and discards the image data of the previous frame if necessary.
     ///
     /// Returns a [`ParameterError`] when there are no more animation frames.
     /// To avoid this the caller can check if [`Info::animation_control`] exists
     /// and consult [`AnimationControl::num_frames`].
+    ///
+    /// [`ParameterError`]: crate::ParameterError
+    /// [`AnimationControl::num_frames`]: crate::AnimationControl::num_frames
     pub fn next_frame_info(&mut self) -> Result<&FrameControl, DecodingError> {
         let remaining_frames = if self.subframe.consumed_and_flushed {
             self.remaining_frames
@@ -363,7 +370,21 @@ impl<R: BufRead + Seek> Reader<R> {
 
         self.subframe = SubframeInfo::new(self.info());
         self.bpp = self.info().bpp_in_prediction();
-        self.unfiltering_buffer.reset_all();
+
+        let frame_bytes = if self.info().interlaced {
+            let mut bytes = 0u64;
+            for pass in crate::adam7::PassConstants::PASSES {
+                bytes += self
+                    .info()
+                    .raw_row_length_from_width(pass.count_samples(self.subframe.width))
+                    as u64
+                    * pass.count_lines(self.subframe.height) as u64;
+            }
+            bytes
+        } else {
+            (self.subframe.rowlen as u64) * self.subframe.height as u64
+        };
+        self.unfiltering_buffer.start_frame(frame_bytes);
 
         // Allocate output buffer.
         let buflen = self.unguarded_output_line_size(self.subframe.width);
@@ -386,7 +407,7 @@ impl<R: BufRead + Seek> Reader<R> {
     ///
     /// The caller must always provide a buffer large enough to hold a complete frame (the APNG
     /// specification restricts subframes to the dimensions given in the image header). The region
-    /// that has been written be checked afterwards by calling `info` after a successful call and
+    /// that has been written be checked afterwards by calling [`Reader::info`] after a successful call and
     /// inspecting the `frame_control` data. This requirement may be lifted in a later version of
     /// `png`.
     ///
@@ -489,9 +510,9 @@ impl<R: BufRead + Seek> Reader<R> {
         Ok(())
     }
 
-    /// Returns the next processed row of the image (discarding `InterlaceInfo`).
+    /// Returns the next processed row of the image (discarding [`InterlaceInfo`]).
     ///
-    /// See also [`Reader.read_row`], which reads into a caller-provided buffer.
+    /// See also [`Reader::read_row`], which reads into a caller-provided buffer.
     pub fn next_row(&mut self) -> Result<Option<Row<'_>>, DecodingError> {
         self.next_interlaced_row()
             .map(|v| v.map(|v| Row { data: v.data }))
@@ -499,7 +520,7 @@ impl<R: BufRead + Seek> Reader<R> {
 
     /// Returns the next processed row of the image.
     ///
-    /// See also [`Reader.read_row`], which reads into a caller-provided buffer.
+    /// See also [`Reader::read_row`], which reads into a caller-provided buffer.
     pub fn next_interlaced_row(&mut self) -> Result<Option<InterlacedRow<'_>>, DecodingError> {
         let mut output_buffer = mem::take(&mut self.scratch_buffer);
         let max_line_size = self
@@ -522,10 +543,10 @@ impl<R: BufRead + Seek> Reader<R> {
     /// Reads the next row of the image into the provided `output_buffer`.
     /// `Ok(None)` will be returned if the current image frame has no more rows.
     ///
-    /// `output_buffer` needs to be long enough to accommodate [`Reader.output_line_size`] for
-    /// [`Info.width`] (initial interlaced rows may need less than that).
+    /// `output_buffer` needs to be long enough to accommodate [`Reader::output_line_size`] for
+    /// [`Info::width`] (initial interlaced rows may need less than that).
     ///
-    /// See also [`Reader.next_row`] and [`Reader.next_interlaced_row`], which read into a
+    /// See also [`Reader::next_row`] and [`Reader::next_interlaced_row`], which read into a
     /// `Reader`-owned buffer.
     pub fn read_row(
         &mut self,
@@ -574,7 +595,6 @@ impl<R: BufRead + Seek> Reader<R> {
         }
 
         self.remaining_frames = 0;
-        self.unfiltering_buffer.reset_all();
         self.decoder.read_until_end_of_input()?;
 
         self.finished = true;
@@ -605,7 +625,7 @@ impl<R: BufRead + Seek> Reader<R> {
     }
 
     /// Returns the color type and the number of bits per sample
-    /// of the data returned by `Reader::next_row` and Reader::frames`.
+    /// of the data returned by [`Reader::next_row`] and [`Reader::next_frame`].
     pub fn output_color_type(&self) -> (ColorType, BitDepth) {
         use crate::common::ColorType::*;
         let t = self.transform;
@@ -679,21 +699,34 @@ impl<R: BufRead + Seek> Reader<R> {
     /// Unfilter the next raw interlaced row into `self.unfiltering_buffer`.
     fn next_raw_interlaced_row(&mut self, rowlen: usize) -> Result<(), DecodingError> {
         // Read image data until we have at least one full row (but possibly more than one).
-        while self.unfiltering_buffer.curr_row_len() < rowlen {
+        while self.unfiltering_buffer.mutable_len_of_curr_row() < rowlen {
             if self.subframe.consumed_and_flushed {
                 return Err(DecodingError::Format(
                     FormatErrorInner::NoMoreImageData.into(),
                 ));
             }
 
-            let mut buffer = self.unfiltering_buffer.as_unfilled_buffer();
-            match self.decoder.decode_image_data(Some(&mut buffer))? {
-                ImageDataCompletionStatus::ExpectingMoreData => (),
-                ImageDataCompletionStatus::Done => self.mark_subframe_as_consumed_and_flushed(),
+            assert!(self.unfiltering_buffer.remaining_bytes() > 0);
+            let completion_status = self
+                .unfiltering_buffer
+                .with_unfilled_buffer(|buffer| self.decoder.decode_image_data(Some(buffer)));
+            match completion_status {
+                Ok(ImageDataCompletionStatus::ExpectingMoreData) => (),
+                Ok(ImageDataCompletionStatus::Done) => self.mark_subframe_as_consumed_and_flushed(),
+                Err(DecodingError::IoError(e))
+                    if e.kind() == std::io::ErrorKind::UnexpectedEof
+                        && self.unfiltering_buffer.readable_len_of_curr_row() >= rowlen =>
+                {
+                    return self
+                        .unfiltering_buffer
+                        .unfilter_curr_row_using_scratch_buffer(rowlen, self.bpp);
+                }
+                Err(other_error) => return Err(other_error),
             }
         }
 
-        self.unfiltering_buffer.unfilter_curr_row(rowlen, self.bpp)
+        self.unfiltering_buffer
+            .unfilter_curr_row_in_place(rowlen, self.bpp)
     }
 }