#include <imageio.h>

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

typedef ImageOutput (	Creator )()

Public Member Functions
virtual	~ImageOutput ()

virtual const char *	format_name (void) const =0
	Return the name of the format implemented by this class. More...

virtual bool	copy_image (ImageInput *in)

virtual int	send_to_output (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 *	operator new (size_t size)

void	operator delete (void *ptr)

Writing pixels
Common features of all the `write` methods: The `format` parameter describes the data type of the `data[]`. The write methods automatically convert the data from the specified `format` to the actual output data type of the file (as was specified by the ImageSpec passed to `open()`). If `format` is `TypeUnknown`, then rather than converting from `format`, it will just copy pixels assumed to already be in the 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. Scanlines or tiles must be written in successive increasing coordinate order, unless the particular output file driver allows random access (indicated by `supports("random_access")`). All write functions return `true` for success, `false` for failure (after which a call to `geterror()` may retrieve a specific error message).
virtual bool	write_scanline (int y, int z, TypeDesc format, const void *data, stride_t xstride=AutoStride)

virtual bool	write_scanlines (int ybegin, int yend, int z, TypeDesc format, const void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride)

virtual bool	write_tile (int x, int y, int z, TypeDesc format, const void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride)

virtual bool	write_tiles (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, TypeDesc format, const void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride)

virtual bool	write_rectangle (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, TypeDesc format, const void *data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride)

virtual bool	write_image (TypeDesc format, const void data, stride_t xstride=AutoStride, stride_t ystride=AutoStride, stride_t zstride=AutoStride, ProgressCallback progress_callback=nullptr, void progress_callback_data=nullptr)

virtual bool	write_deep_scanlines (int ybegin, int yend, int z, const DeepData &deepdata)

virtual bool	write_deep_tiles (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, const DeepData &deepdata)

virtual bool	write_deep_image (const DeepData &deepdata)

virtual bool	set_thumbnail (const ImageBuf &thumb)

Static Public Member Functions
static void	destroy (ImageOutput *x)

Creating an ImageOutput
static unique_ptr	create (string_view filename, Filesystem::IOProxy *ioproxy=nullptr, string_view plugin_searchpath="")

static unique_ptr	create (const std::wstring &filename, Filesystem::IOProxy *ioproxy=nullptr, const std::wstring &plugin_searchpath={})

static unique_ptr	create (const std::string &filename, const std::string &plugin_searchpath)

Protected Member Functions
	ImageOutput ()

const void *	to_native_scanline (TypeDesc format, const void *data, stride_t xstride, std::vector< unsigned char > &scratch, unsigned int dither=0, int yorigin=0, int zorigin=0)

const void *	to_native_tile (TypeDesc format, const void *data, stride_t xstride, stride_t ystride, stride_t zstride, std::vector< unsigned char > &scratch, unsigned int dither=0, int xorigin=0, int yorigin=0, int zorigin=0)

const void *	to_native_rectangle (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, TypeDesc format, const void *data, stride_t xstride, stride_t ystride, stride_t zstride, std::vector< unsigned char > &scratch, unsigned int dither=0, int xorigin=0, int yorigin=0, int zorigin=0)

bool	copy_to_image_buffer (int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, TypeDesc format, const void data, stride_t xstride, stride_t ystride, stride_t zstride, void image_buffer, TypeDesc buf_format=TypeDesc::UNKNOWN)

bool	copy_tile_to_image_buffer (int x, int y, int z, TypeDesc format, const void data, stride_t xstride, stride_t ystride, stride_t zstride, void image_buffer, TypeDesc buf_format=TypeDesc::UNKNOWN)

Protected Attributes
ImageSpec	m_spec
	format spec of the currently open image More...

Opening and closing files for output
enum	OpenMode { Create, AppendSubimage, AppendMIPLevel }
	Modes passed to the `open()` call. More...

virtual int	supports (string_view feature OIIO_MAYBE_UNUSED) const

virtual bool	open (const std::string &filename, const ImageSpec &newspec, OpenMode mode=Create)=0

bool	open (const std::wstring &filename, const ImageSpec &newspec, OpenMode mode=Create)
	Open an ImageOutput using a UTF-16 encoded wstring filename. More...

virtual bool	open (const std::string &filename, int subimages OIIO_MAYBE_UNUSED, const ImageSpec *specs)

bool	open (const std::wstring &filename, int subimages OIIO_MAYBE_UNUSED, const ImageSpec *specs)
	Modes passed to the `open()` call. More...

const ImageSpec &	spec (void) const

virtual bool	close ()=0

Detailed Description

ImageOutput abstracts the writing of an image file in a file format-agnostic manner.

Users don't directly declare these. Instead, you call the create() static method, which will return a unique_ptr holding a subclass of ImageOutput that implements writing the particular format.

Definition at line 1770 of file imageio.h.

Member Typedef Documentation

typedef ImageOutput*(* ImageOutput::Creator)()

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

Definition at line 2421 of file imageio.h.

using ImageOutput::unique_ptr = std::unique_ptr<ImageOutput>

unique_ptr to an ImageOutput.

Definition at line 1773 of file imageio.h.

Member Enumeration Documentation

enum ImageOutput::OpenMode

Modes passed to the open() call.

Enumerator
Create
AppendSubimage
AppendMIPLevel

Definition at line 1967 of file imageio.h.

Constructor & Destructor Documentation

ImageOutput::ImageOutput ( )

protected

virtual ImageOutput::~ImageOutput ( )

virtual

Member Function Documentation

virtual bool ImageOutput::close ( )

pure virtual

Closes the currently open file associated with this ImageOutput and frees any memory or resources associated with it.

virtual bool ImageOutput::copy_image ( ImageInput * in )

virtual

Read the pixels of the current subimage of in, and write it as the next subimage of *this, in a way that is efficient and does not alter pixel values, if at all possible. Both in and this must be a properly-opened ImageInput and ImageOutput, respectively, and their current images must match in size and number of channels.

If a particular ImageOutput implementation does not supply a copy_image method, it will inherit the default implementation, which is to simply read scanlines or tiles from in and write them to *this. However, some file format implementations may have a special technique for directly copying raw pixel data from the input to the output, when both are the same file type and the same pixel data type. This can be more efficient than in->read_image() followed by out->write_image(), and avoids any unintended pixel alterations, especially for formats that use lossy compression.

Note: this method is NOT thread-safe, since it depends on persistent state in the ImageInput.

Parameters

in	A pointer to the open `ImageInput` to read from.

Returns: true upon success, or false upon failure.

bool ImageOutput::copy_tile_to_image_buffer	(	int	x,
		int	y,
		int	z,
		TypeDesc	format,
		const void *	data,
		stride_t	xstride,
		stride_t	ystride,
		stride_t	zstride,
		void *	image_buffer,
		TypeDesc	buf_format = `TypeDesc::UNKNOWN`
	)

protected

Helper function to copy a tile of data into the right spot in an image-sized buffer. This is really just a wrapper for copy_to_image_buffer, passing all the right parameters to copy exactly one tile.

bool ImageOutput::copy_to_image_buffer	(	int	xbegin,
		int	xend,
		int	ybegin,
		int	yend,
		int	zbegin,
		int	zend,
		TypeDesc	format,
		const void *	data,
		stride_t	xstride,
		stride_t	ystride,
		stride_t	zstride,
		void *	image_buffer,
		TypeDesc	buf_format = `TypeDesc::UNKNOWN`
	)

protected

Helper function to copy a rectangle of data into the right spot in an image-sized buffer. In addition to copying to the right place, this handles data format conversion and dither (if the spec's "oiio:dither" is nonzero, and if it's converting from a float-like type to UINT8). The buf_format describes the type of image_buffer, if it's TypeDesc::UNKNOWN it will be assumed to be spec.format.

static unique_ptr ImageOutput::create	(	string_view	filename,
		Filesystem::IOProxy *	ioproxy = `nullptr`,
		string_view	plugin_searchpath = `""`
	)

static

Create an ImageOutput that can be used to write an image file. The type of image file (and hence, the particular subclass of ImageOutput returned, and the plugin that contains its methods) is inferred from the name, if it appears to be a full filename, or it may also name the format.

Parameters

filename	The name of the file format (e.g., "openexr"), a file extension (e.g., "exr"), or a filename from which the the file format can be inferred from its extension (e.g., "hawaii.exr"). The filename is UTF-8 encoded.
plugin_searchpath	An optional colon-separated list of directories to search for OpenImageIO plugin DSO/DLL's.
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 ImageOutput 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 ImageOutput::create	(	const std::wstring &	filename,
		Filesystem::IOProxy *	ioproxy = `nullptr`,
		const std::wstring &	plugin_searchpath = `{}`
	)

inlinestatic

Create an ImageOutput using a UTF-16 encoded wstring filename and plugin searchpath.

Definition at line 1809 of file imageio.h.

static unique_ptr ImageOutput::create	(	const std::string &	filename,
		const std::string &	plugin_searchpath
	)

static

Create an ImageOutput that can be used to write an image file. The type of image file (and hence, the particular subclass of ImageOutput returned, and the plugin that contains its methods) is inferred from the name, if it appears to be a full filename, or it may also name the format.

Parameters

filename	The name of the file format (e.g., "openexr"), a file extension (e.g., "exr"), or a filename from which the the file format can be inferred from its extension (e.g., "hawaii.exr"). The filename is UTF-8 encoded.
plugin_searchpath	An optional colon-separated list of directories to search for OpenImageIO plugin DSO/DLL's.
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 ImageOutput when it exits scope or is reset. The pointer will be empty if the required writer was not able to be created.

static void ImageOutput::destroy ( ImageOutput * x )

static

template<typename... Args>

OIIO_FORMAT_DEPRECATED void ImageOutput::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 2367 of file imageio.h.

template<typename... Args>

void ImageOutput::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 2375 of file imageio.h.

template<typename... Args>

void ImageOutput::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 2383 of file imageio.h.

template<typename... Args>

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

inline

Definition at line 2392 of file imageio.h.

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

pure virtual

Return the name of the format implemented by this class.

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

Return the text of all pending error messages issued against this ImageOutput 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 ImageOutput::has_error ( ) const

Is there a pending error message waiting to be retrieved, that resulted from an ImageOutput 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.

virtual bool ImageOutput::open	(	const std::string &	filename,
		const ImageSpec &	newspec,
		OpenMode	mode = `Create`
	)

pure virtual

Open the file with given name, with resolution and other format data as given in newspec. It is legal to call open multiple times on the same file without a call to close(), if it supports multiimage and mode is AppendSubimage, or if it supports MIP-maps and mode is AppendMIPLevel – this is interpreted as appending a subimage, or a MIP level to the current subimage, respectively.

Parameters

filename	The name of the image file to open, UTF-8 encoded.
newspec	The ImageSpec describing the resolution, data types, etc.
mode	Specifies whether the purpose of the `open` is to create/truncate the file (default: `Create`), append another subimage (`AppendSubimage`), or append another MIP level (`AppendMIPLevel`).

Returns: true upon success, or false upon failure.

bool ImageOutput::open	(	const std::wstring &	filename,
		const ImageSpec &	newspec,
		OpenMode	mode = `Create`
	)

inline

Open an ImageOutput using a UTF-16 encoded wstring filename.

Definition at line 1989 of file imageio.h.

virtual bool ImageOutput::open	(	const std::string &	filename,
		int subimages	OIIO_MAYBE_UNUSED,
		const ImageSpec *	specs
	)

inlinevirtual

Open a multi-subimage file with given name and specifications for each of the subimages. Upon success, the first subimage will be open and ready for transmission of pixels. Subsequent subimages will be denoted with the usual call of open(name,spec,AppendSubimage) (and MIP levels by open(name,spec,AppendMIPLevel)).

The purpose of this call is to accommodate format-writing libraries that must know the number and specifications of the subimages upon first opening the file; such formats can be detected by:: supports("multiimage") && !supports("appendsubimage") The individual specs passed to the appending open() calls for subsequent subimages must match the ones originally passed.

Parameters

filename	The name of the image file to open, UTF-8 encoded.
subimages	The number of subimages (and therefore the length of the `specs[]` array.
specs[]	Pointer to an array of `ImageSpec` objects describing each of the expected subimages.

Returns: true upon success, or false upon failure.

Definition at line 2016 of file imageio.h.

bool ImageOutput::open	(	const std::wstring &	filename,
		int subimages	OIIO_MAYBE_UNUSED,
		const ImageSpec *	specs
	)

inline

Modes passed to the open() call.

Definition at line 2024 of file imageio.h.

void ImageOutput::operator delete ( void * ptr )

void* ImageOutput::operator new ( size_t size )

int ImageOutput::send_to_client	(	const char *	format,
			...
	)

virtual int ImageOutput::send_to_output	(	const char *	format,
			...
	)

virtual

virtual bool ImageOutput::set_ioproxy ( Filesystem::IOProxy * ioproxy )

inlinevirtual

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

Returns: true for success, false for failure.

Definition at line 2338 of file imageio.h.

virtual bool ImageOutput::set_thumbnail ( const ImageBuf & thumb )

inlinevirtual

Specify a reduced-resolution ("thumbnail") version of the image. Note that many image formats may require the thumbnail to be specified prior to writing the pixels.

Parameters

thumb A reference to an ImageBuf containing the thumbnail image.

Returns: true upon success, false if it was not possible to write the thumbnail, or if this file format (or writer) does not support thumbnails.

Note: This method was added to OpenImageIO 2.3.

Definition at line 2301 of file imageio.h.

const ImageSpec& ImageOutput::spec ( void ) const

inline

Return a reference to the image format specification of the current subimage. Note that the contents of the spec are invalid before open() or after close().

Definition at line 2034 of file imageio.h.

virtual int ImageOutput::supports ( string_view feature OIIO_MAYBE_UNUSED ) const

inlinevirtual

Given the name of a "feature", return whether this ImageOutput 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 ImageOutput implementations are expected to recognize include:

"tiles" : Is this format writer able to write tiled images?
"rectangles" : Does this writer accept arbitrary rectangular pixel regions (via write_rectangle())? Returning 0 indicates that pixels must be transmitted via write_scanline() (if scanline-oriented) or write_tile() (if tile-oriented, and only if supports("tiles") returns true).
"random_access" : May tiles or scanlines be written in any order (0 indicates that they must be in successive order)?
"multiimage" : Does this format support multiple subimages within a file?
"appendsubimage" : Does this format support multiple subimages that can be successively appended at will via open(name,spec,AppendSubimage)? A value of 0 means that the format requires pre-declaring the number and specifications of the subimages when the file is first opened, with open(name,subimages,specs).
"mipmap" : Does this format support multiple resolutions for an image/subimage?
"volumes" : Does this format support "3D" pixel arrays (a.k.a. volume images)?
"alpha" : Can this format support an alpha channel?
"nchannels" : Can this format support arbitrary number of channels (beyond RGBA)?
"rewrite" : May the same scanline or tile be sent more than once? Generally, this is true for plugins that implement interactive display, rather than a saved image file.
"empty" : Does this plugin support passing a NULL data pointer to the various write routines to indicate that the entire data block is composed of pixels with value zero? Plugins that support this achieve a speedup when passing blank scanlines or tiles (since no actual data needs to be transmitted or converted).
"channelformats" : Does this format writer support per-channel data formats, respecting the ImageSpec's channelformats field? If not, it only accepts a single data format for all channels and will ignore the channelformats field of the spec.
"displaywindow" : Does the format support display ("full") windows distinct from the pixel data window?
"origin" : Does the image format support specifying a pixel window origin (i.e., nonzero ImageSpec x, y, z)?
"negativeorigin" : Does the image format allow data and display window origins (i.e., ImageSpec x, y, z, full_x, full_y, full_z) to have negative values?
"deepdata" : Does the image format allow "deep" data consisting of multiple values per pixel (and potentially a differing number of values from pixel to pixel)?
"arbitrary_metadata" : Does the image file format allow metadata with arbitrary names (and either arbitrary, or a reasonable set of, data types)? (Versus the file format supporting only a fixed list of specific metadata names/values.)
"exif" Does the image file format support Exif camera data (either specifically, or via arbitrary named metadata)?
"iptc" Does the image file format support IPTC data (either specifically, or via arbitrary named metadata)?
"ioproxy" Does the image file format support writing to an IOProxy?
"procedural" : Is this a purely procedural output that doesn't write an actual file?
"thumbnail" : Does this format writer support adding a reduced resolution copy of the image via the thumbnail() method?
"thumbnail_after_write" : Does this format writer support calling thumbnail() after the scanlines or tiles have been specified? (Supporting "thumbnail" but not "thumbnail_after_write" means that any thumbnail must be supplied immediately after open(), prior to any of the write_*() calls.)

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

void ImageOutput::threads ( int n )

Set the threading policy for this ImageOutput, controlling the maximum amount of parallelizing thread "fan-out" that might occur during large write 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 ImageOutput::threads ( ) const

Retrieve the current thread-spawning policy.

See Also: threads(int)

const void* ImageOutput::to_native_rectangle	(	int	xbegin,
		int	xend,
		int	ybegin,
		int	yend,
		int	zbegin,
		int	zend,
		TypeDesc	format,
		const void *	data,
		stride_t	xstride,
		stride_t	ystride,
		stride_t	zstride,
		std::vector< unsigned char > &	scratch,
		unsigned int	dither = `0`,
		int	xorigin = `0`,
		int	yorigin = `0`,
		int	zorigin = `0`
	)

protected

const void* ImageOutput::to_native_scanline	(	TypeDesc	format,
		const void *	data,
		stride_t	xstride,
		std::vector< unsigned char > &	scratch,
		unsigned int	dither = `0`,
		int	yorigin = `0`,
		int	zorigin = `0`
	)

protected

Helper routines used by write_* implementations: convert data (in the given format and stride) to the "native" format of the file (described by the 'spec' member variable), in contiguous order. This requires a scratch space to be passed in so that there are no memory leaks. Returns a pointer to the native data, which may be the original data if it was already in native format and contiguous, or it may point to the scratch space if it needed to make a copy or do conversions. For float->uint8 conversions only, if dither is nonzero, random dither will be added to reduce quantization banding artifacts; in this case, the specific nonzero dither value is used as a seed for the hash function that produces the per-pixel dither amounts, and the optional [xyz]origin parameters help it to align the pixels to the right position in the dither pattern.

const void* ImageOutput::to_native_tile	(	TypeDesc	format,
		const void *	data,
		stride_t	xstride,
		stride_t	ystride,
		stride_t	zstride,
		std::vector< unsigned char > &	scratch,
		unsigned int	dither = `0`,
		int	xorigin = `0`,
		int	yorigin = `0`,
		int	zorigin = `0`
	)

protected

virtual bool ImageOutput::write_deep_image ( const DeepData & deepdata )

virtual

Write the entire deep image described by deepdata. Depending on the spec, this will write either all tiles or all scanlines.

Parameters

deepdata A DeepData object with the data for the image.

Returns: true upon success, or false upon failure.

virtual bool ImageOutput::write_deep_scanlines	(	int	ybegin,
		int	yend,
		int	z,
		const DeepData &	deepdata
	)

virtual

Write deep scanlines containing pixels (*,y,z), for all y in the range [ybegin,yend), to a deep file. This will fail if it is not a deep file.

Parameters

ybegin/yend	The y range of the scanlines being passed.
z	The z coordinate of the scanline.
deepdata	A `DeepData` object with the data for these scanlines.

Returns: true upon success, or false upon failure.

virtual bool ImageOutput::write_deep_tiles	(	int	xbegin,
		int	xend,
		int	ybegin,
		int	yend,
		int	zbegin,
		int	zend,
		const DeepData &	deepdata
	)

virtual

Write the block of deep tiles that include all pixels in the range

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

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.

Parameters

xbegin/xend	The x range of the pixels covered by the group of tiles passed.
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).
deepdata	A `DeepData` object with the data for the tiles.

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.

virtual bool ImageOutput::write_image	(	TypeDesc	format,
		const void *	data,
		stride_t	xstride = `AutoStride`,
		stride_t	ystride = `AutoStride`,
		stride_t	zstride = `AutoStride`,
		ProgressCallback	progress_callback = `nullptr`,
		void *	progress_callback_data = `nullptr`
	)

virtual

Write the entire image of spec.width x spec.height x spec.depth pixels, from a buffer with the given strides and in the desired format.

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

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

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 ImageOutput::write_rectangle	(	int	xbegin,
		int	xend,
		int	ybegin,
		int	yend,
		int	zbegin,
		int	zend,
		TypeDesc	format,
		const void *	data,
		stride_t	xstride = `AutoStride`,
		stride_t	ystride = `AutoStride`,
		stride_t	zstride = `AutoStride`
	)

virtual

Write a rectangle of pixels given by the range

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

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)

