Merge pull request #506 from Shnatsel/improve-filter-documentation

Improve documentation on filters

Author: Shnatsel

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;
     }

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 uses a heuristic to select the best one.
+/// This improves compression ratio, but makes encoding slightly 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 {