HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImageInput Class Referenceabstract

#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< mutexlock_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 ImageSpecspec (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 ()
 
voidoperator 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
 

Detailed Description

ImageInput abstracts the reading of an image file in a file format-agnostic manner.

Definition at line 616 of file imageio.h.

Member Typedef Documentation

typedef ImageInput*(* ImageInput::Creator)()

Call signature of a function that creates and returns an ImageInput*.

Definition at line 1156 of file imageio.h.

typedef std::lock_guard<mutex> ImageInput::lock_guard

Definition at line 666 of file imageio.h.

typedef std::recursive_mutex ImageInput::mutex

Definition at line 665 of file imageio.h.

using ImageInput::unique_ptr = std::unique_ptr<ImageInput>

unique_ptr to an ImageInput

Definition at line 619 of file imageio.h.

Constructor & Destructor Documentation

ImageInput::ImageInput ( )
virtual ImageInput::~ImageInput ( )
virtual

Member Function Documentation

virtual bool ImageInput::close ( )
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 unique_ptr ImageInput::create ( const std::string filename,
bool  do_open = false,
const ImageSpec config = nullptr,
string_view  plugin_searchpath = "" 
)
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 unique_ptr ImageInput::create ( const std::string filename,
const std::string plugin_searchpath 
)
static
virtual int ImageInput::current_miplevel ( void  ) const
inlinevirtual

Returns the index of the MIPmap image that is currently being read. The highest-res MIP level (or the only level, if there is just one) is number 0.

Definition at line 761 of file imageio.h.

virtual int ImageInput::current_subimage ( void  ) const
inlinevirtual

Returns the index of the subimage that is currently being read. The first subimage (or the only subimage, if there is just one) is number 0.

Definition at line 756 of file imageio.h.

static void ImageInput::destroy ( ImageInput x)
static
template<typename... Args>
void ImageInput::error ( const char *  fmt,
const Args &...  args 
) const
inline

Error reporting for the plugin implementation: call this with Strutil::format-like arguments. Use with caution! Some day this will change to be fmt-like rather than printf-like.

Definition at line 1118 of file imageio.h.

template<typename... Args>
void ImageInput::errorf ( const char *  fmt,
const Args &...  args 
) const
inline

Error reporting for the plugin implementation: call this with printf-like arguments.

Definition at line 1125 of file imageio.h.

template<typename... Args>
void ImageInput::fmterror ( const char *  fmt,
const Args &...  args 
) const
inline

Error reporting for the plugin implementation: call this with fmt::format-like arguments.

Definition at line 1132 of file imageio.h.

virtual const char* ImageInput::format_name ( void  ) const
pure virtual

Return the name of the format implemented by this class.

std::string ImageInput::geterror ( void  ) const
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.

Definition at line 1106 of file imageio.h.

void ImageInput::lock ( )
inline

Lock, try_lock, and unlock for the internal mutex.

Definition at line 1146 of file imageio.h.

static unique_ptr ImageInput::open ( const std::string filename,
const ImageSpec config = nullptr 
)
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.

virtual bool ImageInput::open ( const std::string name,
ImageSpec newspec 
)
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.

virtual bool ImageInput::open ( const std::string name,
ImageSpec newspec,
const ImageSpec  
)
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).

Definition at line 717 of file imageio.h.

void ImageInput::operator delete ( void ptr)
void* ImageInput::operator new ( size_t  size)
virtual bool ImageInput::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

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 bool ImageInput::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

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 bool ImageInput::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 
)
virtual
bool ImageInput::read_image ( float *  data)
inline

Simple read_image reads to contiguous float pixels.

Definition at line 977 of file imageio.h.

virtual bool ImageInput::read_native_deep_image ( int  subimage,
int  miplevel,
DeepData deepdata 
)
virtual

Read the entire deep data image of spec.width x spec.height x spec.depth pixels, all channels, into deepdata.

bool ImageInput::read_native_deep_image ( DeepData deepdata)
inline

Definition at line 1091 of file imageio.h.

virtual bool ImageInput::read_native_deep_scanlines ( int  subimage,
int  miplevel,
int  ybegin,
int  yend,
int  z,
int  chbegin,
int  chend,
DeepData deepdata 
)
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.

