|
HDK
|
#include <imageio.h>
Public Types | |
| using | unique_ptr = std::unique_ptr< ImageInput > |
| unique_ptr to an ImageInput More... | |
| typedef std::recursive_mutex | mutex |
| typedef std::lock_guard< mutex > | lock_guard |
| typedef ImageInput *(* | Creator )() |
| Call signature of a function that creates and returns an ImageInput*. More... | |
Public Member Functions | |
| ImageInput () | |
| virtual | ~ImageInput () |
| virtual const char * | format_name (void) const =0 |
| virtual int | supports (string_view feature) const |
| virtual bool | valid_file (const std::string &filename) const |
| virtual bool | open (const std::string &name, ImageSpec &newspec)=0 |
| virtual bool | open (const std::string &name, ImageSpec &newspec, const ImageSpec &) |
| virtual const ImageSpec & | spec (void) const |
| virtual ImageSpec | spec (int subimage, int miplevel=0) |
| virtual ImageSpec | spec_dimensions (int subimage, int miplevel=0) |
| virtual bool | close ()=0 |
| virtual int | current_subimage (void) const |
| virtual int | current_miplevel (void) const |
| virtual bool | seek_subimage (int subimage, int miplevel) |
| bool | seek_subimage (int subimage, int miplevel, ImageSpec &newspec) |
| bool | seek_subimage (int subimage, ImageSpec &newspec) |
| virtual bool | read_scanline (int y, int z, TypeDesc format, void *data, stride_t xstride=AutoStride) |
| bool | read_scanline (int y, int z, float *data) |
| Simple read_scanline reads to contiguous float pixels. More... | |
| virtual bool | read_scanlines (int subimage, int miplevel, int ybegin, int yend, int z, int chbegin, int chend, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride) |
| bool | read_scanlines (int ybegin, int yend, int z, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride) |
| bool | read_scanlines (int ybegin, int yend, int z, int chbegin, int chend, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride) |
| virtual bool | read_tile (int x, int y, int z, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride) |
| bool | read_tile (int x, int y, int z, float *data) |
| Simple read_tile reads to contiguous float pixels. More... | |
| virtual bool | read_tiles (int subimage, int miplevel, int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride) |
| bool | read_tiles (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride) |
| bool | read_tiles (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride) |
| virtual bool | read_image (TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride, ProgressCallback progress_callback=NULL, void *progress_callback_data=NULL) |
| virtual bool | read_image (int subimage, int miplevel, int chbegin, int chend, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride, ProgressCallback progress_callback=NULL, void *progress_callback_data=NULL) |
| virtual bool | read_image (int chbegin, int chend, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride, ProgressCallback progress_callback=NULL, void *progress_callback_data=NULL) |
| bool | read_image (float *data) |
| Simple read_image reads to contiguous float pixels. More... | |
| virtual bool | read_native_scanline (int subimage, int miplevel, int y, int z, void *data)=0 |
| Read a single scanline of native data into contiguous memory. More... | |
| virtual bool | read_native_scanlines (int subimage, int miplevel, int ybegin, int yend, int z, void *data) |
| virtual bool | read_native_scanlines (int subimage, int miplevel, int ybegin, int yend, int z, int chbegin, int chend, void *data) |
| virtual bool | read_native_tile (int subimage, int miplevel, int x, int y, int z, void *data) |
| virtual bool | read_native_tiles (int subimage, int miplevel, int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, void *data) |
| virtual bool | read_native_tiles (int subimage, int miplevel, int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, void *data) |
| virtual bool | read_native_deep_scanlines (int subimage, int miplevel, int ybegin, int yend, int z, int chbegin, int chend, DeepData &deepdata) |
| virtual bool | read_native_deep_tiles (int subimage, int miplevel, int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, DeepData &deepdata) |
| virtual bool | read_native_deep_image (int subimage, int miplevel, DeepData &deepdata) |
| bool | read_native_deep_scanlines (int ybegin, int yend, int z, int chbegin, int chend, DeepData &deepdata) |
| bool | read_native_deep_tiles (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, DeepData &deepdata) |
| bool | read_native_deep_image (DeepData &deepdata) |
| virtual int | send_to_input (const char *format,...) |
| int | send_to_client (const char *format,...) |
| std::string | geterror () const |
| template<typename... Args> | |
| void | error (const char *fmt, const Args &...args) const |
| template<typename... Args> | |
| void | errorf (const char *fmt, const Args &...args) const |
| template<typename... Args> | |
| void | fmterror (const char *fmt, const Args &...args) const |
| void | threads (int n) |
| int | threads () const |
| Retrieve the current thread-spawning policy. More... | |
| void | lock () |
| Lock, try_lock, and unlock for the internal mutex. More... | |
| bool | try_lock () |
| void | unlock () |
| void * | operator new (size_t size) |
| void | operator delete (void *ptr) |
Static Public Member Functions | |
| static unique_ptr | open (const std::string &filename, const ImageSpec *config=nullptr) |
| static unique_ptr | create (const std::string &filename, bool do_open=false, const ImageSpec *config=nullptr, string_view plugin_searchpath="") |
| static unique_ptr | create (const std::string &filename, const std::string &plugin_searchpath) |
| static void | destroy (ImageInput *x) |
Protected Attributes | |
| mutex | m_mutex |
| ImageSpec | m_spec |
ImageInput abstracts the reading of an image file in a file format-agnostic manner.
| typedef ImageInput*(* ImageInput::Creator)() |
| typedef std::lock_guard<mutex> ImageInput::lock_guard |
| typedef std::recursive_mutex ImageInput::mutex |
| using ImageInput::unique_ptr = std::unique_ptr<ImageInput> |
unique_ptr to an ImageInput
| ImageInput::ImageInput | ( | ) |
|
virtual |
|
pure virtual |
Close an image that we are totally done with. The call to close() is not strictly necessary if the ImageInput is destroyed immediately afterwards, since it is required for the destructor to close if the file is still open.
|
static |
Create and return an ImageInput implementation that is able to read the given file. If do_open is true, fully open it if possible (using the optional configuration spec, if supplied), otherwise just create the ImageInput but don't open it. The plugin_searchpath parameter is an override of the searchpath. colon-separated list of directories to search for ImageIO plugin DSO/DLL's (not a searchpath for the image itself!). This will actually just try every imageio plugin it can locate, until it finds one that's able to open the file without error.
If the caller intends to immediately open the file, then it is often simpler to call static ImageInput::open().
|
static |
|
static |
Return the name of the format implemented by this class.
|
inline |
If any of the API routines returned false indicating an error, this routine will return the error string (and clear any error flags). If no error has occurred since the last time geterror() was called, it will return an empty string.
|
inline |
|
static |
Create an ImageInput subclass instance that is able to read the given file and open it, returning a unique_ptr to the ImageInput if successful. The unique_ptr is set up with an appropriate deleter so the ImageInput will be properly deleted when the unique_ptr goes out of scope or is reset. If the open fails, return an empty unique_ptr and set an error that can be retrieved by OpenImageIO::geterror().
The 'config', if not nullptr, points to an ImageSpec giving requests or special instructions. ImageInput implementations are free to not respond to any such requests, so the default implementation is just to ignore config.
open() will first try to make an ImageInput corresponding to the format implied by the file extension (for example, "foo.tif" will try the TIFF plugin), but if one is not found or if the inferred one does not open the file, every known ImageInput type will be tried until one is found that will open the file.
|
pure virtual |
Open file with given name. Various file attributes are put in newspec and a copy is also saved in this->spec. From these attributes, you can discern the resolution, if it's tiled, number of channels, and native data format. Return true if the file was found and opened okay.
|
inlinevirtual |
Open file with given name, similar to open(name,newspec). The 'config' is an ImageSpec giving requests or special instructions. ImageInput implementations are free to not respond to any such requests, so the default implementation is just to ignore config and call regular open(name,newspec).
| void* ImageInput::operator new | ( | size_t | size | ) |
|
virtual |
Read the entire image of spec.width x spec.height x spec.depth pixels into data (which must already be sized large enough for the entire image) with the given strides and in the desired format. Read tiles or scanlines automatically. Strides set to AutoStride imply 'contiguous' data, i.e., xstride == spec.nchannels*format.size() ystride == xstride*spec.width zstride == ystride*spec.height If format is TypeDesc::UNKNOWN, then rather than converting to format, it will just copy pixels in the file's native data layout (including, possibly, per-channel data formats). Because this may be an expensive operation, a progress callback may be passed. Periodically, it will be called as follows: progress_callback (progress_callback_data, float done) where 'done' gives the portion of the image
|
virtual |
Read the entire image of spec.width x spec.height x spec.depth pixels into data (which must already be sized large enough for the entire image) with the given strides and in the desired format. Read tiles or scanlines automatically. Only channels [chbegin,chend) will be read/copied (chbegin=0, chend=spec.nchannels reads all channels, yielding equivalent behavior to the simpler variant of read_image).
|
virtual |
|
inline |
|
virtual |
Read the entire deep data image of spec.width x spec.height x spec.depth pixels, all channels, into deepdata.
|
inline |
|
virtual |
Read into deepdata the block of native deep scanlines corresponding to pixels (*,y,z) for all roi.ybegin <= y < roi.yend, into deepdata. Only channels [roi.chbegin, chend) will be read (roi.chbegin=0, roi.chend=spec.nchannels reads all channels). The x range must be the full width of the image data, and the z range must be just one depth plane.
|
virtual |
Read into deepdata the block of native deep data tiles that include all pixels and channels specified by the ROI.
|
pure virtual |
Read a single scanline of native data into contiguous memory.
|
virtual |
|
virtual |
|
virtual |
Read a single tile (all channels) of native data into contiguous mamory. The base class read_native_tile fails. A format reader that supports tiles MUST overload this virtual method that reads a single tile (all channels).
|
virtual |
Read multiple tiles (all channels) of native data into contigious memory. A format reader that supports reading multiple tiles at once (in a way that's more efficient than reading the tiles one at a time) is advised (but not required) to overload this virtual method. If an ImageInput subclass does not overload this, the default implementation here is simply to loop over the tiles, calling the single-tile read_native_tile() for each one.
|
virtual |
Read multiple tiles (potentially a subset of channels) of native data into contigious memory. A format reader that supports reading multiple tiles at once, and can handle a channel subset while doing so, is advised (but not required) to overload this virtual method. If an ImageInput subclass does not overload this, the default implementation here is simply to loop over the tiles, calling the single-tile read_native_tile() for each one (and copying carefully to handle the channel subset issues).
|
virtual |
Read the scanline that includes pixels (*,y,z) into data, converting if necessary from the native data format of the file into the 'format' specified (z==0 for non-volume images). The stride value gives the data spacing of adjacent pixels (in bytes). Strides set to AutoStride imply 'contiguous' data, i.e., xstride == spec.nchannels*format.size() If format is TypeDesc::UNKNOWN, then rather than converting to format, it will just copy pixels in the file's native data layout (including, possibly, per-channel data formats). The reader is expected to give the appearance of random access – in other words, if it can't randomly seek to the given scanline, it should transparently close, reopen, and sequentially read through prior scanlines. The base ImageInput class has a default implementation that calls read_native_scanline and then does appropriate format conversion, so there's no reason for each format plugin to override this method.
|
virtual |
Read multiple scanlines that include pixels (*,y,z) for all ybegin <= y < yend in the specified subimage and mip level, into data, using the strides given and converting to the requested data format (unless format is TypeDesc::UNKNOWN, in which case pixels will be copied in the native data layout, including per-channel data formats). Only channels [chbegin,chend) will be read/copied (chbegin=0, chend=spec.nchannels reads all channels, yielding equivalent behavior to the simpler variant of read_scanlines).
This version of read_scanlines, because it passes explicit subimage/miplevel, does not require a separate call to seek_subimage, and is guaranteed to be thread-safe against other concurrent calls to any of the read_* methods that take an explicit subimage/miplevel (but not against any other ImageInput methods).
| bool ImageInput::read_scanlines | ( | int | ybegin, |
| int | yend, | ||
| int | z, | ||
| TypeDesc | format, | ||
| void * | data, | ||
| stride_t | xstride = AutoStride, |
||
| stride_t | ystride = AutoStride |
||
| ) |
| bool ImageInput::read_scanlines | ( | int | ybegin, |
| int | yend, | ||
| int | z, | ||
| int | chbegin, | ||
| int | chend, | ||
| TypeDesc | format, | ||
| void * | data, | ||
| stride_t | xstride = AutoStride, |
||
| stride_t | ystride = AutoStride |
||
| ) |
|
virtual |
Read the tile whose upper-left origin is (x,y,z) into data, converting if necessary from the native data format of the file into the 'format' specified. (z==0 for non-volume images.) The stride values give the data spacing of adjacent pixels, scanlines, and volumetric slices (measured in bytes). Strides set to AutoStride imply 'contiguous' data in the shape of a full tile, i.e., xstride == spec.nchannels*format.size() ystride == xstride*spec.tile_width zstride == ystride*spec.tile_height If format is TypeDesc::UNKNOWN, then rather than converting to format, it will just copy pixels in the file's native data layout (including, possibly, per-channel data formats). The reader is expected to give the appearance of random access – in other words, if it can't randomly seek to the given tile, it should transparently close, reopen, and sequentially read through prior tiles. The base ImageInput class has a default implementation that calls read_native_tile and then does appropriate format conversion, so there's no reason for each format plugin to override this method.
|
virtual |
Read the block of tiles that include all pixels and channels in the ROI, at the specified subimage and MIP level. The values are converted to the requested data format (unless format is TypeDesc::UNKNOWN, in which case pixels will be copied in the native data layout, including per-channel data formats), and stored in data according to the optional stride lengths (in bytes).
The stride values give the data spacing of adjacent pixels, scanlines, and volumetric slices (measured in bytes). Strides set to AutoStride imply 'contiguous' data in the shape of the [begin,end) region, i.e., xstride == (chend - chbegin) * format.size() ystride == xstride * (xend - xbegin) zstride == ystride * (yend - ybegin)
This version of read_tiles, because it passes explicit subimage/miplevel, does not require a separate call to seek_subimage, and is guaranteed to be thread-safe against other concurrent calls to any of the read_* methods that take an explicit subimage/miplevel (but not against any other ImageInput methods).
| bool ImageInput::read_tiles | ( | int | xbegin, |
| int | xend, | ||
| int | ybegin, | ||
| int | yend, | ||
| int | zbegin, | ||
| int | zend, | ||
| TypeDesc | format, | ||
| void * | data, | ||
| stride_t | xstride = AutoStride, |
||
| stride_t | ystride = AutoStride, |
||
| stride_t | zstride = AutoStride |
||
| ) |
| bool ImageInput::read_tiles | ( | int | xbegin, |
| int | xend, | ||
| int | ybegin, | ||
| int | yend, | ||
| int | zbegin, | ||
| int | zend, | ||
| int | chbegin, | ||
| int | chend, | ||
| TypeDesc | format, | ||
| void * | data, | ||
| stride_t | xstride = AutoStride, |
||
| stride_t | ystride = AutoStride, |
||
| stride_t | zstride = AutoStride |
||
| ) |
Seek to the given subimage and MIP-map level within the open image file. The first subimage of the file has index 0, the highest- resolution MIP level has index 0. Return true on success, false on failure (including that there is not a subimage or MIP level with the specified index). The new subimage's vital statistics are put in *newspec (if not NULL) and may also be retrieved by in this->spec()). The reader is expected to give the appearance of random access to subimages and MIP levels – in other words, if it can't randomly seek to the given subimage/level, it should transparently close, reopen, and sequentially read through prior subimages and levels.
General message passing between client and image input server
Return a reference to the image format specification of the current subimage/MIPlevel. Note that the contents of the spec are invalid before open() or after close(), and may change with a call to seek_subimage(). It is thus not thread-safe, since the spec may change if another thread calls seek_subimage, or any of the read_*() functions that take explicit subimage/miplevel.
Return a full copy of the ImageSpec of the designated subimage and MIPlevel. This method is thread-safe, but it is potentially expensive, due to the work that needs to be done to fully copy an ImageSpec if there is lots of named metadata to allocate and copy. See also the less expensive spec_dimensions(). Errors (such as having requested a nonexistant subimage) are indicated by returning an ImageSpec with format==TypeUnknown.
Return a copy of the ImageSpec of the designated subimage and miplevel, but only the dimension and type fields. Just as with a call to ImageSpec::copy_dimensions(), neither the channel names nor any of the arbitrary named metadata will be copied, thus this is a relatively inexpensive operation if you don't need that information. It is guaranteed to be thread-safe. Errors (such as having requested a nonexistant subimage) are indicated by returning an ImageSpec with format==TypeUnknown.
|
inlinevirtual |
Given the name of a 'feature', return whether this ImageInput supports input of images with the given properties. Most queries will simply return 0 for "doesn't support" and nonzero for "supports it", but it is acceptable to have queries return other nonzero integers to indicate varying degrees of support or limits (but should be clearly documented as such).
Feature names that ImageIO plugins are expected to recognize include: "arbitrary_metadata" Does this format allow metadata with arbitrary names and types? "exif" Can this format store Exif camera data? "iptc" Can this format store IPTC data? "procedural" Can this format create images without reading from a disk file? "ioproxy" Does this format reader support IOProxy?
Note that main advantage of this approach, versus having separate individual supports_foo() methods, is that this allows future expansion of the set of possible queries without changing the API, adding new entry points, or breaking linkage compatibility.
Set the current thread-spawning policy: the maximum number of threads that may be spawned by ImageInput internals. A value of 1 means all work will be done by the calling thread; 0 means to use the global OIIO::attribute("threads") value.
|
inline |
|
virtual |
Return true if the named file is file of the type for this ImageInput. The implementation will try to determine this as efficiently as possible, in most cases much less expensively than doing a full open(). Note that a file can appear to be of the right type (i.e., valid_file() returning true) but still fail a subsequent call to open(), such as if the contents of the file are truncated, nonsensical, or otherwise corrupted.
1.8.6 
