|
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 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_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 |
|
|
| 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) |
|
ImageOutput abstracts the writing of an image file in a file format-agnostic manner.
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.
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 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.
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_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.