#include <imageio.h>
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 ImageSpec & | spec (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 ImageOutput * | create (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 |
ImageOutput abstracts the writing of an image file in a file format-agnostic manner.
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] |
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.
ImageSpec OpenImageIO::ImageOutput::m_spec [protected] |
format spec of the currently open image