Add color management to texture lookups

This isn't 100% final -- I'm sure there are some corner cases I
missed, maybe things that will eventually need some performance work,
but enough works and passes tests that I'm confident in the API and so
I want to get this merged and we can iterate on internals later.

The use case is as follows: User or shader knows that a particular
texture is in something other than the default working color space,
this is not necessarily apparent from the file itself and so cannot be
fully automatic, but it is presumed that it can be communicated in the
texture call. We aim to be efficient, fully converting each tile upon
input. Note that we are sweeping under the rug the fact that a
non-default color space lookup is not mathematically correct with
respect to the MIP-map downsizing math if that was not considered at
texture creation time. But by converting texels as they are read,
rather than the shader itself trying to do a color transformation on
the final texture result, at least we are doing the right math for the
filtering within and among MIP levels.

The new interface consists of communicating the presumed working color
space, finding the colortransform ID of a given from/to (with the "to"
defaulting to the working space, if not specified), and then on each
texture call, supplying that colortransform ID as one of the settings
in TextureOpt (or TextureOptBatch).

The outline of changes are as follows:

* BREAKING CHANGE: TextureOpt and TextureOptBatch now contain an
  additional int `colortransformid`. The default, 0, is the old (and,
  frankly, preferred) behavior. Nonzero values indicate that we want
  the texels to go through a color transformation as the tiles are
  read into the cache.

* BREAKING CHANGE: New public methods have been added to TextureSystem
  `get_colortransform_id(fromspace, tospace)` that return a transform
  ID given the from and to color spaces (ustring or ustringhash). This
  is the value that goes in the TextureOpt to request a color
  transformation on the pixels as they are read.

* BREAKING CHANGE: IC::get_image_handle / TS::get_texture_handle now
  take an additional optinal paramter that is a TextureOpt*. This is
  currently unused, but is reserved for possible future use and/or for
  alternate TextureSystem implementations that choose a different
  implementation strategy wherein an entirely different TextureHandle
  may correspond to each color transformation. That's not how I've
  done it here, but it's a valid approach (and maybe one we'll switch
  to in the future). We presume that it's ill-defined to ask for a
  handle with one explicit color transformation, then use that handle
  with a TextureOpt that implies a different color
  transformation. Using those consistently ensure that either TS
  strategy will work equally well.

* New TextureSystem attributes "colorspace" gives the working color
  space name (defaulting to "scene_linear"), and "colorconfig" can
  optionally point to a color config file (though this is not yet
  functional -- it just uses the default color config).

* Internally, the tile cache hash has been adjusted so that the same
  tile in the disk file will appear as a separate tile in the cache
  for each color space pair that is applied to it. Thus, there is no
  conflict if some different texture calls ask for different color
  space interpretations of the same texture file. (That said, it's not
  recommended to be throwing color spaces around willy nilly -- it
  still takes multiple cache entrie, plus extra color conversion math
  as the tiles are read in.)

* A new preprocessor symbol OIIO_TEXTURESYSTEM_SUPPORTS_COLORSPACE in
  texture.h allows client software can easily tell if this is a
  version new enough to support color management and has the additional
  fields in the texture option structures.

Because there are breaking changes here to ABI, this is destined only
for master (future 2.5) and will not be backported to OIIO 2.4.

Author: lgritz

CMakeLists.txt

@@ -4,7 +4,7 @@
 
 cmake_minimum_required (VERSION 3.12)
 
-set (OpenImageIO_VERSION "2.5.0.2")
+set (OpenImageIO_VERSION "2.5.1.0")
 set (OpenImageIO_VERSION_OVERRIDE "" CACHE STRING
      "Version override (use with caution)!")
 mark_as_advanced (OpenImageIO_VERSION_OVERRIDE)

src/cmake/testing.cmake

@@ -186,6 +186,7 @@ macro (oiio_add_all_tests)
                     texture-stats
                     texture-threadtimes
                     texture-env
+                    texture-colorspace
                    )
     oiio_add_tests (${all_texture_tests})
     # Duplicate texture tests with batch mode

src/include/OpenImageIO/imagecache.h

@@ -28,6 +28,9 @@
 
 OIIO_NAMESPACE_BEGIN
 
