HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImageOutput Class Referenceabstract

#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
 
voidoperator 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 voidto_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 voidto_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 voidto_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 ImageSpecspec (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

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
inA 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
filenameThe 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_searchpathAn optional colon-separated list of directories to search for OpenImageIO plugin DSO/DLL's.
ioproxyOptional pointer to an IOProxy to use (not supported by all formats, see supports("ioproxy")). The caller retains ownership of the proxy.
Returns
A unique_ptr that will close and free the 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
filenameThe 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_searchpathAn optional colon-separated list of directories to search for OpenImageIO plugin DSO/DLL's.
ioproxyOptional pointer to an IOProxy to use (not supported by all formats, see supports("ioproxy")). The caller retains ownership of the proxy.
Returns
A unique_ptr that will close and free the 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
filenameThe name of the image file to open, UTF-8 encoded.
newspecThe ImageSpec describing the resolution, data types, etc.
modeSpecifies 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
filenameThe name of the image file to open, UTF-8 encoded.
subimagesThe 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
thumbA 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
deepdataA 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/yendThe y range of the scanlines being passed.
zThe z coordinate of the scanline.
deepdataA 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/xendThe x range of the pixels covered by the group of tiles passed.
ybegin/yendThe y range of the pixels covered by the tiles.
zbegin/zendThe z range of the pixels covered by the tiles (for a 2D image, zbegin=0 and zend=1).
deepdataA 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
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystride/zstrideThe distance in bytes between successive pixels, scanlines, and image planes (or AutoStride).
progress_callback/progress_callback_dataOptional progress callback.
Returns
true upon success, or false upon failure.
virtual bool 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/xendThe x range of the pixels being passed.
ybegin/yendThe y range of the pixels being passed.
zbegin/zendThe z range of the pixels being passed (for a 2D image, zbegin=0 and zend=1).
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystride/zstrideThe distance in bytes between successive pixels, scanlines, and image planes (or AutoStride).
Returns
true upon success, or false upon failure.
Note
The call will fail 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/zThe y & z coordinates of the scanline.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstrideThe 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/yendThe y range of the scanlines being passed.
zThe z coordinate of the scanline.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystrideThe distance in bytes between successive pixels and scanlines (or AutoStride).
Returns
true upon success, or false upon failure.
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/zThe upper left coordinate of the tile being passed.
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystride/zstrideThe distance in bytes between successive pixels, scanlines, and image planes (or AutoStride to indicate a "contiguous" single tile).
Returns
true upon success, or false upon failure.
Note
This call will fail if the image is not tiled, or if (x,y,z) is not the upper left corner coordinates of a tile.
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/xendThe x range of the pixels covered by the group of tiles passed.
ybegin/yendThe y range of the pixels covered by the tiles.
zbegin/zendThe z range of the pixels covered by the tiles (for a 2D image, zbegin=0 and zend=1).
formatA TypeDesc describing the type of data.
dataPointer to the pixel data.
xstride/ystride/zstrideThe distance in bytes between successive pixels, scanlines, and image planes (or AutoStride).
Returns
true upon success, or false upon failure.
Note
The call will fail if the image is not tiled, or if the pixel ranges do not fall along tile (or image) boundaries, or if it is not a valid tile range.

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: