api: deprecation cleanup in imageio.h (#4312)

Track down and fix many places internal to OIIO where we were still
using deprecated API calls.

Add deprecation warnings to some things that have been nominally
deprecated, but weren't already tagged as such.

Guard deprecated things behind OIIO_DISABLE_DEPRECATED so that
downstream projects can hide them to help them find and change any use
of the deprecated calls, and behind !defined(OIIO_INTERNAL) so they are
hidden from the rest of the internals of our code base.

Make some of the deprecated things inline, so that their final removal
later doesn't constitute a link ABI compatibility change. (We do absorb
an ABI compatibility boundary with this PR, so I've bumped the version
number appropriately.) Move all the OIIO-namespace level deprecated
items to the end of imageio.h so they're as out of the way as possible.

A lot of the things that are still present here, just guarded by the
deprecation warnings, will be removed entirely before the final OIIO 3.0
release.

Please note some particular things in imageio that have been deprecated
for a while and that we expect to disappear entirely by 3.0:

* The old style `ImageInput::read_*` functions that don't take explicit
subimage and miplevel paramters, because they aren't thread-safe due to
their implied statefulness. You are expected to use the ones that take
those parameters and are stateless.

* The variety of seek_subimage that takes an `ImageSpec&` to fill in.

* Some obsolete varieties of ImageInput and ImageOutput create() static
methods.

* The `destroy` methods that are no longer needed (plain old `delete` is
fine).

* The various error-setting functions that use the old printf-like
formatting conventions. Use `errorfmt()` and friends that use the
std::format conventions.

Signed-off-by: Larry Gritz <[email protected]>

src/iconvert/iconvert.cpp

@@ -375,8 +375,7 @@ convert_file(const std::string& in_filename, const std::string& out_filename)
 
     bool ok                      = true;
     bool mip_to_subimage_warning = false;
