#include <imageio.h>

Public Types
using	unique_ptr = std::unique_ptr< ImageInput >
	unique_ptr to an ImageInput More...

typedef std::lock_guard< const ImageInput & >	lock_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

bool	valid_file (const std::wstring &filename) const
	Check valid vile using a UTF-16 encoded wstring filename. More...

virtual bool	open (const std::string &name, ImageSpec &newspec)=0

bool	open (const std::wstring &name, ImageSpec &newspec)
	Open the ImageInput using a UTF-16 encoded wstring filename. More...

virtual bool	open (const std::string &name, ImageSpec &newspec, const ImageSpec &config OIIO_MAYBE_UNUSED)

bool	open (const std::wstring &name, ImageSpec &newspec, const ImageSpec &config OIIO_MAYBE_UNUSED)
	Open the ImageInput using a UTF-16 encoded wstring filename. More...

virtual const ImageSpec &	spec (void) const

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

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

virtual bool	get_thumbnail (ImageBuf &thumb, int subimage)

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)

bool	has_error () const

std::string	geterror (bool clear=true) const

template<typename... Args>
OIIO_FORMAT_DEPRECATED 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 () const

void	unlock () const

bool	try_lock () const

void *	operator 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 `channelformats` 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	open (const std::wstring &filename, const ImageSpec config=nullptr, Filesystem::IOProxy ioproxy=nullptr)
	Create and open an ImageInput using a UTF-16 encoded wstring filename. More...

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::wstring &filename, bool do_open=false, const ImageSpec config=nullptr, Filesystem::IOProxy ioproxy=nullptr, string_view plugin_searchpath="")
	Create an ImageInput using a UTF-16 encoded wstring filename. More...

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
ImageSpec	m_spec

Detailed Description

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

Definition at line 824 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 1739 of file imageio.h.

typedef std::lock_guard<const ImageInput&> ImageInput::lock_guard

The presence of lock() and unlock() establish an ImageInput itself as having the BasicLockable concept and therefore can be used by std::lock_guard.

Definition at line 1730 of file imageio.h.

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

unique_ptr to an ImageInput

Definition at line 827 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

filename	The name of an image file, or a file extension, or the name of a file format. The filename is UTF-8 encoded.
do_open	If `true`, not only create but also open the file.
config	Optional pointer to an ImageSpec whose metadata contains "configuration hints" for the ImageInput implementation.
ioproxy	Optional 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_searchpath	An 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::wstring &	filename,
		bool	do_open = `false`,
		const ImageSpec *	config = `nullptr`,
		Filesystem::IOProxy *	ioproxy = `nullptr`,
		string_view	plugin_searchpath = `""`
	)

inlinestatic

Create an ImageInput using a UTF-16 encoded wstring filename.

Definition at line 939 of file imageio.h.

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

filename	The name of the file to open, UTF-8 encoded.
config	Optional pointer to an ImageSpec whose metadata contains "configuration hints."
ioproxy	Optional 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

filename	The name of the file to open, UTF-8 encoded.
config	Optional pointer to an ImageSpec whose metadata contains "configuration hints."
ioproxy	Optional 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 1142 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 1137 of file imageio.h.

static void ImageInput::destroy ( ImageInput * x )

static

template<typename... Args>

OIIO_FORMAT_DEPRECATED void ImageInput::error	(	const char *	fmt,
		const Args &...	args
	)		const

inline

Error reporting for the plugin implementation: call this with Strutil::format-like arguments. It is not necessary to have the error message contain a trailing newline. Use with caution! Some day this will change to be fmt-like rather than printf-like.

Definition at line 1674 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. It is not necessary to have the error message contain a trailing newline.

Definition at line 1682 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 std::format-like arguments. It is not necessary to have the error message contain a trailing newline.

Definition at line 1690 of file imageio.h.

template<typename... Args>

void ImageInput::fmterror	(	const char *	fmt,
		const Args &...	args
	)		const

inline

Definition at line 1699 of file imageio.h.

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

pure virtual

Return the name of the format implemented by this class.

virtual bool ImageInput::get_thumbnail	(	ImageBuf &	thumb,
		int	subimage
	)

inlinevirtual

Retrieve a reduced-resolution ("thumbnail") version of the given subimage. It is guaranteed to be thread-safe.

Parameters

thumb	A reference to an `ImageBuf` which will be overwritten with the thumbnail image.
subimage	The index of the subimage in the file whose thumbnail is to be retrieved.

Returns: true upon success, false if no thumbnail was available, or if this file format (or reader) does not support thumbnails.

Note: This method was added to OpenImageIO 2.3.

Definition at line 1121 of file imageio.h.

std::string ImageInput::geterror ( bool clear = true ) const

Return the text of all pending error messages issued against this ImageInput by the calling thread, and clear the pending error message unless clear is false. If no error message is pending, it will return an empty string.

Note that any error() calls issued are thread-specific, and the geterror()/has_error() are expected to be called by the same thread that called whichever API function encountered an error.

bool ImageInput::has_error ( ) const

Is there a pending error message waiting to be retrieved, that resulted from an ImageInput API call made by the this thread?

Note that any error() calls issued are thread-specific, and the geterror()/has_error() are expected to be called by the same thread that called whichever API function encountered an error.

void ImageInput::lock ( ) const

There is a (hidden) internal recursive mutex to each ImageInput that can be used by the II to enforce thread safety. This is exposed via the obvious lock()/unlock()/try_lock() semantics.

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

filename	The name of the file to open, UTF-8 encoded.
config	Optional pointer to an ImageSpec whose metadata contains "configuration hints."
ioproxy	Optional 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::open	(	const std::wstring &	filename,
		const ImageSpec *	config = `nullptr`,
		Filesystem::IOProxy *	ioproxy = `nullptr`
	)

inlinestatic

Create and open an ImageInput using a UTF-16 encoded wstring filename.

Definition at line 872 of file imageio.h.

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

name	Filename to open, UTF-8 encoded.
newspec	Reference 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.

bool ImageInput::open	(	const std::wstring &	name,
		ImageSpec &	newspec
	)

inline

Open the ImageInput using a UTF-16 encoded wstring filename.

Definition at line 1045 of file imageio.h.

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

name	Filename to open, UTF-8 encoded.
newspec	Reference to an ImageSpec in which to deposit a full description of the contents of the first subimage of the file.
config	An ImageSpec whose metadata contains "configuration hints" for the ImageInput implementation.

Returns: true if the file was found and opened successfully.

Definition at line 1069 of file imageio.h.

bool ImageInput::open	(	const std::wstring &	name,
		ImageSpec &	newspec,
		const ImageSpec &config	OIIO_MAYBE_UNUSED
	)

inline

Open the ImageInput using a UTF-16 encoded wstring filename.

Definition at line 1074 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

subimage	The subimage to read from (starting with 0).
miplevel	The MIP level to read (0 is the highest resolution level).
chbegin/chend	The channel range to read.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data.
xstride/ystride/zstride	The distance in bytes between successive pixels, scanlines, and image planes (or `AutoStride`).
progress_callback/progress_callback_data	Optional 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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The 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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The 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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The distance in bytes between successive pixels in `data` (or `AutoStride`).

Returns: true upon success, or false upon failure.

Definition at line 1471 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

subimage	The subimage to read from (starting with 0).
miplevel	The MIP level to read (0 is the highest resolution level).
deepdata	A `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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The distance in bytes between successive pixels in `data` (or `AutoStride`).

Returns: true upon success, or false upon failure.

Definition at line 1549 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

subimage	The subimage to read from (starting with 0).
miplevel	The MIP level to read (0 is the highest resolution level).
chbegin/chend	The channel range to read.
ybegin/yend	The y range of the scanlines being passed.
z	The z coordinate of the scanline.
deepdata	A `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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The distance in bytes between successive pixels in `data` (or `AutoStride`).

Returns: true upon success, or false upon failure.

Definition at line 1536 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

subimage	The subimage to read from (starting with 0).
miplevel	The MIP level to read (0 is the highest resolution level).
xbegin/xend	The x range of the pixels covered by the group of tiles being read.
ybegin/yend	The y range of the pixels covered by the tiles.
zbegin/zend	The z range of the pixels covered by the tiles (for a 2D image, zbegin=0 and zend=1).
chbegin/chend	The channel range to read.
deepdata	A `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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The distance in bytes between successive pixels in `data` (or `AutoStride`).

Returns: true upon success, or false upon failure.

Definition at line 1542 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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The 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 1246 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

subimage	The subimage to read from (starting with 0).
miplevel	The MIP level to read (0 is the highest resolution level).
ybegin/yend	The y range of the scanlines being passed.
z	The z coordinate of the scanline.
chbegin/chend	The channel range to read.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data.
xstride/ystride	The 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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The 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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The 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/z	The upper left coordinate of the tile being passed.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data.
xstride/ystride/zstride	The 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 1339 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

subimage	The subimage to read from (starting with 0).
miplevel	The MIP level to read (0 is the highest resolution level).
xbegin/xend	The x range of the pixels covered by the group of tiles being read.
ybegin/yend	The y range of the pixels covered by the tiles.
zbegin/zend	The z range of the pixels covered by the tiles (for a 2D image, zbegin=0 and zend=1).
chbegin/chend	The channel range to read.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data.
xstride/ystride/zstride	The 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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The 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/z	The y & z coordinates of the scanline. For 2D images, z should be 0.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data buffer.
xstride	The 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 1157 of file imageio.h.

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

inline

Definition at line 1165 of file imageio.h.

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

inline

Definition at line 1175 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 1645 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 1085 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?
"ioproxy" : Does this format reader support reading from an IOProxy?
"iptc" : Can this format store IPTC data?
"procedural" : Can this format create images without reading from a disk file?
"thumbnail" : Does this format reader support retrieving a reduced resolution copy of the image via the thumbnail() method?

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

void ImageInput::threads ( int n )

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.

int ImageInput::threads ( ) const

Retrieve the current thread-spawning policy.

See Also: threads(int)

bool ImageInput::try_lock ( ) const

void ImageInput::unlock ( ) const

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. The filename is UTF-8 encoded.

Returns: true upon success, or false upon failure.

bool ImageInput::valid_file ( const std::wstring & filename ) const

inline

Check valid vile using a UTF-16 encoded wstring filename.

Definition at line 1021 of file imageio.h.

Member Data Documentation

ImageSpec ImageInput::m_spec

protected

Definition at line 1742 of file imageio.h.

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

OpenImageIO/imageio.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation