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

#include <imageio.h>

Public Types

enum  OpenMode { Create, AppendSubimage, AppendMIPLevel }
 

Public Member Functions

virtual const char * format_name (void) const =0
 
virtual bool supports (const std::string &) const
 
virtual bool open (const std::string &name, const ImageSpec &newspec, OpenMode mode=Create)=0
 
virtual bool open (const std::string &name, int subimages, const ImageSpec *specs)
 
const ImageSpecspec (void) const
 
virtual bool close ()=0
 
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=NULL, void *progress_callback_data=NULL)
 
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)
 Write the entire deep image denoted by data.
 
virtual bool copy_image (ImageInput *in)
 
virtual int send_to_output (const char *format,...)
 
int send_to_client (const char *format,...)
 
std::string geterror () const
 

Static Public Member Functions

static ImageOutputcreate (const std::string &filename, const std::string &plugin_searchpath="")
 

Protected Member Functions

 TINYFORMAT_WRAP_FORMAT (void, error, const, std::ostringstream msg;, msg, append_error(msg.str());) const void *to_native_scanline(TypeDesc format
 
const void * to_native_tile (TypeDesc format, const void *data, stride_t xstride, stride_t ystride, stride_t zstride, std::vector< unsigned char > &scratch)
 
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)
 

Protected Attributes

const void * data
 
const void stride_t xstride
 
const void stride_t
std::vector< unsigned char > & 
scratch
 
ImageSpec m_spec
 format spec of the currently open image
 

Detailed Description

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

Member Function Documentation

virtual bool ImageOutput::close ( )
pure virtual

Close an image that we are totally done with. This should leave the plugin in a state where it could open a new file safely, without having to destroy the writer.

virtual bool ImageOutput::copy_image ( ImageInput in)
virtual

Read 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. Return true if it works ok, false if for some reason the operation wasn't possible.

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 ImageIO implementations may have a special technique for directly copying raw pixel data from the input to the output, when both input and output are the SAME file type and the same data format. 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.

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

Create an ImageOutput that will write to a file, with the format inferred from the extension of the name. The plugin_searchpath parameter is a colon-separated list of directories to search for ImageIO plugin DSO/DLL's. This just creates the ImageOutput, it does not open the file.

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

Return the name of the format implemented by this class.

std::string ImageOutput::geterror ( void  ) const
inline

If any of the API routines returned false indicating an error, this routine will return the error string (and clear any error flags). If no error has occurred since the last time geterror() was called, it will return an empty string.

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

Open the file with given name, with resolution and other format data as given in newspec. Open returns true for success, false for failure. Note that 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.

virtual bool ImageOutput::open ( const std::string &  name,
int  subimages,
const ImageSpec specs 
)
inlinevirtual

Open the file with given name, expecting to have a given total number of subimages, described by specs[0..subimages-1]. Return true for success, false for failure. 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 fmust 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.

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

General message passing between client and image output server

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

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

Given the name of a 'feature', return whether this ImageOutput supports output of images with the given properties. Feature names that ImageIO plugins are expected to recognize include: "tiles" Is this format able to write tiled images? "rectangles" Does this plugin accept arbitrary rectangular pixel regions, not necessarily aligned to scanlines or tiles? "random_access" May tiles or scanlines be written in any order (false indicates that they MUST be in successive order). "multiimage" Does this format support multiple subimages within a file? "appendsubimage" Does this format support adding subimages one at a time through open(name,spec,AppendSubimage)? If not, then open(name,subimages,specs) must be used instead. "mipmap" Does this format support multiple resolutions for an image/subimage? "volumes" Does this format support "3D" pixel arrays? "rewrite" May the same scanline or tile be sent more than once? (Generally, this will be true for plugins that implement interactive display.) "empty" Does this plugin support passing a NULL data pointer to write_scanline or write_tile to indicate that the entire data block is zero? "channelformats" Does the plugin/format support per-channel data formats? "displaywindow" Does the format support display ("full") windows distinct from the pixel data window? "origin" Does the format support a nonzero x,y,z origin of the pixel data window? "negativeorigin" Does the format support negative x,y,z and full_{x,y,z} origin values? "deepdata" Deep (multi-sample per pixel) data

