OpenImageIO/oiio — pull request #683 by lgritz (2013-10-03 05:19:05+00:00)
Title: Fix ImageBuf spec vs nativespec confusion over the data format.

Recall: ImageBuf.spec() is supposed to describe the data in the buffer (or held by the ImageCache, if it's a cache-backed IB), whereas ImageBuf.nativespec() is supposed to describe the data in the file itself.

It turns out this was subtly broken all along -- in cases where you called init_spec(), spec().format held the data type of the file after that call, but after a full call to read(), it would be changed to reflect the data type of the buffer.

This did not match the documentation or intended design of spec vs nativespec, but we never noticed, and in fact there were places in the code that (unknowingly) took advantage of this chain of events.

When, earlier this week, I committed changes that remove the need to ever call init_spec() and read(), instead doing these actions automatically and lazily when other API calls first need the data in question, a bunch of icky bugs popped up, revealing this confusion.

This patch mostly fixes the situation. It is VERY important for apps to keep straight whether it's spec() [the buffer] or nativespec() [the file] that they want to be calling for any particular purpose.

There is still one way things can be confusing: If you create the IB, then reference spec() -- which will reflect how it will look in the ImageCache, then force a call to read() to force a fully local read rather than use the cache... at that point, spec().format will change to reflect the buffer that you read. I don't see how to avoid that, unless we switch to a model where the IB constructor fully specifies at that time whether the IC will be used or whether the file will be fully read locally. I'll mull that over for possible later revision.