OpenImageIO
|
#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 ImageSpec & | spec (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 ImageInput * | open (const std::string &filename, const ImageSpec *config=NULL) |
static ImageInput * | create (const std::string &filename, const std::string &plugin_searchpath="") |
ImageInput abstracts the reading of an image file in a file format-agnostic manner.
|
pure virtual |
Close an image that we are totally done with.
|
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().
|
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.
|
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.
|
pure virtual |
Return the name of the format implemented by this class.
|
inline |
If any of the API routines returned false indicating an error, this routine will return the error string (and clear any error flags). If no error has occurred since the last time geterror() was called, it will return an empty string.
|
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.
|
pure virtual |
Open file with given name. Various file attributes are put in newspec and a copy is also saved in this->spec. From these attributes, you can discern the resolution, if it's tiled, number of channels, and native data format. Return true if the file was found and opened okay.
|
inlinevirtual |
Open file with given name, similar to open(name,newspec). The 'config' is an ImageSpec giving requests or special instructions. ImageInput implementations are free to not respond to any such requests, so the default implementation is just to ignore config and call regular open(name,newspec).
|
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
|
inline |
Simple read_image reads to contiguous float pixels.
|
virtual |
Read the entire deep data image of spec.width x spec.height x spec.depth pixels, all channels, into 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 |
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).
|
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 |
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 |
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 |
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 |
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 |
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 |
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.
|
inline |
Simple read_scanline reads to contiguous float pixels.
|
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 |
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 |
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.
|
inline |
Simple read_tile reads to contiguous float pixels.
|
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 |
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).
|
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.
|
inline |
Seek to the given subimage – backwards-compatible call that doesn't worry about MIP-map levels at all.
|
virtual |
General message passing between client and image input server
|
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().
|
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 |
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.