From e1f429ee0e5cfa9c24968726705b044ee2dd71ad Mon Sep 17 00:00:00 2001 From: "Sergey \"Shnatsel\" Davidoff" Date: Fri, 27 Sep 2024 00:29:54 +0100 Subject: [PATCH 1/2] Improve documentation on filters --- src/encoder.rs | 12 ++++++++---- src/filter.rs | 12 ++++++++---- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/src/encoder.rs b/src/encoder.rs index 27c1432c..73e0f1ea 100644 --- a/src/encoder.rs +++ b/src/encoder.rs @@ -1346,8 +1346,11 @@ impl<'a, W: Write> StreamWriter<'a, W> { /// Set the used filter type for the next frame. /// /// The default filter is [`FilterType::Sub`] which provides a basic prediction algorithm for - /// sample values based on the previous. For a potentially better compression ratio, at the - /// cost of more complex processing, try out [`FilterType::Paeth`]. + /// sample values based on the previous. + /// + /// For optimal compression ratio you should enable adaptive filtering + /// instead of setting a single filter for the entire image, see + /// [set_adaptive_filter](Self::set_adaptive_filter). pub fn set_filter(&mut self, filter: FilterType) { self.filter = filter; } @@ -1356,8 +1359,9 @@ impl<'a, W: Write> StreamWriter<'a, W> { /// /// Adaptive filtering attempts to select the best filter for each line /// based on heuristics which minimize the file size for compression rather - /// than use a single filter for the entire image. The default method is - /// [`AdaptiveFilterType::NonAdaptive`]. + /// than use a single filter for the entire image. + /// + /// The default method is [`AdaptiveFilterType::NonAdaptive`]. pub fn set_adaptive_filter(&mut self, adaptive_filter: AdaptiveFilterType) { self.adaptive_filter = adaptive_filter; } diff --git a/src/filter.rs b/src/filter.rs index 0edd4e93..d808bf23 100644 --- a/src/filter.rs +++ b/src/filter.rs @@ -267,6 +267,8 @@ mod simd { /// Compression in general benefits from repetitive data. The filter is a content-aware method of /// compressing the range of occurring byte values to help the compression algorithm. Note that /// this does not operate on pixels but on raw bytes of a scanline. +/// +/// Details on how each filter works can be found in the [PNG Book](http://www.libpng.org/pub/png/book/chapter09.html). #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[repr(u8)] pub enum FilterType { @@ -297,12 +299,14 @@ impl FilterType { } } -/// The filtering method for preprocessing scanline data before compression. +/// Adaptive filtering tries every possible filter for each row and keeps the best one. +/// This improves compression ratio, but makes encoding slower. /// -/// Adaptive filtering performs additional computation in an attempt to maximize -/// the compression of the data. [`NonAdaptive`] filtering is the default. +/// It is recommended to use `Adaptive` whenever you care about compression ratio. +/// Filtering is quite cheap compared to other parts of encoding, but can contribute +/// to the compression ratio significantly. /// -/// [`NonAdaptive`]: AdaptiveFilterType::NonAdaptive +/// `NonAdaptive` filtering is the default. #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[repr(u8)] pub enum AdaptiveFilterType { From a64485af0aaeffad2af378e8c061d0aa09af8c73 Mon Sep 17 00:00:00 2001 From: "Sergey \"Shnatsel\" Davidoff" Date: Fri, 27 Sep 2024 11:26:25 +0100 Subject: [PATCH 2/2] Update src/filter.rs Co-authored-by: Jonathan Behrens --- src/filter.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/filter.rs b/src/filter.rs index d808bf23..9290a040 100644 --- a/src/filter.rs +++ b/src/filter.rs @@ -299,8 +299,8 @@ impl FilterType { } } -/// Adaptive filtering tries every possible filter for each row and keeps the best one. -/// This improves compression ratio, but makes encoding slower. +/// Adaptive filtering tries every possible filter for each row and uses a heuristic to select the best one. +/// This improves compression ratio, but makes encoding slightly slower. /// /// It is recommended to use `Adaptive` whenever you care about compression ratio. /// Filtering is quite cheap compared to other parts of encoding, but can contribute