Note that main advantage of this approach, versus having separate individual supports_foo() methods, is that this allows future expansion of the set of possible queries without changing the API, adding new entry points, or breaking linkage compatibility.

ImageOutput::TINYFORMAT_WRAP_FORMAT ( void  ,
error  ,
const  ,
std::ostringstream msg;  ,
msg  ,
append_error(msg.str());   
) const
protected

Error reporting for the plugin implementation: call this with printf-like arguments. Note however that this is fully typesafe! void error (const char format, ...) 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.

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

Write the entire deep image denoted by data.

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 [ybegin,yend), to a deep file.

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

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 = NULL,
void *  progress_callback_data = NULL 
)
virtual

Write the entire image of spec.width x spec.height x spec.depth pixels, with the given strides and in the desired format. Strides set to AutoStride imply 'contiguous' data, i.e., xstride == spec.nchannels*format.size() ystride == xstride*spec.width zstride == ystride*spec.height Depending on spec, write either all tiles or all scanlines. Assume that data points to a layout in row-major order. If format is TypeDesc::UNKNOWN, then rather than converting from format, it will just copy pixels in the file's native data layout (including, possibly, per-channel data formats). Because this may be an expensive operation, a progress callback may be passed. Periodically, it will be called as follows: progress_callback (progress_callback_data, float done) where 'done' gives the portion of the image

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 three stride values give the distance (in bytes) between successive pixels, scanlines, and volumetric slices, respectively. Strides set to AutoStride imply 'contiguous' data, i.e., xstride == spec.nchannels*format.size() ystride == xstride * (xmax-xmin+1) zstride == ystride * (ymax-ymin+1) The data are automatically converted from 'format' to the actual output format (as specified to open()) by this method. If format is TypeDesc::UNKNOWN, it will just copy pixels assuming they are already in the file's native data layout (including, possibly, per-channel data formats).

Return true for success, false for failure. It is a failure to call write_rectangle 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 a full scanline that includes pixels (*,y,z). (z is ignored for 2D non-volume images.) The stride value gives the distance between successive pixels (in bytes). Strides set to AutoStride imply 'contiguous' data, i.e., xstride == spec.nchannels*format.size() The data are automatically converted from 'format' to the actual output format (as specified to open()) by this method. If format is TypeDesc::UNKNOWN, then rather than converting from format, it will just copy pixels in the file's native data layout (including, possibly, per-channel data formats). Return true for success, false for failure. It is a failure to call write_scanline with an out-of-order scanline if this format driver does not support random access.

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 except that it may be used to write more than one scanline at a time (which, for some formats, may be able to be done much more efficiently or in parallel).

virtual bool 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. (z is ignored for 2D non-volume images.) The three stride values give the distance (in bytes) between successive pixels, scanlines, and volumetric slices, respectively. Strides set to AutoStride imply 'contiguous' data, i.e., xstride == spec.nchannels*format.size() ystride == xstride*spec.tile_width zstride == ystride*spec.tile_height The data are automatically converted from 'format' to the actual output format (as specified to open()) by this method. If format is TypeDesc::UNKNOWN, then rather than converting from format, it will just copy pixels in the file's native data layout (including, possibly, per-channel data formats). Return true for success, false for failure. It is a failure to call write_tile with an out-of-order tile if this format driver does not support random access.

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 write_tile except that it may be used to write more than one tile at a time (which, for some formats, may be able to be done much more efficiently or in parallel). The begin/end pairs must correctly delineate tile boundaries, with the exception that it may also be the end of the image data if the image resolution is not a whole multiple of the tile size.

Member Data Documentation

ImageSpec ImageOutput::m_spec
protected

format spec of the currently open image


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