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

#include <imageio.h>

Public Types

enum  OpenMode { Create, AppendSubimage, AppendMIPLevel }
 
using unique_ptr = std::unique_ptr< ImageOutput >
 unique_ptr to an ImageOutput, with custom deleter. More...
 
typedef ImageOutput *(* Creator )()
 Call signature of a function that creates and returns an ImageOutput*. More...
 

Public Member Functions

 ImageOutput ()
 
virtual ~ImageOutput ()
 
virtual const char * format_name (void) const =0
 
virtual int supports (string_view feature) 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. More...
 
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
 
template<typename... Args>
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 fmterror (const char *fmt, const Args &...args) const
 
void threads (int n)
 
int threads () const
 Retrieve the current thread-spawning policy. More...
 
voidoperator new (size_t size)
 
void operator delete (void *ptr)
 

Static Public Member Functions

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

Protected Member Functions

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

Detailed Description

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

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

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

unique_ptr to an ImageOutput, with custom deleter.

Definition at line 1180 of file imageio.h.

Member Enumeration Documentation

Enumerator
Create 
AppendSubimage 
AppendMIPLevel 

Definition at line 1262 of file imageio.h.

Constructor & Destructor Documentation

ImageOutput::ImageOutput ( )
virtual ImageOutput::~ImageOutput ( )
virtual

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.

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 ( 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. If the writer could be created, a unique_ptr to it will be returned, otherwise an empty pointer will be returned and an appropriate error message will be set that can be retrieved with OIIO::geterror().

static void ImageOutput::destroy ( ImageOutput x)
static
template<typename... Args>
void ImageOutput::error ( const char *  fmt,
const Args &...  args 
) const
inline

Error reporting for the plugin implementation: call this with Strutil::format-like arguments. Use with caution! Some day this will change to be fmt-like rather than printf-like.

Definition at line 1478 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.

Definition at line 1485 of file imageio.h.

template<typename... Args>
void ImageOutput::fmterror ( const char *  fmt,
const Args &...  args 
) const
inline

Error reporting for the plugin implementation: call this with fmt::format-like arguments.

Definition at line 1492 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 ( 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.

Definition at line 1467 of file imageio.h.

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.

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

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

Definition at line 1300 of file imageio.h.

virtual int ImageOutput::supports ( string_view  feature) 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 nonzero 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 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? "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 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 "arbitrary_metadata" Does this format allow metadata with arbitrary names and types? "exif" Can this format store Exif camera data? "iptc" Can this format store IPTC data? "ioproxy" Does this format writer support IOProxy?

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.

Definition at line 1260 of file imageio.h.

void ImageOutput::threads ( int  n)
inline

Set the current thread-spawning policy: the maximum number of threads that may be spawned by ImageOutput internals. A value of 1 means all work will be done by the calling thread; 0 means to use the global OIIO::attribute("threads") value.

Definition at line 1500 of file imageio.h.

int ImageOutput::threads ( ) const
inline

Retrieve the current thread-spawning policy.

Definition at line 1503 of file imageio.h.

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 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 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 == spec.nchannels*format.size() ystride == xstride * (xend-xbegin) zstride == ystride * (yend-ybegin) 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 in the shape of a full tile, 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. 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 == spec.nchannels*format.size() ystride == xstride * (xend-xbegin) zstride == ystride * (yend-ybegin)

Member Data Documentation

ImageSpec ImageOutput::m_spec
protected

format spec of the currently open image

Definition at line 1570 of file imageio.h.


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