From 2d901796025929c2e4f82dce696aa2ab53616032 Mon Sep 17 00:00:00 2001
From: "A. Molzer" <5550310+197g@users.noreply.github.com>
Date: Mon, 29 Dec 2025 19:49:09 +0100
Subject: [PATCH] Soften deprecation of `Decoder::read_image`

---
 src/decoder/mod.rs     |  8 +++++++-
 src/encoder/writer.rs  |  4 +++-
 tests/encode_images.rs | 20 +++++++++++++++-----
 3 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/decoder/mod.rs b/src/decoder/mod.rs
index ef47425..cc31572 100644
--- a/src/decoder/mod.rs
+++ b/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()?;
 
diff --git a/src/encoder/writer.rs b/src/encoder/writer.rs
index bd9c603..6b7eb16 100644
--- a/src/encoder/writer.rs
+++ b/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),
diff --git a/tests/encode_images.rs b/tests/encode_images.rs
index b16e87d..df0dac9 100644
--- a/tests/encode_images.rs
+++ b/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");
                 }