@lgritz
Latest commit 271f911 Feb 4, 2023 History
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 parameter 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 attribute "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 transform 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 entries, 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.
21 contributors

Users who have contributed to this file

@lgritz @fpsunflower @c42f @rmv @cmstein @johnhaddon @danwexler @ThiagoIze @mfvescovi @v4hn @maxliani @leamsi