Document Decoder::open behavior

Make Compression enum non-exhaustive

benches/encode.rs

@@ -4,7 +4,7 @@ extern crate tiff;
 use criterion::{black_box, Criterion, Throughput};
 use std::io::Cursor;
 use tiff::encoder::colortype::RGB32Float;
-use tiff::encoder::{Compression, DeflateLevel, Predictor, TiffEncoder};
+use tiff::encoder::{Compression, Predictor, TiffEncoder};
 
 const WIDTH: u32 = 500;
 const HEIGHT: u32 = 500;
@@ -14,7 +14,7 @@ fn encode_image_f32_float_predictor_deflate(data: &[f32]) {
     TiffEncoder::new(&mut buf)
         .unwrap()
         .with_predictor(Predictor::FloatingPoint)
-        .with_compression(Compression::Deflate(DeflateLevel::Fast))
+        .with_compression(Compression::Deflate(1))
         .write_image::<RGB32Float>(WIDTH, HEIGHT, black_box(data))
         .unwrap();
 }

src/decoder/mod.rs

@@ -857,11 +857,64 @@ impl TiffHeader {
 }
 
 impl<R: Read + Seek> Decoder<R> {
+    /// Parse the image header from the underlying file and create a decoder positioned before its
+    /// first directory.
+    ///
+    /// This method opens the file in a state _before_ the first (image) directory. You need to
+    /// call one of [`Self::next_image`], [`Self::next_directory`] or [`Self::seek_to_directory`]
+    /// to choose a directory before interacting with the tag methods.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tiff::decoder::{Decoder, DecodingResult};
+    ///
+    /// let buffered_file = /* */
+    /// # std::io::Cursor::new(include_bytes!(concat!(
+    /// #   env!("CARGO_MANIFEST_DIR"), "/tests/images/tiled-gray-i1.tif"
+    /// # )));
+    ///
+    /// let mut decoder =  Decoder::open(buffered_file)?;
+    /// let mut img_buffer = DecodingResult::U8(vec![]);
+    ///
+    /// while decoder.more_images() {
+    ///     decoder.next_image()?;
+    ///     decoder.read_image_to_buffer(&mut img_buffer)?;
+    /// }
+    ///
+    /// # Ok::<_, tiff::TiffError>(())
+    /// ```
+    ///
+    /// # Relations
+    ///
+    /// The [`TiffHeader`] type allows opening a file with a custom offset.
+    pub fn open(mut r: R) -> TiffResult<Decoder<R>> {
+        let header = TiffHeader::parse(&mut r)?;
+        Ok(header.open(r))
+    }
+
     /// Create a decoder and attempt to parse the first image directory.
     ///
     /// To open a file without parsing any directory yet (for instance to retain a [`Decoder`] on
-    /// errors in the directory), use [`TiffHeader::parse`] and [`TiffHeader::open`] instead..
+    /// errors in the directory), use [`TiffHeader::parse`] and [`TiffHeader::open`] instead.
-    #[deprecated = "Prefer `Decoder::open`. These methods will become aliases in a future major release."]
+    ///
+    /// This method is equivalent to [`Decoder::open`] except it provides no decoder when the first
+    /// IFD errors due to not being an image or an IO problem. It can be replaced precisely with
+    /// this sequence:
+    ///
+    /// ```no_run
+    /// # use tiff::decoder::Decoder;
+    /// # let r = std::io::BufReader::new(std::io::empty());
+    /// let decoder = {
+    ///     let mut tmp = Decoder::open(r)?;
+    ///     tmp.next_image()?;
+    ///     tmp
+    /// };
+    ///
+    /// # Ok::<_, tiff::TiffError>(())
+    /// ```
+    ///
+    #[deprecated = "Prefer `Decoder::open` followed by an explicit `next_image` call. These methods will become aliases in a future major release."]
     pub fn new(mut r: R) -> TiffResult<Decoder<R>> {
         let header = TiffHeader::parse(&mut r)?;
         let mut decoder = header.open(r);
@@ -869,15 +922,6 @@ impl<R: Read + Seek> Decoder<R> {
         Ok(decoder)
     }
 
-    /// Parse the image header from the underlying file and create a decoder positioned before its
-    /// first directory.
-    ///
-    /// The [`TiffHeader`] type allows opening a file with a custom.
-    pub fn open(mut r: R) -> TiffResult<Decoder<R>> {
-        let header = TiffHeader::parse(&mut r)?;
-        Ok(header.open(r))
-    }
-
     /// Configure allocation limits for all subsequent operations.
     ///
     /// Limits apply to allocated return values such as from [`Decoder::read_image`] and

src/encoder/compression/deflate.rs

@@ -7,24 +7,27 @@ pub struct Deflate {
     level: FlateCompression,
 }
 
-/// The level of compression used by the Deflate algorithm.
-/// It allows trading compression ratio for compression speed.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
-#[non_exhaustive]
-#[derive(Default)]
-pub enum DeflateLevel {
-    /// The fastest possible compression mode.
-    Fast = 1,
-    /// The conserative choice between speed and ratio.
-    #[default]
-    Balanced = 6,
-    /// The best compression available with Deflate.
-    Best = 9,
-}
-
 impl Deflate {
     /// Create a new deflate compressor with a specific level of compression.
-    pub fn with_level(level: DeflateLevel) -> Self {
+    ///
+    /// The valid levels are 1 through 9 inclusive. The default level is 6.
+    ///
+    /// - `1` stands for light but fast compression
+    /// - `6` is the recommended balanced default
+    /// - `9` is maximum compression ratio at the cost of slow encoding
+    pub fn with_level(level: u8) -> Self {
+        Self {
+            level: FlateCompression::new(level as u32),
+        }
+    }
+
+    /// Create a new deflate compressor with an exact level of compression.
+    ///
+    /// `0` stands for uncompressed
+    /// `1` stands for light but fast compression
+    /// `6` is the recommended balanced default
+    /// `9` is maximum compression ratio at the cost of slow encoding
+    pub fn exact_level(level: u8) -> Self {
         Self {
             level: FlateCompression::new(level as u32),
         }
@@ -33,7 +36,7 @@ impl Deflate {
 
 impl Default for Deflate {
     fn default() -> Self {
-        Self::with_level(DeflateLevel::default())
+        Self::with_level(6)
     }
 }
 

src/encoder/compression/mod.rs

@@ -9,7 +9,7 @@ mod packbits;
 mod uncompressed;
 
 #[cfg(feature = "deflate")]
-pub use self::deflate::{Deflate, DeflateLevel};
+pub use self::deflate::Deflate;
 
 #[cfg(feature = "lzw")]
 pub use self::lzw::Lzw;

src/encoder/mod.rs

@@ -38,9 +38,8 @@ use self::writer::*;
 /// [Predictor::Horizontal] is for integer sample types.
 /// [Predictor::FloatingPoint] is for floating-point sample types (f32, f64).
 pub type Predictor = crate::tags::Predictor;
-#[cfg(feature = "deflate")]
-pub type DeflateLevel = compression::DeflateLevel;
 
+#[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Default)]
 pub enum Compression {
     #[default]
@@ -48,7 +47,7 @@ pub enum Compression {
     #[cfg(feature = "lzw")]
     Lzw,
     #[cfg(feature = "deflate")]
-    Deflate(DeflateLevel),
+    Deflate(u8),
     Packbits,
 }
 

tests/encode_images_with_compression.rs

@@ -5,7 +5,6 @@ use tiff::{
     decoder::{Decoder, DecodingResult},
     encoder::{
         colortype::{self, ColorType},
-        compression::*,
         Compression, TiffEncoder, TiffValue,
     },
 };
@@ -148,9 +147,9 @@ fn encode_decode_with_lzw() {
 #[test]
 #[cfg(feature = "deflate")]
 fn encode_decode_with_deflate() {
-    encode_decode_with_compression(Compression::Deflate(DeflateLevel::Fast));
+    encode_decode_with_compression(Compression::Deflate(1));
-    encode_decode_with_compression(Compression::Deflate(DeflateLevel::Balanced));
+    encode_decode_with_compression(Compression::Deflate(6));
-    encode_decode_with_compression(Compression::Deflate(DeflateLevel::Best));
+    encode_decode_with_compression(Compression::Deflate(9));
 }
 
 #[test]