Soften deprecation of Decoder::read_image

Author: 197g

src/decoder/mod.rs

@@ -1396,7 +1396,13 @@ impl<R: Read + Seek> Decoder<R> {
     ///
     /// When the image is stored as a planar configuration, this method will currently only read
     /// the first sample's plane. This will be fixed in a future major version of `tiff`.
-    #[deprecated = "Use `DecodingResult::resize_to` and `read_image_bytes` instead. This old method will keep its bugged planar behavior until it is removed."]
+    ///
+    /// # Intent to deprecate
+    ///
+    /// Use `DecodingResult::resize_to` and `read_image_bytes` instead where possible, preserving
+    /// the buffer across multiple calls. This old method will likely keep its bugged planar
+    /// behavior until it is fully replaced, to ensure that existing code will not run into
+    /// unexpectedly large allocations that will error on limits instead.
     pub fn read_image(&mut self) -> TiffResult<DecodingResult> {
         let readout = self.image().readout_for_image()?;
 

src/encoder/writer.rs

@@ -221,6 +221,8 @@ fn encoder_on_short_writes() {
     };
 
     let imgdata = vec![42u8; 100 * 100];
+    let mut data = crate::decoder::DecodingResult::U8(vec![]);
+
     for comp in [
         super::Compression::Uncompressed,
         super::Compression::Packbits,
@@ -240,7 +242,7 @@ fn encoder_on_short_writes() {
 
         write.inner.set_position(0);
         let mut tiff_reader = crate::decoder::Decoder::new(&mut write.inner).unwrap();
-        let mut data = tiff_reader.read_image().unwrap();
+        let _layout = tiff_reader.read_image_to_buffer(&mut data).unwrap();
 
         assert!(
             matches!(&data, crate::decoder::DecodingResult::U8(v) if *v == imgdata),

tests/encode_images.rs

@@ -81,7 +81,10 @@ fn encode_decode() {
             decoder.get_tag(Tag::Artist).unwrap(),
             ifd::Value::Ascii("Image-tiff".into())
         );
-        if let DecodingResult::U8(img_res) = decoder.read_image().unwrap() {
+
+        let mut buffer = tiff::decoder::DecodingResult::U8(vec![]);
+        let _layout = decoder.read_image_to_buffer(&mut buffer).unwrap();
+        if let tiff::decoder::DecodingResult::U8(img_res) = buffer {
             assert_eq!(image_data, img_res);
         } else {
             panic!("Wrong data type");
@@ -161,7 +164,9 @@ fn encode_decode_big() {
             decoder.get_tag(Tag::Artist).unwrap(),
             ifd::Value::Ascii("Image-tiff".into())
         );
-        if let DecodingResult::U8(img_res) = decoder.read_image().unwrap() {
+        let mut buffer = tiff::decoder::DecodingResult::U8(vec![]);
+        let _layout = decoder.read_image_to_buffer(&mut buffer).unwrap();
+        if let DecodingResult::U8(img_res) = buffer {
             assert_eq!(image_data, img_res);
         } else {
             panic!("Wrong data type");
@@ -245,7 +250,10 @@ macro_rules! test_roundtrip {
             let mut decoder = Decoder::new(img_file).expect("Cannot create decoder");
             assert_eq!(decoder.colortype().unwrap(), expected_type);
 
-            let image_data = match decoder.read_image().unwrap() {
+            let mut buffer = tiff::decoder::DecodingResult::U8(vec![]);
+            decoder.read_image_to_buffer(&mut buffer).unwrap();
+
+            let image_data = match buffer {
                 DecodingResult::$buffer(res) => res,
                 _ => panic!("Wrong data type"),
             };
@@ -259,9 +267,11 @@ macro_rules! test_roundtrip {
             }
             file.seek(SeekFrom::Start(0)).unwrap();
             {
+                let mut buffer = tiff::decoder::DecodingResult::U8(vec![]);
                 let mut decoder = Decoder::new(&mut file).unwrap();
-                if let DecodingResult::$buffer(img_res) = decoder.read_image().unwrap() {
-                    assert_eq!(image_data, img_res);
+                decoder.read_image_to_buffer(&mut buffer).unwrap();
+                if let DecodingResult::$buffer(img_res) = buffer {
+                    assert_eq!(*image_data, img_res);
                 } else {
                     panic!("Wrong data type");
                 }