Parameters

xbegin/xend	The x range of the pixels being passed.
ybegin/yend	The y range of the pixels being passed.
zbegin/zend	The z range of the pixels being passed (for a 2D image, zbegin=0 and zend=1).
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 for a format plugin that does not return true for supports("rectangles").

virtual bool ImageOutput::write_scanline	(	int	y,
		int	z,
		TypeDesc	format,
		const void *	data,
		stride_t	xstride = `AutoStride`
	)

virtual

Write the full scanline that includes pixels (*,y,z). For 2D non-volume images, z should be 0. The xstride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply "contiguous" data.

Parameters

y/z	The y & z coordinates of the scanline.
format	A TypeDesc describing the type of `data`.
data	Pointer to the pixel data.
xstride	The distance in bytes between successive pixels in `data` (or `AutoStride`).

Returns: true upon success, or false upon failure.

virtual bool ImageOutput::write_scanlines	(	int	ybegin,
		int	yend,
		int	z,
		TypeDesc	format,
		const void *	data,
		stride_t	xstride = `AutoStride`,
		stride_t	ystride = `AutoStride`
	)

virtual

Write multiple scanlines that include pixels (*,y,z) for all ybegin <= y < yend, from data. This is analogous to write_scanline(y,z,format,data,xstride) repeatedly for each of the scanlines in turn (the advantage, though, is that some image file types may be able to write multiple scanlines more efficiently or in parallel, than it could with one scanline at a time).

