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 )()
 

Public Member Functions

virtual ~ImageInput ()
 
virtual const char * format_name (void) const =0
 Return the name of the format implemented by this class. More...
 
virtual int supports (string_view feature OIIO_MAYBE_UNUSED) 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 &config OIIO_MAYBE_UNUSED)
 
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 int send_to_input (const char *format,...)
 
int send_to_client (const char *format,...)
 
virtual bool set_ioproxy (Filesystem::IOProxy *ioproxy)
 
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 errorfmt (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
 
void lock ()
 Lock the internal mutex, block until the lock is acquired. More...
 
bool try_lock ()
 
void unlock ()
 Ulock the internal mutex. More...
 
voidoperator new (size_t size)
 
void operator delete (void *ptr)
 
Reading pixels

Common features of all the read methods:

  • The format parameter describes the data type of the data[] buffer. The read methods automatically convert the data from the data type it is stored in the file into the format of the data buffer. If format is TypeUnknown it will just copy pixels of file's native data layout (including, possibly, per-channel data formats as specified by the ImageSpec's channelfomats field).
  • The stride values describe the layout of the data buffer: xstride is the distance in bytes between successive pixels within each scanline. ystride is the distance in bytes between successive scanlines. For volumetric images zstride is the distance in bytes between successive "volumetric planes". Strides set to the special value AutoStride imply contiguous data, i.e.,
    xstride = format.size() * nchannels
    ystride = xstride * width
    zstride = ystride * height
    
  • Any range parameters (such as ybegin and yend) describe a "half open interval", meaning that begin is the first item and end is one past the last item. That means that the number of items is end - begin.
  • For ordinary 2D (non-volumetric) images, any z or zbegin coordinates should be 0 and any zend should be 1, indicating that only a single image "plane" exists.
  • Some read methods take a channel range [chbegin,chend) to allow reading of a contiguous subset of channels (chbegin=0, chend=spec.nchannels reads all channels).
  • ImageInput readers are expected to give the appearance of random access – in other words, if it can't randomly seek to the given scanline or tile, it should transparently close, reopen, and sequentially read through prior scanlines.
  • All read functions return true for success, false for failure (after which a call to geterror() may retrieve a specific error message).
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 into 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 into 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 (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 (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)
 
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)
 
Reading native pixels -- implementation overloads
Note
read_native_* methods are usually not directly called by user code (except for read_native_deep_* varieties). These are the methods that are overloaded by the ImageInput subclasses that implement the individual file format readers.
virtual bool read_native_scanline (int subimage, int miplevel, int y, int z, void *data)=0
 
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)
 

Static Public Member Functions

static void destroy (ImageInput *x)
 
Creating an ImageIntput
static unique_ptr open (const std::string &filename, const ImageSpec *config=nullptr, Filesystem::IOProxy *ioproxy=nullptr)
 
static unique_ptr create (string_view filename, bool do_open=false, const ImageSpec *config=nullptr, Filesystem::IOProxy *ioproxy=nullptr, string_view plugin_searchpath="")
 
static unique_ptr create (const std::string &filename, bool do_open, const ImageSpec *config, string_view plugin_searchpath)
 
static unique_ptr create (const std::string &filename, const std::string &plugin_searchpath)
 

Protected Member Functions

 ImageInput ()
 

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 802 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 1642 of file imageio.h.

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

Definition at line 928 of file imageio.h.

typedef std::recursive_mutex ImageInput::mutex

Definition at line 927 of file imageio.h.

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

unique_ptr to an ImageInput

Definition at line 805 of file imageio.h.

Constructor & Destructor Documentation

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

Member Function Documentation

virtual bool ImageInput::close ( )
pure virtual

Close an open ImageInput. 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.

Returns
true upon success, or false upon failure.
static unique_ptr ImageInput::create ( string_view  filename,
bool  do_open = false,
const ImageSpec config = nullptr,
Filesystem::IOProxy ioproxy = nullptr,
string_view  plugin_searchpath = "" 
)
static

Create and return an ImageInput implementation that is able to read the given file or format. If do_open is true (and the filename is the name of a file, not just a format), fully open it if possible (using the optional config 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!).

If the filename parameter is the name of a file format (such as "openexr"), it will create an ImageInput that reads that particular format. If the name is a file extension (such as "exr" or ".exr"), it will guess the file format from the extension and return that type of ImageInput.

If filename is a full file name (such as "hawaii.exr"), it will create an ImageInput that reads the format implied by the file extension (".tif") and try to open the file with that reader. If the file can be opened and appears to be of the correct type, then that ImageInput (after being closed) will be returned to the caller. But if it fails (say, because the file type does not match the extension), then every known kind of image reader will be tried in turn, until one can be found that succeeds in opening that file. The create() file will fail entirely only if no known image reader type succeeds.

If the caller intends to immediately open the file, then it is often simpler to call static ImageInput::open().

Parameters
filenameThe name of an image file, or a file extension, or the name of a file format.
do_openIf true, not only create but also open the file.
configOptional pointer to an ImageSpec whose metadata contains "configuration hints" for the ImageInput implementation.
ioproxyOptional pointer to an IOProxy to use (not supported by all formats, see supports("ioproxy")). The caller retains ownership of the proxy. If this is not supplied, it is still possible to set the proxy with a call to set_proxy() prior to open().
plugin_searchpathAn optional colon-separated list of directories to search for OpenImageIO plugin DSO/DLL's.
Returns
A unique_ptr that will close and free the ImageInput when it exits scope or is reset. The pointer will be empty if the required writer was not able to be created.
static unique_ptr ImageInput::create ( const std::string filename,
bool  do_open,
const ImageSpec config,
string_view  plugin_searchpath 
)
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 closed and 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 OIIO::geterror().

The config, if not nullptr, points to an ImageSpec giving hints, 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.

Parameters
filenameThe name of the file to open.
configOptional pointer to an ImageSpec whose metadata contains "configuration hints."
ioproxyOptional pointer to an IOProxy to use (not supported by all formats, see supports("ioproxy")). The caller retains ownership of the proxy.
Returns
A unique_ptr that will close and free the ImageInput when it exits scope or is reset. The pointer will be empty if the required writer was not able to be created.
static unique_ptr ImageInput::create ( const std::string filename,
const std::string plugin_searchpath 
)
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 closed and 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 OIIO::geterror().

The config, if not nullptr, points to an ImageSpec giving hints, 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.

Parameters
filenameThe name of the file to open.
configOptional pointer to an ImageSpec whose metadata contains "configuration hints."
ioproxyOptional pointer to an IOProxy to use (not supported by all formats, see supports("ioproxy")). The caller retains ownership of the proxy.
Returns
A unique_ptr that will close and free the ImageInput when it exits scope or is reset. The pointer will be empty if the required writer was not able to be created.
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 1069 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 1064 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 1584 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 1591 of file imageio.h.

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

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

Definition at line 1598 of file imageio.h.

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

Definition at line 1606 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 method 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 1572 of file imageio.h.

void ImageInput::lock ( )
inline

Lock the internal mutex, block until the lock is acquired.

Definition at line 1628 of file imageio.h.

static unique_ptr ImageInput::open ( const std::string filename,
const ImageSpec config = nullptr,
Filesystem::IOProxy ioproxy = 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 closed and 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 OIIO::geterror().

The config, if not nullptr, points to an ImageSpec giving hints, 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.

Parameters
filenameThe name of the file to open.
configOptional pointer to an ImageSpec whose metadata contains "configuration hints."
ioproxyOptional pointer to an IOProxy to use (not supported by all formats, see supports("ioproxy")). The caller retains ownership of the proxy.
Returns
A unique_ptr that will close and free the ImageInput when it exits scope or is reset. The pointer will be empty if the required writer was not able to be created.
virtual bool ImageInput::open ( const std::string name,
ImageSpec newspec 
)
pure virtual

Opens the file with given name and seek to the first subimage in the file. Various file attributes are put in newspec and a copy is also saved internally to the ImageInput (retrievable via spec(). From examining newspec or spec(), you can discern the resolution, if it's tiled, number of channels, native data format, and other metadata about the image.

Parameters
nameFilename to open.
newspecReference to an ImageSpec in which to deposit a full description of the contents of the first subimage of the file.
Returns
true if the file was found and opened successfully.
virtual bool ImageInput::open ( const std::string name,
ImageSpec newspec,
const ImageSpec &config  OIIO_MAYBE_UNUSED 
)
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).

Parameters
nameFilename to open.
newspecReference to an ImageSpec in which to deposit a full description of the contents of the first subimage of the file.
configAn ImageSpec whose metadata contains "configuration hints" for the ImageInput implementation.
Returns
true if the file was found and opened successfully.

Definition at line 1020 of file imageio.h.

void ImageInput::operator delete ( void ptr)
void* ImageInput::operator new ( size_t  size)
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 a buffer with the given strides and in the desired data format.

Depending on the spec, this will read either all tiles or all scanlines. Assume that data points to a layout in row-major order.

This version of read_image, because it passes explicit subimage and 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).

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 (between 0.0 and 1.0) that has been written thus far.

