OpenImageIO
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Member Functions | Static Public Member Functions | List of all members
ImageInput Class Referenceabstract

#include <imageio.h>

Public Member Functions

virtual const char * format_name (void) const =0
 
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 &)
 
const ImageSpecspec (void) const
 
virtual bool supports (const std::string &) const
 
virtual bool close ()=0
 
virtual int current_subimage (void) const
 
virtual int current_miplevel (void) const
 
virtual 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)
 
virtual bool read_scanlines (int ybegin, int yend, int z, TypeDesc format, void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride)
 
virtual 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)
 
virtual 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)
 
virtual 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)
 
bool read_image (float *data)
 
virtual bool read_native_scanline (int y, int z, void *data)=0
 
virtual bool read_native_scanlines (int ybegin, int yend, int z, void *data)
 
virtual bool read_native_scanlines (int ybegin, int yend, int z, int chbegin, int chend, void *data)
 
virtual bool read_native_tile (int x, int y, int z, void *data)
 
virtual bool read_native_tiles (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, void *data)
 
virtual bool read_native_tiles (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 ybegin, int yend, int z, int chbegin, int chend, DeepData &deepdata)
 
virtual bool read_native_deep_tiles (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, DeepData &deepdata)
 
virtual 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
 

Static Public Member Functions

static ImageInputopen (const std::string &filename, const ImageSpec *config=NULL)
 
static ImageInputcreate (const std::string &filename, const std::string &plugin_searchpath="")
 

Detailed Description

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

Member Function Documentation

virtual bool ImageInput::close ( )
pure virtual

Close an image that we are totally done with.

static ImageInput* ImageInput::create ( const std::string &  filename,
const std::string &  plugin_searchpath = "" 
)
static

Create and return an ImageInput implementation that is willing to read the given file. The plugin_searchpath parameter is a 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. This just creates the ImageInput, it does not open the file.

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

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.

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.

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.

static ImageInput* ImageInput::open ( const std::string &  filename,
const ImageSpec config = NULL 
)
static

Create an ImageInput subclass instance that is able to read the given file and open it, returning the opened ImageInput if successful. If it fails, return NULL and set an error that can be retrieved by OpenImageIO::geterror().

The 'config', if not NULL, 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).

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

bool ImageInput::read_image ( float *  data)
inline

Simple read_image reads to contiguous float pixels.

virtual bool ImageInput::read_native_deep_image ( DeepData deepdata)
virtual

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

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

Read native deep data from multiple scanlines that include pixels (*,y,z) for all ybegin <= y < yend, into deepdata. Only channels [chbegin, chend) will be read (chbegin=0, chend=spec.nchannels reads all channels).

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

Read the block of multiple native deep data tiles that include all pixels in [xbegin,xend) X [ybegin,yend) X [zbegin,zend), into deepdata. Only channels [chbegin,chend) will be read (chbegin=0, chend=spec.nchannels reads all channels).

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

read_native_scanline is just like read_scanline, except that it keeps the data in the native format of the disk file and always reads into contiguous memory (no strides). It's up to the user to have enough space allocated and know what to do with the data. IT IS EXPECTED THAT EACH FORMAT PLUGIN WILL OVERRIDE THIS METHOD.

virtual bool ImageInput::read_native_scanlines ( int  ybegin,
int  yend,
int  z,
void *  data 
)
virtual

read_native_scanlines is just like read_scanlines, except that it keeps the data in the native format of the disk file and always reads into contiguous memory (no strides). It's up to the user to have enough space allocated and know what to do with the data. If a format reader subclass does not override this method, the default implementation it will simply be a loop calling read_native_scanline for each scanline.

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

A variant of read_native_scanlines that reads only channels [chbegin,chend). If a format reader subclass does not override this method, the default implementation will simply call the all-channel version of read_native_scanlines into a temporary buffer and copy the subset of channels.

virtual bool ImageInput::read_native_tile ( int  x,
int  y,
int  z,
void *  data 
)
virtual

read_native_tile is just like read_tile, except that it keeps the data in the native format of the disk file and always read into contiguous memory (no strides). It's up to the user to have enough space allocated and know what to do with the data. IT IS EXPECTED THAT EACH FORMAT PLUGIN WILL OVERRIDE THIS METHOD IF IT SUPPORTS TILED IMAGES.

virtual bool ImageInput::read_native_tiles ( int  xbegin,
int  xend,
int  ybegin,
int  yend,
int  zbegin,
int  zend,
void *  data 
)
virtual

read_native_tiles is just like read_tiles, except that it keeps the data in the native format of the disk file and always reads into contiguous memory (no strides). It's up to the caller to have enough space allocated and know what to do with the data. If a format reader does not override this method, the default implementation it will simply be a loop calling read_native_tile for each tile in the block.

virtual bool ImageInput::read_native_tiles ( int  xbegin,
int  xend,
int  ybegin,
int  yend,
int  zbegin,
int  zend,
int  chbegin,
int  chend,
void *  data 
)
virtual

A variant of read_native_tiles that reads only channels [chbegin,chend). If a format reader subclass does not override this method, the default implementation will simply call the all-channel version of read_native_tiles into a temporary buffer and copy the subset of channels.

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.

virtual bool ImageInput::read_scanlines ( int  ybegin,
int  yend,
int  z,
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, 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). This is analogous to read_scanline except that it may be used to read more than one scanline at a time (which, for some formats, may be able to be done much more efficiently or in parallel).

virtual 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 multiple scanlines that include pixels (*,y,z) for all ybegin <= y < yend, 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).

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, 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.

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

Read the block of multiple tiles that include all pixels in [xbegin,xend) X [ybegin,yend) X [zbegin,zend), 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). This is analogous to read_tile except that it may be used to read more than one tile at a time (which, for some formats, may be able to be done much 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.

virtual 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

Read the block of multiple tiles that include all pixels in [xbegin,xend) X [ybegin,yend) X [zbegin,zend), 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_tiles).

virtual bool ImageInput::seek_subimage ( int  subimage,
int  miplevel,
ImageSpec newspec 
)
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 (and also saved 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.

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

Seek to the given subimage – backwards-compatible call that doesn't worry about MIP-map levels at all.

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

General message passing between client and image input server

const ImageSpec& ImageInput::spec ( void  ) const
inline

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

virtual bool ImageInput::supports ( const std::string &  ) const
inlinevirtual

Given the name of a 'feature', return whether this ImageInput supports input of images with the given properties. Feature names that ImageIO plugins are expected to recognize include: none at this time

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.

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.


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