OpenImageIO::ImageOutput Class Reference

#include <imageio.h>

List of all members.

Public Member Functions

virtual const char * format_name (void) const =0
virtual bool supports (const std::string &feature) const =0
virtual bool open (const std::string &name, const ImageSpec &newspec, bool append=false)=0
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_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_rectangle (int xmin, int xmax, int ymin, int ymax, int zmin, int zmax, 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 copy_image (ImageInput *in)
virtual int send_to_output (const char *format,...)
int send_to_client (const char *format,...)
std::string geterror () const
std::string error_message () const

Static Public Member Functions

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

Protected Member Functions

void error (const char *format,...) OPENIMAGEIO_PRINTF_ARGS(2
void const void * to_native_scanline (TypeDesc format, const void *data, stride_t xstride, std::vector< unsigned char > &scratch)
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 xmin, int xmax, int ymin, int ymax, int zmin, int zmax, TypeDesc format, const void *data, stride_t xstride, stride_t ystride, stride_t zstride, std::vector< unsigned char > &scratch)

Protected Attributes

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 OpenImageIO::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 OpenImageIO::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* OpenImageIO::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.

void OpenImageIO::ImageOutput::error ( const char *  format,
  ... 
) [protected]

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

std::string OpenImageIO::ImageOutput::error_message (  )  const [inline]

Deprecated

virtual const char* OpenImageIO::ImageOutput::format_name ( void   )  const [pure virtual]

Return the name of the format implemented by this class.

std::string OpenImageIO::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 OpenImageIO::ImageOutput::open ( const std::string &  name,
const ImageSpec newspec,
bool  append = false 
) [pure virtual]

Open 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 the append flag is true -- this is interpreted as appending images (such as for MIP-maps).

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

General message passing between client and image output server

const ImageSpec& OpenImageIO::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 OpenImageIO::ImageOutput::supports ( const std::string &  feature  )  const [pure virtual]

Given the name of a 'feature', return whether this ImageIO 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 images within a file? "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?

Note that the earlier incarnation of ImageIO that shipped with NVIDIA's Gelato 2.x had individual supports_foo functions. When forking OpenImageIO, we replaced this with a single entry point that accepts tokens. The main advantage is that this allows future expansion of the set of possible queries without changing the API, adding new entry points, or breaking linkage compatibility.

void const void* OpenImageIO::ImageOutput::to_native_scanline ( TypeDesc  format,
const void *  data,
stride_t  xstride,
std::vector< unsigned char > &  scratch 
) [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.

virtual bool OpenImageIO::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. 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 OpenImageIO::ImageOutput::write_rectangle ( int  xmin,
int  xmax,
int  ymin,
int  ymax,
int  zmin,
int  zmax,
TypeDesc  format,
const void *  data,
stride_t  xstride = AutoStride,
stride_t  ystride = AutoStride,
stride_t  zstride = AutoStride 
) [inline, virtual]

Write pixels whose x coords range over xmin..xmax (inclusive), y coords over ymin..ymax, and z coords over zmin...zmax. 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. 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 OpenImageIO::ImageOutput::write_scanline ( int  y,
int  z,
TypeDesc  format,
const void *  data,
stride_t  xstride = AutoStride 
) [inline, 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. 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 OpenImageIO::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 
) [inline, 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. 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.


Member Data Documentation

format spec of the currently open image


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on Tue Oct 27 06:30:41 2009 for OpenImageIO by  doxygen 1.6.1