Parameters
subimageThe subimage to read from (starting with 0).
miplevelThe MIP level to read (0 is the highest resolution level).
chbegin/chendThe channel range to read.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystride/zstrideThe distance in bytes between successive pixels, scanlines, and image planes (or AutoStride).
progress_callback/progress_callback_dataOptional progress callback.
Returns
true upon success, or false upon failure.
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 scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.
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

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.
bool ImageInput::read_image ( float *  data)
inline

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.

Definition at line 1393 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.

Parameters
subimageThe subimage to read from (starting with 0).
miplevelThe MIP level to read (0 is the highest resolution level).
deepdataA DeepData object into which the data for the image will be placed.
Returns
true upon success, or false upon failure.
bool ImageInput::read_native_deep_image ( DeepData deepdata)
inline

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.

Definition at line 1469 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 deep scanlines containing pixels (*,y,z), for all y in the range [ybegin,yend) into deepdata. This will fail if it is not a deep file.

Parameters
subimageThe subimage to read from (starting with 0).
miplevelThe MIP level to read (0 is the highest resolution level).
chbegin/chendThe channel range to read.
ybegin/yendThe y range of the scanlines being passed.
zThe z coordinate of the scanline.
deepdataA DeepData object into which the data for these scanlines will be placed.
Returns
true upon success, or false upon failure.
bool ImageInput::read_native_deep_scanlines ( int  ybegin,
int  yend,
int  z,
int  chbegin,
int  chend,
DeepData deepdata 
)
inline

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.

Definition at line 1456 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 pixel range.

Parameters
subimageThe subimage to read from (starting with 0).
miplevelThe MIP level to read (0 is the highest resolution level).
xbegin/xendThe x range of the pixels covered by the group of tiles being read.
ybegin/yendThe y range of the pixels covered by the tiles.
zbegin/zendThe z range of the pixels covered by the tiles (for a 2D image, zbegin=0 and zend=1).
chbegin/chendThe channel range to read.
deepdataA DeepData object into which the data for these tiles will be placed.
Returns
true upon success, or false upon failure.
Note
The call will fail if the image is not tiled, or if the pixel ranges do not fall along tile (or image) boundaries, or if it is not a valid tile range.
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

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.

Definition at line 1462 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 (all channels) 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

Read a range of scanlines (all channels) of native data into contiguous memory.

virtual bool ImageInput::read_native_scanlines ( int  subimage,
int  miplevel,
int  ybegin,
int  yend,
int  z,
int  chbegin,
int  chend,
void data 
)
virtual

Read a range of scanlines (with optionally a subset of channels) of native data into contiguous memory.

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 memory. 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) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.
bool ImageInput::read_scanline ( int  y,
int  z,
float *  data 
)
inline

Simple read_scanline reads into contiguous float pixels.

Definition at line 1173 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 (TypeUnknown indicates no conversion, just copy native data types). 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).

Parameters
subimageThe subimage to read from (starting with 0).
miplevelThe MIP level to read (0 is the highest resolution level).
ybegin/yendThe y range of the scanlines being passed.
zThe z coordinate of the scanline.
chbegin/chendThe channel range to read.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystrideThe distance in bytes between successive pixels and scanlines (or AutoStride).
Returns
true upon success, or false upon failure.
Note
This call was changed for OpenImageIO 2.0 to include the explicit subimage and miplevel parameters. The previous versions, which lacked subimage and miplevel parameters (thus were dependent on a prior call to seek_subimage) are considered deprecated.
bool ImageInput::read_scanlines ( int  ybegin,
int  yend,
int  z,
TypeDesc  format,
void data,
stride_t  xstride = AutoStride,
stride_t  ystride = AutoStride 
)

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.
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 
)

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.
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. 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 = format.size() * spec.nchannels
ystride = xstride * spec.tile_width
zstride = ystride * spec.tile_height
Note
This variety of read_tile is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_tiles() that has the subimage and miplevel passed explicitly.
Parameters
x/y/zThe upper left coordinate of the tile being passed.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystride/zstrideThe distance in bytes between successive pixels, scanlines, and image planes (or AutoStride to indicate a "contiguous" single tile).
Returns
true upon success, or false upon failure.
Note
This call will fail if the image is not tiled, or if (x,y,z) is not the upper left corner coordinates of a tile.
bool ImageInput::read_tile ( int  x,
int  y,
int  z,
float *  data 
)
inline

Simple read_tile reads into contiguous float pixels.

Definition at line 1264 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 multiple tiles that include all pixels in

[xbegin,xend) X [ybegin,yend) X [zbegin,zend)

