OpenImageIO/oiio — pull request #265 by lgritz (2012-03-27 08:05:32+00:00)
Title: Review: API changes to ImageInput -- create-with-open and valid_file

In the continuing quest to make create/open more efficient, here are two minor API changes:

1. In almost all uses, an app calls ImageInput::create() to get an II*, then immediately calls in->open() to open the file, which, if you think carefully about the fact that create() does an open to verify that the II is capable of opening the file, means that open() ends up getting called twice. Very wasteful. So the first change is that we change the ImageInput::create() function prototype to include a do_open flag -- if true, it returns the file already opened, not needing a separate call to open(). If false (and this is sometimes useful), it behaves as before, returning an ImageInput* that can be opened, but is not presently. This also simplifies the source of apps just a bit, since the common "create & open" sequence can now be accomplished with just a call to create.

2. To further streamline, we add a new optional method, ImageInput::valid_file(filename), which returns true if the named file appears to be a valid file of that format (in a way that's less expensive than doing a full open and header read -- for example, just checking the first few bytes that contain a "magic number" or whatever). Not all plugins supply this function, and it's not required; the ones that do must return true for supports("valid_file"). I've included implementations for OpenEXR and TIFF that are considerably less expensive than a full header read.

The combination of these should reduce a lot of the overhead for identifying which type of ImageInput is appropriate for a given file and creating it, generally avoiding at least one redundant open and header read for exr and tif files.

Note that this is a break in ABI compatibility. It will not be merged into 1.0, only master, and so will be a 1.1 feature. I believe that it should be source-back-compatible, however.