+// Forward declaration
+class TextureOpt;
+
 namespace pvt {
 // Forward declaration
 class ImageCacheImpl;
@@ -216,6 +219,11 @@ class OIIO_API ImageCache {
     ///           enabled, this reduces the number of file opens, at the
     ///           expense of not being able to open files if their format do
     ///           not actually match their filename extension). Default: 0
+    /// - `string colorspace` :
+    ///           The working colorspace of the texture system. Default: none.
+    /// - `string colorconfig` :
+    ///           Name of the OCIO config to use. Default: "" (meaning to use
+    ///           the default color config).
     ///
     /// - `string options`
     ///           This catch-all is simply a comma-separated list of
@@ -467,6 +475,25 @@ class OIIO_API ImageCache {
     /// internals.
     typedef pvt::ImageCacheFile ImageHandle;
 
+#if OIIO_VERSION_GREATER_EQUAL(2, 5, 1)
+    /// Retrieve an opaque handle for fast texture lookups.  The filename is
+    /// presumed to be UTF-8 encoded. The `options`, if not null, may be used
+    /// to create a separate handle for certain texture option choices
+    /// (currently: the colorspace). The opaque pointer `thread_info` is
+    /// thread-specific information returned by `get_perthread_info()`. Return
+    /// nullptr if something has gone horribly wrong.
+    virtual ImageHandle* get_image_handle(ustring filename,
+                                      Perthread* thread_info = nullptr,
+                                      const TextureOpt* options = nullptr) = 0;
+
+    /// Get an ImageHandle using a UTF-16 encoded wstring filename.
+    ImageHandle* get_image_handle(const std::wstring& filename,
+                                  Perthread* thread_info = nullptr,
+                                  const TextureOpt* options = nullptr) {
+        return get_image_handle(ustring(Strutil::utf16_to_utf8(filename)),
+                                thread_info, options);
+    }
+#else
     /// Retrieve an opaque handle for fast image lookups. The filename is
     /// presumed to be UTF-8 encoded. The opaque `pointer thread_info` is
     /// thread-specific information returned by `get_perthread_info()`.
@@ -480,6 +507,7 @@ class OIIO_API ImageCache {
         return get_image_handle (ustring(Strutil::utf16_to_utf8(filename)),
                                  thread_info);
     }
+#endif
 
     /// Return true if the image handle (previously returned by
     /// `get_image_handle()`) is a valid image that can be subsequently read.

src/include/OpenImageIO/texture.h

@@ -20,6 +20,7 @@
 // Define symbols that let client applications determine if newly added
 // features are supported.
 #define OIIO_TEXTURESYSTEM_SUPPORTS_CLOSE 1
+#define OIIO_TEXTURESYSTEM_SUPPORTS_COLORSPACE 1
 
 // Is the getattributetype() method present? (Added in 2.5)
 #define OIIO_TEXTURESYSTEM_SUPPORTS_GETATTRIBUTETYPE 1
@@ -232,6 +233,7 @@ class OIIO_API TextureOpt {
         fill(0.0f), missingcolor(nullptr),
         time(0.0f), rnd(-1.0f), samples(1),
         rwrap(WrapDefault), rblur(0.0f), rwidth(1.0f),
+        colortransformid(0),
         envlayout(0)
     { }
 
@@ -264,6 +266,8 @@ class OIIO_API TextureOpt {
     float rblur;   ///< Blur amount in the r direction
     float rwidth;  ///< Multiplier for derivatives in r direction
 
+    int colortransformid;       ///< Color space id of the texture
+
     /// Utility: Return the Wrap enum corresponding to a wrap name:
     /// "default", "black", "clamp", "periodic", "mirror".
     static Wrap decode_wrapmode(const char* name)
@@ -313,9 +317,7 @@ class OIIO_API TextureOptBatch {
     alignas(Tex::BatchAlign) float twidth[Tex::BatchWidth];
     alignas(Tex::BatchAlign) float rwidth[Tex::BatchWidth];
     // Note: rblur,rwidth only used for volumetric lookups
-#if OIIO_VERSION_GREATER_EQUAL(2,4,0)
     alignas(Tex::BatchAlign) float rnd[Tex::BatchWidth];
-#endif
 
     // Options that must be the same for all points we're texturing at once
     int firstchannel = 0;                 ///< First channel of the lookup
@@ -330,6 +332,7 @@ class OIIO_API TextureOptBatch {
     int conservative_filter = 1;          ///< True: over-blur rather than alias
     float fill = 0.0f;                    ///< Fill value for missing channels
     const float *missingcolor = nullptr;  ///< Color for missing texture
+    int colortransformid = 0;             ///< Color space id of the texture
 
 private:
     // Options set INTERNALLY by libtexture after the options are passed
@@ -551,6 +554,10 @@ class OIIO_API TextureSystem {
     /// - `int max_errors_per_file` :
     ///             Limits how many errors to issue for each file. (default:
     ///             100)
+    /// - `string colorspace` :
+    ///             The working colorspace of the texture system.
+    /// - `string colorconfig` :
+    ///             Name of the OCIO config to use (default: "").
     ///
     /// Texture-specific settings:
     /// - `matrix44 worldtocommon` / `matrix44 commontoworld` :
@@ -788,16 +795,20 @@ class OIIO_API TextureSystem {
     class TextureHandle;
 
     /// Retrieve an opaque handle for fast texture lookups.  The filename is
-    /// presumed to be UTF-8 encoded. The opaque pointer `thread_info` is
-    /// thread-specific information returned by `get_perthread_info()`.
-    /// Return nullptr if something has gone horribly wrong.
-    virtual TextureHandle* get_texture_handle (ustring filename,
-                                            Perthread *thread_info=nullptr) = 0;
+    /// presumed to be UTF-8 encoded. The `options`, if not null, may be used
+    /// to create a separate handle for certain texture option choices
+    /// (currently: the colorspace). The opaque pointer `thread_info` is
+    /// thread-specific information returned by `get_perthread_info()`. Return
+    /// nullptr if something has gone horribly wrong.
+    virtual TextureHandle* get_texture_handle(ustring filename,
+                                      Perthread* thread_info = nullptr,
+                                      const TextureOpt* options = nullptr) = 0;
     /// Get a TextureHandle using a UTF-16 encoded wstring filename.
-    TextureHandle* get_texture_handle (const std::wstring& filename,
-                                       Perthread *thread_info=nullptr) {
-        return get_texture_handle (ustring(Strutil::utf16_to_utf8(filename)),
-                                   thread_info);
+    TextureHandle* get_texture_handle(const std::wstring& filename,
+                                      Perthread* thread_info = nullptr,
+                                      const TextureOpt* options = nullptr) {
+        return get_texture_handle(ustring(Strutil::utf16_to_utf8(filename)),
+                                  thread_info, options);
     }
 
     /// Return true if the texture handle (previously returned by
@@ -810,6 +821,14 @@ class OIIO_API TextureSystem {
     /// This method was added in OpenImageIO 2.3.
     virtual ustring filename_from_handle(TextureHandle* handle) = 0;
 
+    /// Retrieve an id for a color transformation by name. This ID can be used
+    /// as the value for TextureOpt::colortransformid. The returned value will
+    /// be -1 if either color space is unknown, and 0 for a null
+    /// transformation.
+    virtual int get_colortransform_id(ustring fromspace,
+                                      ustring tospace) const = 0;
+    virtual int get_colortransform_id(ustringhash fromspace,
+                                      ustringhash tospace) const = 0;
     /// @}
 
     /// @{

src/libtexture/imagecache.cpp

@@ -11,10 +11,13 @@
 #include <vector>
 
 #include <OpenImageIO/Imath.h>
+
+#include <OpenImageIO/color.h>
 #include <OpenImageIO/dassert.h>
 #include <OpenImageIO/filesystem.h>
 #include <OpenImageIO/fmath.h>
 #include <OpenImageIO/imagebuf.h>
+#include <OpenImageIO/imagebufalgo.h>
 #include <OpenImageIO/imagecache.h>
 #include <OpenImageIO/imageio.h>
 #include <OpenImageIO/optparser.h>
@@ -791,36 +794,41 @@ ImageCacheFile::init_from_spec()
 
 
 bool
-ImageCacheFile::read_tile(ImageCachePerThreadInfo* thread_info, int subimage,
-                          int miplevel, int x, int y, int z, int chbegin,
-                          int chend, TypeDesc format, void* data)
+ImageCacheFile::read_tile(ImageCachePerThreadInfo* thread_info,
+                          const TileID& id, void* data)
 {
-    OIIO_DASSERT(chend > chbegin);
+    OIIO_DASSERT(id.chend() > id.chbegin());
 
     // Mark if we ever use a mip level that's not the first
+    int miplevel = id.miplevel();
     if (miplevel > 0)
         m_mipused = true;
-
     // count how many times this mipmap level was read
     m_mipreadcount[miplevel]++;
 
+    int subimage = id.subimage();
     SubimageInfo& subinfo(subimageinfo(subimage));
 
     // Special case for un-MIP-mapped
     if (subinfo.unmipped && miplevel != 0)
-        return read_unmipped(thread_info, subimage, miplevel, x, y, z, chbegin,
-                             chend, format, data);
+        return read_unmipped(thread_info, id, data);
 
     std::shared_ptr<ImageInput> inp = open(thread_info);
     if (!inp)
         return false;
 
     // Special case for untiled images -- need to do tile emulation
     if (subinfo.untiled)
-        return read_untiled(thread_info, inp.get(), subimage, miplevel, x, y, z,
-                            chbegin, chend, format, data);
+        return read_untiled(thread_info, inp.get(), id, data);
 
     // Ordinary tiled
+    int x           = id.x();
+    int y           = id.y();
+    int z           = id.z();
+    int chbegin     = id.chbegin();
+    int chend       = id.chend();
+    TypeDesc format = id.file().datatype(subimage);
+
     bool ok = true;
     const ImageSpec& spec(this->spec(subimage, miplevel));
     for (int tries = 0; tries <= imagecache().failure_retries(); ++tries) {
@@ -852,6 +860,19 @@ ImageCacheFile::read_tile(ImageCachePerThreadInfo* thread_info, int subimage,
         thread_info->m_stats.bytes_read += b;
         m_bytesread += b;
         ++m_tilesread;
+        if (id.colortransformid() > 0) {
+            // print("CONVERT id {} {},{} to cs {}\n", filename(), id.x(), id.y(),
+            //       id.colortransformid());
+            ImageBuf wrapper(ImageSpec(spec.tile_width, spec.tile_height,
+                                       spec.nchannels, format),
+                             data);
+            ImageBufAlgo::colorconvert(
+                wrapper, wrapper,
+                ColorConfig::default_colorconfig().getColorSpaceNameByIndex(
+                    (id.colortransformid() >> 16) - 1),
+                m_imagecache.colorspace(), true, string_view(), string_view(),
+                nullptr, ROI(), 1);
+        }
     }
     return ok;
 }
@@ -860,9 +881,7 @@ ImageCacheFile::read_tile(ImageCachePerThreadInfo* thread_info, int subimage,
 
 bool
 ImageCacheFile::read_unmipped(ImageCachePerThreadInfo* thread_info,
-                              int subimage, int miplevel, int x, int y, int z,
-                              int chbegin, int chend, TypeDesc format,
-                              void* data)
+                              const TileID& id, void* data)
 {
     // We need a tile from an unmipmapped file, and it doesn't really
     // exist.  So generate it out of thin air by interpolating pixels
@@ -875,6 +894,15 @@ ImageCacheFile::read_unmipped(ImageCachePerThreadInfo* thread_info,
     // N.B. No need to lock the mutex, since this is only called
     // from read_tile, which already holds the lock.
 
+    int subimage = id.subimage();
+    int miplevel = id.miplevel();
+    int x        = id.x();
+    int y        = id.y();
+    // int z        = id.z();
+    int chbegin     = id.chbegin();
+    int chend       = id.chend();
+    TypeDesc format = id.file().datatype(id.subimage());
+
     // Figure out the size and strides for a single tile, make an ImageBuf
     // to hold it temporarily.
     const ImageSpec& spec(this->spec(subimage, miplevel));
@@ -888,7 +916,7 @@ ImageCacheFile::read_unmipped(ImageCachePerThreadInfo* thread_info,
     // Figure out the range of texels we need for this tile
     x -= spec.x;
     y -= spec.y;
-    z -= spec.z;
+    // z -= spec.z;
     int x0 = x - (x % spec.tile_width);
     int x1 = std::min(x0 + spec.tile_width - 1, spec.full_width - 1);
     int y0 = y - (y % spec.tile_height);
@@ -956,10 +984,18 @@ ImageCacheFile::read_unmipped(ImageCachePerThreadInfo* thread_info,
 // of reading a "tile" from a file that's scanline-oriented.
 bool
 ImageCacheFile::read_untiled(ImageCachePerThreadInfo* thread_info,
-                             ImageInput* inp, int subimage, int miplevel, int x,
-                             int y, int z, int chbegin, int chend,
-                             TypeDesc format, void* data)
-{
+                             ImageInput* inp, const TileID& id, void* data)
+{
+    int subimage         = id.subimage();
+    int miplevel         = id.miplevel();
+    int x                = id.x();
+    int y                = id.y();
+    int z                = id.z();
+    int chbegin          = id.chbegin();
+    int chend            = id.chend();
+    TypeDesc format      = id.file().datatype(id.subimage());
+    int colortransformid = id.colortransformid();
+
     // Strides for a single tile
     const ImageSpec& spec(this->spec(subimage, miplevel));
     int tw = spec.tile_width;
@@ -1021,7 +1057,7 @@ ImageCacheFile::read_untiled(ImageCachePerThreadInfo* thread_info,
                 // tile-row, so let's put it in the cache anyway so
                 // it'll be there when asked for.
                 TileID id(*this, subimage, miplevel, i + spec.x, y0, z, chbegin,
-                          chend);
+                          chend, colortransformid);
                 if (!imagecache().tile_in_cache(id, thread_info)) {
                     ImageCacheTileRef tile;
                     tile = new ImageCacheTile(id, &buf[i * pixelsize], format,
@@ -1520,10 +1556,7 @@ ImageCacheTile::read(ImageCachePerThreadInfo* thread_info)
     // Clear the end pad values so there aren't NaNs sucked up by simd loads
     memset(m_pixels.get() + size - OIIO_SIMD_MAX_SIZE_BYTES, 0,
            OIIO_SIMD_MAX_SIZE_BYTES);
-    m_valid = file.read_tile(thread_info, m_id.subimage(), m_id.miplevel(),
-                             m_id.x(), m_id.y(), m_id.z(), m_id.chbegin(),
-                             m_id.chend(), file.datatype(m_id.subimage()),
-                             &m_pixels[0]);
+    m_valid = file.read_tile(thread_info, m_id, &m_pixels[0]);
     file.imagecache().incr_mem(size);
     if (m_valid) {
         ImageCacheFile::LevelInfo& lev(
@@ -1636,6 +1669,7 @@ ImageCacheImpl::init()
     m_failure_retries      = 0;
     m_latlong_y_up_default = true;
     m_Mw2c.makeIdentity();
+    m_colorspace              = ustring("scene_linear");
     m_mem_used                = 0;
     m_statslevel              = 0;
     m_max_errors_per_file     = 100;
@@ -2196,8 +2230,23 @@ ImageCacheImpl::attribute(string_view name, TypeDesc type, const void* val)
             do_invalidate          = true;
         }
     } else if (name == "substitute_image" && type == TypeDesc::STRING) {
-        m_substitute_image = ustring(*(const char**)val);
-        do_invalidate      = true;
+        ustring uval(*(const char**)val);
+        if (uval != m_substitute_image) {
+            m_substitute_image = uval;
+            do_invalidate      = true;
+        }
+    } else if (name == "colorconfig" && type == TypeDesc::STRING) {
+        ustring uval(*(const char**)val);
+        if (uval != m_colorconfigname) {
+            m_colorconfigname = uval;
+            do_invalidate     = true;
+        }
+    } else if (name == "colorspace" && type == TypeDesc::STRING) {
+        ustring uval(*(const char**)val);
+        if (uval != m_colorspace) {
+            m_colorspace  = uval;
+            do_invalidate = true;
+        }
     } else if (name == "max_mip_res" && type == TypeInt) {
         m_max_mip_res = *(const int*)val;
         do_invalidate = true;
@@ -2339,6 +2388,14 @@ ImageCacheImpl::getattribute(string_view name, TypeDesc type, void* val) const
         *(const char**)val = m_substitute_image.c_str();
         return true;
     }
+    if (name == "colorconfig" && type == TypeDesc::STRING) {
+        *(const char**)val = m_colorconfigname.c_str();
+        return true;
+    }
+    if (name == "colorspace" && type == TypeDesc::STRING) {
+        *(const char**)val = m_colorspace.c_str();
+        return true;
+    }
     if (name == "all_filenames" && type.basetype == TypeDesc::STRING
         && type.is_sized_array()) {
         ustring* names = (ustring*)val;