This is analogous to calling read_tile(x,y,z,...) for each tile in turn (but for some file formats, reading multiple tiles may allow it to read more efficiently or in parallel).

The begin/end pairs must correctly delineate tile boundaries, with the exception that it may also be the end of the image data if the image resolution is not a whole multiple of the tile size. 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 = format.size() * spec.nchannels
ystride = xstride * (xend-xbegin)
zstride = ystride * (yend-ybegin)

This version of read_tiles, because it passes explicit subimage and 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).

Parameters
subimageThe subimage to read from (starting with 0).
miplevelThe MIP level to read (0 is the highest resolution level).
xbegin/xendThe x range of the pixels covered by the group of tiles being read.
ybegin/yendThe y range of the pixels covered by the tiles.
zbegin/zendThe z range of the pixels covered by the tiles (for a 2D image, zbegin=0 and zend=1).
chbegin/chendThe channel range to read.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystride/zstrideThe distance in bytes between successive pixels, scanlines, and image planes (or AutoStride).
Returns
true upon success, or false upon failure.
Note
The call will fail if the image is not tiled, or if the pixel ranges do not fall along tile (or image) boundaries, or if it is not a valid tile range.
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 
)

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.
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 
)

Read the scanline that includes pixels (*,y,z) from the "current" subimage and MIP level. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Note
This variety of read_scanline is not re-entrant nor thread-safe. If you require concurrent reads to the same open ImageInput, you should use read_scanlines that has the subimage and miplevel passed explicitly.
Parameters
y/zThe y & z coordinates of the scanline. For 2D images, z should be 0.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data buffer.
xstrideThe distance in bytes between successive pixels in data (or AutoStride).
Returns
true upon success, or false upon failure.
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. The new subimage's vital statistics=may be retrieved by 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.

Returns
true upon success, or false upon failure. A failure may indicate that no such subimage or MIP level exists in the file.

Definition at line 1084 of file imageio.h.

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

Definition at line 1092 of file imageio.h.

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

Definition at line 1102 of file imageio.h.

int ImageInput::send_to_client ( const char *  format,
  ... 
)
virtual int ImageInput::send_to_input ( const char *  format,
  ... 
)
virtual
virtual bool ImageInput::set_ioproxy ( Filesystem::IOProxy ioproxy)
inlinevirtual

Set an IOProxy for this reader. This must be called prior to open(), and only for readers that support them (supports("ioproxy")). The caller retains ownership of the proxy.

Returns
true for success, false for failure.

Definition at line 1564 of file imageio.h.

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

Return a reference to the image 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 1031 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 nonexistent 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 nonexistent subimage) are indicated by returning an ImageSpec with format==TypeUnknown.

virtual int ImageInput::supports ( string_view feature  OIIO_MAYBE_UNUSED) const
inlinevirtual

Given the name of a "feature", return whether this ImageInput supports output of images with the given properties. Most queries will simply return 0 for "doesn't support" and 1 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 ImageInput implementations 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 reading from an IOProxy?

This list of queries may be extended in future releases. Since this can be done simply by recognizing new query strings, and does not require any new API entry points, addition of support for new queries does not break ``link compatibility'' with previously-compiled plugins.

Definition at line 964 of file imageio.h.

void ImageInput::threads ( int  n)
inline

Set the threading policy for this ImageInput, controlling the maximum amount of parallelizing thread "fan-out" that might occur during large read operations. The default of 0 means that the global attribute("threads") value should be used (which itself defaults to using as many threads as cores; see Section Global Attributes_).

The main reason to change this value is to set it to 1 to indicate that the calling thread should do all the work rather than spawning new threads. That is probably the desired behavior in situations where the calling application has already spawned multiple worker threads.

Definition at line 1621 of file imageio.h.

int ImageInput::threads ( ) const
inline

Retrieve the current thread-spawning policy.

See Also
threads(int)

Definition at line 1625 of file imageio.h.

bool ImageInput::try_lock ( )
inline

Try to lock the internal mutex, returning true if successful, or false if the lock could not be immediately acquired.

Definition at line 1631 of file imageio.h.

void ImageInput::unlock ( )
inline

Ulock the internal mutex.

Definition at line 1633 of file imageio.h.

virtual bool ImageInput::valid_file ( const std::string filename) const
virtual

Return true if the filename names a 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 there can be false positives: 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.

Returns
true upon success, or false upon failure.

Member Data Documentation

mutex ImageInput::m_mutex
mutableprotected

Definition at line 1645 of file imageio.h.

ImageSpec ImageInput::m_spec
protected

Definition at line 1646 of file imageio.h.


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