-    for (int subimage = 0; ok && in->seek_subimage(subimage, 0, inspec);
-         ++subimage) {
+    for (int subimage = 0; ok && in->seek_subimage(subimage, 0); ++subimage) {
         if (subimage > 0 && !out->supports("multiimage")) {
             print(stderr,
                   "iconvert WARNING: {} does not support multiple subimages.\n"
@@ -388,6 +387,7 @@ convert_file(const std::string& in_filename, const std::string& out_filename)
         int miplevel = 0;
         do {
             // Copy the spec, with possible change in format
+            inspec            = in->spec(subimage, miplevel);
             ImageSpec outspec = inspec;
             bool nocopy = adjust_spec(in.get(), out.get(), inspec, outspec);
             if (miplevel > 0) {
@@ -473,7 +473,7 @@ convert_file(const std::string& in_filename, const std::string& out_filename)
             }
 
             ++miplevel;
-        } while (ok && in->seek_subimage(subimage, miplevel, inspec));
+        } while (ok && in->seek_subimage(subimage, miplevel));
     }
 
     out->close();

src/igrep/igrep.cpp

@@ -62,7 +62,6 @@ grep_file(const std::string& filename, std::regex& re,
             std::cerr << geterror() << "\n";
         return false;
     }
-    ImageSpec spec = in->spec();
 
     if (file_match) {
         bool match = false;
@@ -83,6 +82,7 @@ grep_file(const std::string& filename, std::regex& re,
     do {
         if (!all_subimages && subimage > 0)
             break;
+        ImageSpec spec = in->spec(subimage);
         for (auto&& p : spec.extra_attribs) {
             TypeDesc t = p.type();
             if (t.elementtype() == TypeDesc::STRING) {
@@ -108,7 +108,7 @@ grep_file(const std::string& filename, std::regex& re,
                 }
             }
         }
-    } while (in->seek_subimage(++subimage, 0, spec));
+    } while (in->seek_subimage(++subimage, 0));
 
     if (invert_match) {
         found = !found;

src/iinfo/iinfo.cpp

@@ -243,8 +243,9 @@ static void
 print_info_subimage(int current_subimage, int max_subimages, ImageSpec& spec,
                     ImageInput* input, const std::string& filename)
 {
-    if (!input->seek_subimage(current_subimage, 0, spec))
+    if (!input->seek_subimage(current_subimage, 0))
         return;
+    spec = input->spec(current_subimage);
 
     if (!metamatch.empty()
         && !std::regex_search(
@@ -274,9 +275,9 @@ print_info_subimage(int current_subimage, int max_subimages, ImageSpec& spec,
         print("\n");
     }
     // Count MIP levels
-    ImageSpec mipspec;
-    while (input->seek_subimage(current_subimage, nmip, mipspec)) {
+    while (input->seek_subimage(current_subimage, nmip)) {
         if (printres) {
+            ImageSpec mipspec = input->spec_dimensions(current_subimage, nmip);
             if (nmip == 1)
                 print("    MIP-map levels: {}x{}", spec.width, spec.height);
             print(" {}x{}", mipspec.width, mipspec.height);
@@ -291,8 +292,7 @@ print_info_subimage(int current_subimage, int max_subimages, ImageSpec& spec,
         if (filenameprefix)
             print("{} : ", filename);
         // Before sha-1, be sure to point back to the highest-res MIP level
-        ImageSpec tmpspec;
-        input->seek_subimage(current_subimage, 0, tmpspec);
+        input->seek_subimage(current_subimage, 0);
         print_sha1(input, current_subimage, 0);
     }
 
@@ -302,8 +302,7 @@ print_info_subimage(int current_subimage, int max_subimages, ImageSpec& spec,
     if (compute_stats
         && (metamatch.empty() || std::regex_search("stats", field_re))) {
         for (int m = 0; m < nmip; ++m) {
-            ImageSpec mipspec;
-            input->seek_subimage(current_subimage, m, mipspec);
+            ImageSpec mipspec = input->spec_dimensions(current_subimage, m);
             if (filenameprefix)
                 print("{} : ", filename);
             if (nmip > 1 && (subimages || m == 0)) {
@@ -314,7 +313,7 @@ print_info_subimage(int current_subimage, int max_subimages, ImageSpec& spec,
         }
     }
 
-    if (!input->seek_subimage(current_subimage, 0, spec))
+    if (!input->seek_subimage(current_subimage, 0))
         return;
 }
 
@@ -334,23 +333,24 @@ print_info(const std::string& filename, size_t namefieldlength,
     std::vector<int> num_of_miplevels;
     {
         int nmip = 1;
-        while (input->seek_subimage(input->current_subimage(), nmip, spec)) {
+        while (input->seek_subimage(input->current_subimage(), nmip)) {
             ++nmip;
             any_mipmapping = true;
         }
         num_of_miplevels.push_back(nmip);
     }
-    while (input->seek_subimage(num_of_subimages, 0, spec)) {
+    while (input->seek_subimage(num_of_subimages, 0)) {
         // maybe we should do this more gently?
         ++num_of_subimages;
         int nmip = 1;
-        while (input->seek_subimage(input->current_subimage(), nmip, spec)) {
+        while (input->seek_subimage(input->current_subimage(), nmip)) {
             ++nmip;
             any_mipmapping = true;
         }
         num_of_miplevels.push_back(nmip);
     }
-    input->seek_subimage(0, 0, spec);  // re-seek to the first
+    // input->seek_subimage(0, 0);  // re-seek to the first
+    spec = input->spec(0, 0);
 
     if (metamatch.empty()
         || std::regex_search("resolution, width, height, depth, channels",
@@ -388,7 +388,7 @@ print_info(const std::string& filename, size_t namefieldlength,
         // info about num of subimages and their resolutions
         print("    {} subimages: ", num_of_subimages);
         for (int i = 0; i < num_of_subimages; ++i) {
-            input->seek_subimage(i, 0, spec);
+            spec     = input->spec(i, 0);
             int bits = spec.get_int_attribute("oiio:BitsPerSample",
                                               spec.format.size() * 8);
             if (i)