Parameters

ybegin/yend	The y range of the scanlines being passed.
z	The z coordinate of the scanline.
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.

virtual bool ImageOutput::write_tile	(	int	x,
		int	y,
		int	z,
		TypeDesc	format,
		const void *	data,
		stride_t	xstride = `AutoStride`,
		stride_t	ystride = `AutoStride`,
		stride_t	zstride = `AutoStride`
	)

virtual

Write the tile with (x,y,z) as the upper left corner. The three stride values give the distance (in bytes) between successive pixels, scanlines, and volumetric slices, respectively. 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

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.

virtual bool ImageOutput::write_tiles	(	int	xbegin,
		int	xend,
		int	ybegin,
		int	yend,
		int	zbegin,
		int	zend,
		TypeDesc	format,
		const void *	data,
		stride_t	xstride = `AutoStride`,
		stride_t	ystride = `AutoStride`,
		stride_t	zstride = `AutoStride`
	)

virtual

Write the block of multiple tiles that include all pixels in

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

This is analogous to calling write_tile(x,y,z,...) for each tile in turn (but for some file formats, passing multiple tiles may allow it to write 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)

Parameters

xbegin/xend	The x range of the pixels covered by the group of tiles passed.
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).
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.

Member Data Documentation

ImageSpec ImageOutput::m_spec

protected

format spec of the currently open image

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

Opening and closing files for output

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation