|
| virtual | ~ImageOutput () |
| |
| virtual const char * | format_name (void) const =0 |
| | Return the name of the format implemented by this class. More...
|
| |
| virtual bool | copy_image (ImageInput *in) |
| |
| virtual int | send_to_output (const char *format,...) |
| |
| int | send_to_client (const char *format,...) |
| |
| virtual bool | set_ioproxy (Filesystem::IOProxy *ioproxy) |
| |
| bool | has_error () const |
| |
| std::string | geterror (bool clear=true) const |
| |
| template<typename... Args> |
| OIIO_FORMAT_DEPRECATED 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 | errorfmt (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 |
| |
| void * | operator new (size_t size) |
| |
| void | operator delete (void *ptr) |
| |
|
Common features of all the write methods:
|
| 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=nullptr, void *progress_callback_data=nullptr) |
| |
| 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) |
| |
| virtual bool | set_thumbnail (const ImageBuf &thumb) |
| |
|
| | ImageOutput () |
| |
| const void * | 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) |
| |
| const void * | 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) |
| |
| 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, 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) |
| |
ImageOutput abstracts the writing of an image file in a file format-agnostic manner.
Users don't directly declare these. Instead, you call the create() static method, which will return a unique_ptr holding a subclass of ImageOutput that implements writing the particular format.
Definition at line 1770 of file imageio.h.
| virtual bool ImageOutput::copy_image |
( |
ImageInput * |
in | ) |
|
|
virtual |
Read the pixels of 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.
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 file format implementations may have a special technique for directly copying raw pixel data from the input to the output, when both are the same file type and the same pixel data type. 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.
Note: this method is NOT thread-safe, since it depends on persistent state in the ImageInput.
- Parameters
-
- Returns
true upon success, or false upon failure.
| virtual bool ImageOutput::open |
( |
const std::string & |
filename, |
|
|
int subimages |
OIIO_MAYBE_UNUSED, |
|
|
const ImageSpec * |
specs |
|
) |
| |
|
inlinevirtual |
Open a multi-subimage file with given name and specifications for each of the subimages. 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 must 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.
- Parameters
-
| filename | The name of the image file to open, UTF-8 encoded. |
| subimages | The number of subimages (and therefore the length of the specs[] array. |
| specs[] | Pointer to an array of ImageSpec objects describing each of the expected subimages. |
- Returns
true upon success, or false upon failure.
Definition at line 2016 of file imageio.h.
| virtual int ImageOutput::supports |
( |
string_view feature |
OIIO_MAYBE_UNUSED | ) |
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 1 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 ImageOutput implementations are expected to recognize include:
"tiles" : Is this format writer able to write tiled images?"rectangles" : Does this writer accept arbitrary rectangular pixel regions (via write_rectangle())? Returning 0 indicates that pixels must be transmitted via write_scanline() (if scanline-oriented) or write_tile() (if tile-oriented, and only if supports("tiles") returns true)."random_access" : May tiles or scanlines be written in any order (0 indicates that they must be in successive order)?"multiimage" : Does this format support multiple subimages within a file?"appendsubimage" : Does this format support multiple subimages that can be successively appended at will via open(name,spec,AppendSubimage)? A value of 0 means that the format requires pre-declaring the number and specifications of the subimages when the file is first opened, with open(name,subimages,specs)."mipmap" : Does this format support multiple resolutions for an image/subimage?"volumes" : Does this format support "3D" pixel arrays (a.k.a. volume images)?"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 is true for plugins that implement interactive display, rather than a saved image file."empty" : Does this plugin support passing a NULL data pointer to the various write routines to indicate that the entire data block is composed of pixels with value zero? Plugins that support this achieve a speedup when passing blank scanlines or tiles (since no actual data needs to be transmitted or converted)."channelformats" : Does this format writer support per-channel data formats, respecting the ImageSpec's channelformats field? If not, it only accepts a single data format for all channels and will ignore the channelformats field of the spec."displaywindow" : Does the format support display ("full") windows distinct from the pixel data window?"origin" : Does the image format support specifying a pixel window origin (i.e., nonzero ImageSpec x, y, z)?"negativeorigin" : Does the image format allow data and display window origins (i.e., ImageSpec x, y, z, full_x, full_y, full_z) to have negative values?"deepdata" : Does the image format allow "deep" data consisting of multiple values per pixel (and potentially a differing number of values from pixel to pixel)?"arbitrary_metadata" : Does the image file format allow metadata with arbitrary names (and either arbitrary, or a reasonable set of, data types)? (Versus the file format supporting only a fixed list of specific metadata names/values.)"exif" Does the image file format support Exif camera data (either specifically, or via arbitrary named metadata)?"iptc" Does the image file format support IPTC data (either specifically, or via arbitrary named metadata)?"ioproxy" Does the image file format support writing to an IOProxy?"procedural" : Is this a purely procedural output that doesn't write an actual file?"thumbnail" : Does this format writer support adding a reduced resolution copy of the image via the thumbnail() method?"thumbnail_after_write" : Does this format writer support calling thumbnail() after the scanlines or tiles have been specified? (Supporting "thumbnail" but not "thumbnail_after_write" means that any thumbnail must be supplied immediately after open(), prior to any of the write_*() calls.)
This list of queries may be extended in future releases. Since this can be done simply by recognizing new query strings, and does not require any new API entry points, addition of support for new queries does not break ``link compatibility'' with previously-compiled plugins.
Definition at line 1962 of file imageio.h.
| 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 the range
[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.
- Parameters
-
| xbegin/xend | The x range of the pixels covered by the group of tiles passed. |
| ybegin/yend | The y range of the pixels covered by the tiles. |
| zbegin/zend | The z range of the pixels covered by the tiles (for a 2D image, zbegin=0 and zend=1). |
| deepdata | A DeepData object with the data for the tiles. |
- Returns
true upon success, or false upon failure.
- Note
- The call will fail if the image is not tiled, or if the pixel ranges do not fall along tile (or image) boundaries, or if it is not a valid tile range.
Write the entire image of spec.width x spec.height x spec.depth pixels, from a buffer with the given strides and in the desired format.
Depending on the spec, this will 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 (between 0.0 and 1.0) that has been written thus far.
- Parameters
-
| format | A TypeDesc describing the type of data. |
| data | Pointer to the pixel data. |
| xstride/ystride/zstride | The distance in bytes between successive pixels, scanlines, and image planes (or AutoStride). |
| progress_callback/progress_callback_data | Optional progress callback. |
- Returns
true upon success, or false upon failure.
| 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 = format.size() * spec.nchannels
ystride = xstride * (xend-xbegin)
zstride = ystride * (yend-ybegin)
- Parameters
-
| xbegin/xend | The x range of the pixels being passed. |
| ybegin/yend | The y range of the pixels being passed. |
| zbegin/zend | The z range of the pixels being passed (for a 2D image, zbegin=0 and zend=1). |
| format | A TypeDesc describing the type of data. |
| data | Pointer to the pixel data. |
| xstride/ystride/zstride | The distance in bytes between successive pixels, scanlines, and image planes (or AutoStride). |
- Returns
true upon success, or false upon failure.
- Note
- The call will fail for a format plugin that does not return true for
supports("rectangles").
Write multiple scanlines that include pixels (*,y,z) for all ybegin <= y < yend, from data. This is analogous to write_scanline(y,z,format,data,xstride) repeatedly for each of the scanlines in turn (the advantage, though, is that some image file types may be able to write multiple scanlines more efficiently or in parallel, than it could with one scanline at a time).
- Parameters
-
| ybegin/yend | The y range of the scanlines being passed. |
| z | The z coordinate of the scanline. |
| format | A TypeDesc describing the type of data. |
| data | Pointer to the pixel data. |
| xstride/ystride | The distance in bytes between successive pixels and scanlines (or AutoStride). |
- Returns
true upon success, or false upon failure.
Write the tile with (x,y,z) as the upper left corner. 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 = format.size() * spec.nchannels
ystride = xstride * spec.tile_width
zstride = ystride * spec.tile_height
- Parameters
-
| x/y/z | The upper left coordinate of the tile being passed. |
| format | A TypeDesc describing the type of data. |
| data | Pointer to the pixel data. |
| xstride/ystride/zstride | The distance in bytes between successive pixels, scanlines, and image planes (or AutoStride to indicate a "contiguous" single tile). |
- Returns
true upon success, or false upon failure.
- Note
- This call will fail if the image is not tiled, or if (x,y,z) is not the upper left corner coordinates of a tile.
| 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 calling write_tile(x,y,z,...) for each tile in turn (but for some file formats, passing multiple tiles may allow it to write 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 = format.size() * spec.nchannels
ystride = xstride * (xend-xbegin)
zstride = ystride * (yend-ybegin)
- Parameters
-
| xbegin/xend | The x range of the pixels covered by the group of tiles passed. |
| ybegin/yend | The y range of the pixels covered by the tiles. |
| zbegin/zend | The z range of the pixels covered by the tiles (for a 2D image, zbegin=0 and zend=1). |
| format | A TypeDesc describing the type of data. |
| data | Pointer to the pixel data. |
| xstride/ystride/zstride | The distance in bytes between successive pixels, scanlines, and image planes (or AutoStride). |
- Returns
true upon success, or false upon failure.
- Note
- The call will fail if the image is not tiled, or if the pixel ranges do not fall along tile (or image) boundaries, or if it is not a valid tile range.
1.8.6