bool ImageInput::read_native_deep_scanlines ( int  ybegin,
int  yend,
int  z,
int  chbegin,
int  chend,
DeepData deepdata 
)
inline

Definition at line 1078 of file imageio.h.

virtual bool ImageInput::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

Read into deepdata the block of native deep data tiles that include all pixels and channels specified by the ROI.

bool ImageInput::read_native_deep_tiles ( int  xbegin,
int  xend,
int  ybegin,
int  yend,
int  zbegin,
int  zend,
int  chbegin,
int  chend,
DeepData deepdata 
)
inline

Definition at line 1084 of file imageio.h.

virtual bool ImageInput::read_native_scanline ( int  subimage,
int  miplevel,
int  y,
int  z,
void data 
)
pure virtual

Read a single scanline of native data into contiguous memory.

virtual bool ImageInput::read_native_scanlines ( int  subimage,
int  miplevel,
int  ybegin,
int  yend,
int  z,
void data 
)
virtual
virtual bool ImageInput::read_native_scanlines ( int  subimage,
int  miplevel,
int  ybegin,
int  yend,
int  z,
int  chbegin,
int  chend,
void data 
)
virtual
virtual bool ImageInput::read_native_tile ( int  subimage,
int  miplevel,
int  x,
int  y,
int  z,
void data 
)
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 bool ImageInput::read_native_tiles ( int  subimage,
int  miplevel,
int  xbegin,
int  xend,
int  ybegin,
int  yend,
int  zbegin,
int  zend,
void data 
)
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 bool ImageInput::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

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 bool ImageInput::read_scanline ( int  y,
int  z,
TypeDesc  format,
void data,
stride_t  xstride = AutoStride 
)
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.

bool ImageInput::read_scanline ( int  y,
int  z,
float *  data 
)
inline

Simple read_scanline reads to contiguous float pixels.

Definition at line 817 of file imageio.h.

virtual bool ImageInput::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 
)
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 bool ImageInput::read_tile ( int  x,
int  y,
int  z,
TypeDesc  format,
void data,
stride_t  xstride = AutoStride,
stride_t  ystride = AutoStride,
stride_t  zstride = 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.

bool ImageInput::read_tile ( int  x,
int  y,
int  z,
float *  data 
)
inline

Simple read_tile reads to contiguous float pixels.

Definition at line 882 of file imageio.h.

virtual bool ImageInput::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 
)
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 
)
virtual bool ImageInput::seek_subimage ( int  subimage,
int  miplevel 
)
inlinevirtual

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.

Definition at line 774 of file imageio.h.

bool ImageInput::seek_subimage ( int  subimage,
int  miplevel,
ImageSpec newspec 
)
inline

Definition at line 782 of file imageio.h.

bool ImageInput::seek_subimage ( int  subimage,
ImageSpec newspec 
)
inline

Definition at line 792 of file imageio.h.

int ImageInput::send_to_client ( const char *  format,
  ... 
)
virtual int ImageInput::send_to_input ( const char *  format,
  ... 
)
virtual

General message passing between client and image input server

virtual const ImageSpec& ImageInput::spec ( void  ) const
inlinevirtual

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.

Definition at line 726 of file imageio.h.

virtual ImageSpec ImageInput::spec ( int  subimage,
int  miplevel = 0 
)
virtual

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.

virtual ImageSpec ImageInput::spec_dimensions ( int  subimage,
int  miplevel = 0 
)
virtual

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.

virtual int ImageInput::supports ( string_view  feature) const
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.

Definition at line 694 of file imageio.h.

void ImageInput::threads ( int  n)
inline

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.

Definition at line 1140 of file imageio.h.

int ImageInput::threads ( ) const
inline

Retrieve the current thread-spawning policy.

Definition at line 1143 of file imageio.h.

bool ImageInput::try_lock ( )
inline

Definition at line 1147 of file imageio.h.

void ImageInput::unlock ( )
inline

Definition at line 1148 of file imageio.h.

virtual bool ImageInput::valid_file ( const std::string filename) const
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.

Member Data Documentation

mutex ImageInput::m_mutex
mutableprotected

Definition at line 1159 of file imageio.h.

ImageSpec ImageInput::m_spec
protected

Definition at line 1160 of file imageio.h.


The documentation for this class was generated from the following file: