HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
imageio.h
Go to the documentation of this file.
1 // Copyright 2008-present Contributors to the OpenImageIO project.
2 // SPDX-License-Identifier: BSD-3-Clause
3 // https://github.com/OpenImageIO/oiio
4 
5 
6 /////////////////////////////////////////////////////////////////////////////
7 /// \file
8 ///
9 /// Provides a simple API that abstracts the reading and writing of
10 /// images. Subclasses, which may be found in DSO/DLL's, implement
11 /// particular formats.
12 ///
13 /////////////////////////////////////////////////////////////////////////////
14 
15 // clang-format off
16 
17 #pragma once
18 #define OPENIMAGEIO_IMAGEIO_H
19 
20 #if defined(_MSC_VER)
21 // Ignore warnings about DLL exported classes with member variables that are template classes.
22 // This happens with the std::vector<T> and std::string members of the classes below.
23 # pragma warning(disable : 4251)
24 #endif
25 
26 #include <cmath>
27 #include <limits>
28 #include <string>
29 #include <vector>
30 
31 #include <OpenImageIO/span.h>
32 #include <OpenImageIO/export.h>
34 #include <OpenImageIO/paramlist.h>
35 #include <OpenImageIO/platform.h>
36 #include <OpenImageIO/strutil.h>
37 #include <OpenImageIO/thread.h>
38 #include <OpenImageIO/typedesc.h>
39 
41 
42 class DeepData;
43 class ImageBuf;
44 
45 
46 /// Type we use for stride lengths between pixels, scanlines, or image
47 /// planes.
48 using stride_t = int64_t;
49 
50 /// Type we use to express how many pixels (or bytes) constitute an image,
51 /// tile, or scanline.
52 using imagesize_t = uint64_t;
53 
54 /// Special value to indicate a stride length that should be
55 /// auto-computed.
57 
58 
59 
60 /// Pointer to a function called periodically by read_image and
61 /// write_image. This can be used to implement progress feedback, etc.
62 /// It takes an opaque data pointer (passed to read_image/write_image)
63 /// and a float giving the portion of work done so far. It returns a
64 /// bool, which if 'true' will STOP the read or write.
65 typedef bool (*ProgressCallback)(void *opaque_data, float portion_done);
66 
67 
68 
69 // Deprecated typedefs. Just use ParamValue and ParamValueList directly.
72 
73 
74 // Forward declaration of IOProxy
75 namespace Filesystem {
76  class IOProxy;
77 }
78 
79 
80 /// ROI is a small helper struct describing a rectangular region of interest
81 /// in an image. The region is [xbegin,xend) x [begin,yend) x [zbegin,zend),
82 /// with the "end" designators signifying one past the last pixel in each
83 /// dimension, a la STL style.
84 ///
85 struct ROI {
86  ///@{
87  /// @name ROI data members
88  /// The data members are:
89  ///
90  /// int xbegin, xend, ybegin, yend, zbegin, zend;
91  /// int chbegin, chend;
92  ///
93  /// These describe the spatial extent
94  /// [xbegin,xend) x [ybegin,yend) x [zbegin,zend)
95  /// And the channel extent:
96  /// [chbegin,chend)]
97  int xbegin, xend;
98  int ybegin, yend;
99  int zbegin, zend;
101  ///@}
102 
103  /// Default constructor is an undefined region. Note that this is also
104  /// interpreted as All().
105  constexpr ROI () noexcept : xbegin(std::numeric_limits<int>::min()), xend(0),
106  ybegin(0), yend(0), zbegin(0), zend(0), chbegin(0), chend(0)
107  { }
108 
109  /// Constructor with an explicitly defined region.
110  ///
111  constexpr ROI (int xbegin, int xend, int ybegin, int yend,
112  int zbegin=0, int zend=1, int chbegin=0, int chend=10000) noexcept
113  : xbegin(xbegin), xend(xend), ybegin(ybegin), yend(yend),
115  { }
116 
117  /// Is a region defined?
118  constexpr bool defined () const noexcept { return (xbegin != std::numeric_limits<int>::min()); }
119 
120  ///@{
121  /// @name Spatial size functions.
122  /// The width, height, and depth of the region.
123  constexpr int width () const noexcept { return xend - xbegin; } ///< Height
124  constexpr int height () const noexcept { return yend - ybegin; } ///< Width
125  constexpr int depth () const noexcept { return zend - zbegin; } ///< Depth
126  ///@}
127 
128  /// Number of channels in the region. Beware -- this defaults to a
129  /// huge number, and to be meaningful you must consider
130  /// std::min (imagebuf.nchannels(), roi.nchannels()).
131  constexpr int nchannels () const noexcept { return chend - chbegin; }
132 
133  /// Total number of pixels in the region.
134  constexpr imagesize_t npixels () const noexcept {
135  return defined()
137  : 0;
138  }
139 
140  /// All() is an alias for the default constructor, which indicates that
141  /// it means "all" of the image, or no region restriction. For example,
142  /// float myfunc (ImageBuf &buf, ROI roi = ROI::All());
143  /// Note that this is equivalent to:
144  /// float myfunc (ImageBuf &buf, ROI roi = {});
145  static constexpr ROI All () noexcept { return ROI(); }
146 
147  /// Test equality of two ROIs
148  friend constexpr bool operator== (const ROI &a, const ROI &b) noexcept {
149  return (a.xbegin == b.xbegin && a.xend == b.xend &&
150  a.ybegin == b.ybegin && a.yend == b.yend &&
151  a.zbegin == b.zbegin && a.zend == b.zend &&
152  a.chbegin == b.chbegin && a.chend == b.chend);
153  }
154  /// Test inequality of two ROIs
155  friend constexpr bool operator!= (const ROI &a, const ROI &b) noexcept {
156  return (a.xbegin != b.xbegin || a.xend != b.xend ||
157  a.ybegin != b.ybegin || a.yend != b.yend ||
158  a.zbegin != b.zbegin || a.zend != b.zend ||
159  a.chbegin != b.chbegin || a.chend != b.chend);
160  }
161 
162  /// Test if the coordinate is within the ROI.
163  constexpr bool contains (int x, int y, int z=0, int ch=0) const noexcept {
164  return x >= xbegin && x < xend && y >= ybegin && y < yend
165  && z >= zbegin && z < zend && ch >= chbegin && ch < chend;
166  }
167 
168  /// Test if another ROI is entirely within our ROI.
169  constexpr bool contains (const ROI& other) const noexcept {
170  return (other.xbegin >= xbegin && other.xend <= xend &&
171  other.ybegin >= ybegin && other.yend <= yend &&
172  other.zbegin >= zbegin && other.zend <= zend &&
173  other.chbegin >= chbegin && other.chend <= chend);
174  }
175 
176  /// Stream output of the range
177  friend std::ostream & operator<< (std::ostream &out, const ROI &roi) {
178  out << roi.xbegin << ' ' << roi.xend << ' ' << roi.ybegin << ' '
179  << roi.yend << ' ' << roi.zbegin << ' ' << roi.zend << ' '
180  << roi.chbegin << ' ' << roi.chend;
181  return out;
182  }
183 };
184 
185 
186 
187 /// Union of two regions, the smallest region containing both.
188 inline constexpr ROI roi_union (const ROI &A, const ROI &B) noexcept {
189  return (A.defined() && B.defined())
190  ? ROI (std::min (A.xbegin, B.xbegin), std::max (A.xend, B.xend),
191  std::min (A.ybegin, B.ybegin), std::max (A.yend, B.yend),
192  std::min (A.zbegin, B.zbegin), std::max (A.zend, B.zend),
193  std::min (A.chbegin, B.chbegin), std::max (A.chend, B.chend))
194  : (A.defined() ? A : B);
195 }
196 
197 /// Intersection of two regions.
198 inline constexpr ROI roi_intersection (const ROI &A, const ROI &B) noexcept {
199  return (A.defined() && B.defined())
200  ? ROI (std::max (A.xbegin, B.xbegin), std::min (A.xend, B.xend),
201  std::max (A.ybegin, B.ybegin), std::min (A.yend, B.yend),
202  std::max (A.zbegin, B.zbegin), std::min (A.zend, B.zend),
203  std::max (A.chbegin, B.chbegin), std::min (A.chend, B.chend))
204  : (A.defined() ? A : B);
205 }
206 
207 
208 
209 
210 /// ImageSpec describes the data format of an image -- dimensions, layout,
211 /// number and meanings of image channels.
212 ///
213 /// The `width, height, depth` are the size of the data of this image, i.e.,
214 /// the number of pixels in each dimension. A ``depth`` greater than 1
215 /// indicates a 3D "volumetric" image. The `x, y, z` fields indicate the
216 /// *origin* of the pixel data of the image. These default to (0,0,0), but
217 /// setting them differently may indicate that this image is offset from the
218 /// usual origin.
219 /// Therefore the pixel data are defined over pixel coordinates
220 /// [`x` ... `x+width-1`] horizontally,
221 /// [`y` ... `y+height-1`] vertically,
222 /// and [`z` ... `z+depth-1`] in depth.
223 ///
224 /// The analogous `full_width`, `full_height`, `full_depth` and `full_x`,
225 /// `full_y`, `full_z` fields define a "full" or "display" image window over
226 /// the region [`full_x` ... `full_x+full_width-1`] horizontally, [`full_y`
227 /// ... `full_y+full_height-1`] vertically, and [`full_z`...
228 /// `full_z+full_depth-1`] in depth.
229 ///
230 /// Having the full display window different from the pixel data window can
231 /// be helpful in cases where you want to indicate that your image is a
232 /// *crop window* of a larger image (if the pixel data window is a subset of
233 /// the full display window), or that the pixels include *overscan* (if the
234 /// pixel data is a superset of the full display window), or may simply
235 /// indicate how different non-overlapping images piece together.
236 ///
237 /// For tiled images, `tile_width`, `tile_height`, and `tile_depth` specify
238 /// that the image is stored in a file organized into rectangular *tiles*
239 /// of these dimensions. The default of 0 value for these fields indicates
240 /// that the image is stored in scanline order, rather than as tiles.
241 ///
242 
244 public:
245  ///@{
246  /// @name ImageSpec data members
247  ///
248  /// The `ImageSpec` contains data fields for the values that are
249  /// required to describe nearly any image, and an extensible list of
250  /// arbitrary attributes that can hold metadata that may be user-defined
251  /// or specific to individual file formats.
252  ///
253  /// Here are the hard-coded data fields:
254 
255  int x; ///< origin (upper left corner) of pixel data
256  int y; ///< origin (upper left corner) of pixel data
257  int z; ///< origin (upper left corner) of pixel data
258  int width; ///< width of the pixel data window
259  int height; ///< height of the pixel data window
260  int depth; ///< depth of pixel data, >1 indicates a "volume"
261  int full_x; ///< origin of the full (display) window
262  int full_y; ///< origin of the full (display) window
263  int full_z; ///< origin of the full (display) window
264  int full_width; ///< width of the full (display) window
265  int full_height; ///< height of the full (display) window
266  int full_depth; ///< depth of the full (display) window
267  int tile_width; ///< tile width (0 for a non-tiled image)
268  int tile_height; ///< tile height (0 for a non-tiled image)
269  int tile_depth; ///< tile depth (0 for a non-tiled image,
270  ///< 1 for a non-volume image)
271  int nchannels; ///< number of image channels, e.g., 4 for RGBA
272 
273  TypeDesc format; ///< Data format of the channels.
274  ///< Describes the native format of the pixel data values
275  /// themselves, as a `TypeDesc`. Typical values would be
276  /// `TypeDesc::UINT8` for 8-bit unsigned values, `TypeDesc::FLOAT`
277  /// for 32-bit floating-point values, etc.
278  std::vector<TypeDesc> channelformats;
279  ///< Optional per-channel data formats. If all channels of the image
280  /// have the same data format, that will be described by `format`
281  /// and `channelformats` will be empty (zero length). If there are
282  /// different data formats for each channel, they will be described
283  /// in the `channelformats` vector, and the `format` field will
284  /// indicate a single default data format for applications that
285  /// don't wish to support per-channel formats (usually this will be
286  /// the format of the channel that has the most precision).
287 
288  std::vector<std::string> channelnames;
289  ///< The names of each channel, in order. Typically this will be "R",
290  ///< "G", "B", "A" (alpha), "Z" (depth), or other arbitrary names.
292  ///< The index of the channel that represents *alpha* (pixel
293  ///< coverage and/or transparency). It defaults to -1 if no alpha
294  ///< channel is present, or if it is not known which channel
295  ///< represents alpha.
297  ///< The index of the channel that represents *z* or *depth* (from
298  ///< the camera). It defaults to -1 if no depth channel is present,
299  ///< or if it is not know which channel represents depth.
300  bool deep; ///< True if the image contains deep data.
301  ///< If `true`, this indicates that the image describes contains
302  ///< "deep" data consisting of multiple samples per pixel. If
303  ///< `false`, it's an ordinary image with one data value (per
304  ///< channel) per pixel.
306  ///< A list of arbitrarily-named and arbitrarily-typed additional
307  /// attributes of the image, for any metadata not described by the
308  /// hard-coded fields described above. This list may be manipulated
309  /// with the `attribute()` and `find_attribute()` methods.
310 
311  ///@}
312 
313  /// Constructor: given just the data format, set all other fields to
314  /// something reasonable.
316 
317  /// Constructor: given just the data format (as any type name recognized
318  /// by the `TypeDesc` constructor), set all other fields to something
319  /// reasonable.
321 
322  /// Constructs an `ImageSpec` with the given x and y resolution, number
323  /// of channels, and pixel data format.
324  ///
325  /// All other fields are set to the obvious defaults -- the image is an
326  /// ordinary 2D image (not a volume), the image is not offset or a crop
327  /// of a bigger image, the image is scanline-oriented (not tiled),
328  /// channel names are "R", "G", "B"' and "A" (up to and including 4
329  /// channels, beyond that they are named "channel *n*"), the fourth
330  /// channel (if it exists) is assumed to be alpha.
331  ImageSpec (int xres, int yres, int nchans, TypeDesc fmt = TypeUInt8) noexcept;
332 
333  /// Construct an `ImageSpec` with the given x and y resolution, number
334  /// of channels, and pixel data format name (as any type name recognized
335  /// by the `TypeDesc` constructor).
336  ImageSpec (int xres, int yres, int nchans, string_view fmt) noexcept
337  : ImageSpec(xres, yres, nchans, TypeDesc(fmt)) {}
338 
339  /// Construct an `ImageSpec` whose dimensions (both data and "full") and
340  /// number of channels are given by the `ROI`, pixel data type by `fmt`,
341  /// and other fields are set to their default values.
342  explicit ImageSpec (const ROI &roi, TypeDesc fmt = TypeUInt8) noexcept;
343 
344  /// Construct an `ImageSpec` from an ROI giving dimensions, and the name
345  /// of a data type that will be recognized by the `TypeDesc` constructor.
346  explicit ImageSpec (const ROI &roi, string_view fmt) noexcept
347  : ImageSpec(roi, TypeDesc(fmt)) {}
348 
349  /// Set the data format, and clear any per-channel format information
350  /// in `channelformats`.
351  void set_format (TypeDesc fmt) noexcept;
352 
353  /// Set the data format, and clear any per-channel format information
354  /// in `channelformats`. The `fmt` may be a string such as `"uint8"`,
355  /// or any other type name recognized by the TypeDesc constructor.
356  void set_format (string_view fmt) noexcept { set_format(TypeDesc(fmt)); }
357 
358  /// Sets the `channelnames` to reasonable defaults for the number of
359  /// channels. Specifically, channel names are set to "R", "G", "B,"
360  /// and "A" (up to and including 4 channels, beyond that they are named
361  /// "channel*n*".
362  void default_channel_names () noexcept;
363 
364  /// Returns the number of bytes comprising each channel of each pixel
365  /// (i.e., the size of a single value of the type described by the
366  /// `format` field).
367  size_t channel_bytes() const noexcept { return format.size(); }
368 
369  /// Return the number of bytes needed for the single specified
370  /// channel. If native is false (default), compute the size of one
371  /// channel of `this->format`, but if native is true, compute the size
372  /// of the channel in terms of the "native" data format of that
373  /// channel as stored in the file.
374  size_t channel_bytes (int chan, bool native=false) const noexcept;
375 
376  /// Return the number of bytes for each pixel (counting all channels).
377  /// If `native` is false (default), assume all channels are in
378  /// `this->format`, but if `native` is true, compute the size of a pixel
379  /// in the "native" data format of the file (these may differ in
380  /// the case of per-channel formats).
381  size_t pixel_bytes (bool native=false) const noexcept;
382 
383  /// Return the number of bytes for just the subset of channels in each
384  /// pixel described by [chbegin,chend). If native is false (default),
385  /// assume all channels are in this->format, but if native is true,
386  /// compute the size of a pixel in the "native" data format of the file
387  /// (these may differ in the case of per-channel formats).
388  size_t pixel_bytes (int chbegin, int chend, bool native=false) const noexcept;
389 
390  /// Returns the number of bytes comprising each scanline, i.e.,
391  /// `pixel_bytes(native) * width` This will return
392  /// `std::numeric_limits<imagesize_t>::max()` in the event of an
393  /// overflow where it's not representable in an `imagesize_t`.
394  imagesize_t scanline_bytes (bool native=false) const noexcept;
395 
396  /// Return the number of pixels comprising a tile (or 0 if it is not a
397  /// tiled image). This will return
398  /// `std::numeric_limits<imagesize_t>::max()` in the event of an
399  /// overflow where it's not representable in an `imagesize_t`.
400  imagesize_t tile_pixels () const noexcept;
401 
402  /// Returns the number of bytes comprising an image tile, i.e.,
403  /// `pixel_bytes(native) * tile_width * tile_height * tile_depth`
404  /// If native is false (default), assume all channels are in
405  /// `this->format`, but if `native` is true, compute the size of a pixel
406  /// in the "native" data format of the file (these may differ in the
407  /// case of per-channel formats).
408  imagesize_t tile_bytes (bool native=false) const noexcept;
409 
410  /// Return the number of pixels for an entire image. This will
411  /// return `std::numeric_limits<imagesize_t>::max()` in the event of
412  /// an overflow where it's not representable in an `imagesize_t`.
413  imagesize_t image_pixels () const noexcept;
414 
415  /// Returns the number of bytes comprising an entire image of these
416  /// dimensions, i.e.,
417  /// `pixel_bytes(native) * width * height * depth`
418  /// This will return `std::numeric_limits<image size_t>::max()` in the
419  /// event of an overflow where it's not representable in an
420  /// `imagesize_t`. If `native` is false (default), assume all channels
421  /// are in `this->format`, but if `native` is true, compute the size of
422  /// a pixel in the "native" data format of the file (these may differ in
423  /// the case of per-channel formats).
424  imagesize_t image_bytes (bool native=false) const noexcept;
425 
426  /// Verify that on this platform, a `size_t` is big enough to hold the
427  /// number of bytes (and pixels) in a scanline, a tile, and the
428  /// whole image. If this returns false, the image is much too big
429  /// to allocate and read all at once, so client apps beware and check
430  /// these routines for overflows!
431  bool size_t_safe() const noexcept {
433  return image_bytes() < big && scanline_bytes() < big &&
434  tile_bytes() < big;
435  }
436 
437  /// Adjust the stride values, if set to AutoStride, to be the right
438  /// sizes for contiguous data with the given format, channels,
439  /// width, height.
440  static void auto_stride (stride_t &xstride, stride_t &ystride,
441  stride_t &zstride, stride_t channelsize,
442  int nchannels, int width, int height) noexcept {
443  if (xstride == AutoStride)
444  xstride = nchannels * channelsize;
445  if (ystride == AutoStride)
446  ystride = xstride * width;
447  if (zstride == AutoStride)
448  zstride = ystride * height;
449  }
450 
451  /// Adjust the stride values, if set to AutoStride, to be the right
452  /// sizes for contiguous data with the given format, channels,
453  /// width, height.
454  static void auto_stride (stride_t &xstride, stride_t &ystride,
455  stride_t &zstride, TypeDesc format,
456  int nchannels, int width, int height) noexcept {
457  auto_stride (xstride, ystride, zstride, format.size(),
458  nchannels, width, height);
459  }
460 
461  /// Adjust xstride, if set to AutoStride, to be the right size for
462  /// contiguous data with the given format and channels.
463  static void auto_stride (stride_t &xstride, TypeDesc format, int nchannels) noexcept {
464  if (xstride == AutoStride)
465  xstride = nchannels * format.size();
466  }
467 
468  /// Add a metadata attribute to `extra_attribs`, with the given name and
469  /// data type. The `value` pointer specifies the address of the data to
470  /// be copied.
471  void attribute (string_view name, TypeDesc type, const void *value);
472 
473  /// Add an `unsigned int` attribute to `extra_attribs`.
474  void attribute (string_view name, unsigned int value) {
475  attribute (name, TypeDesc::UINT, &value);
476  }
477 
478  /// Add an `int` attribute to `extra_attribs`.
480  attribute (name, TypeDesc::INT, &value);
481  }
482 
483  /// Add a `float` attribute to `extra_attribs`.
484  void attribute (string_view name, float value) {
485  attribute (name, TypeDesc::FLOAT, &value);
486  }
487 
488  /// Add a string attribute to `extra_attribs`.
490  std::string str(value);
491  const char *s = str.c_str();
492  attribute (name, TypeDesc::STRING, &s);
493  }
494 
495  /// Parse a string containing a textual representation of a value of
496  /// the given `type`, and add that as an attribute to `extra_attribs`.
497  /// Example:
498  ///
499  /// spec.attribute ("temperature", TypeString, "-273.15");
500  ///
502 
503  /// Searches `extra_attribs` for any attributes matching `name` (as a
504  /// regular expression), removing them entirely from `extra_attribs`. If
505  /// `searchtype` is anything other than `TypeDesc::UNKNOWN`, matches
506  /// will be restricted only to attributes with the given type. The name
507  /// comparison will be case-sensitive if `casesensitive` is true,
508  /// otherwise in a case-insensitive manner.
509  void erase_attribute (string_view name,
510  TypeDesc searchtype=TypeDesc::UNKNOWN,
511  bool casesensitive=false);
512 
513  /// Searches `extra_attribs` for an attribute matching `name`, returning
514  /// a pointer to the attribute record, or NULL if there was no match.
515  /// If `searchtype` is anything other than `TypeDesc::UNKNOWN`, matches
516  /// will be restricted only to attributes with the given type. The name
517  /// comparison will be exact if `casesensitive` is true, otherwise in a
518  /// case-insensitive manner if `caseinsensitive` is false.
519  ParamValue * find_attribute (string_view name,
520  TypeDesc searchtype=TypeDesc::UNKNOWN,
521  bool casesensitive=false);
522  const ParamValue *find_attribute (string_view name,
523  TypeDesc searchtype=TypeDesc::UNKNOWN,
524  bool casesensitive=false) const;
525 
526  /// Search for the named attribute and return the pointer to its
527  /// `ParamValue` record, or NULL if not found. This variety of
528  /// `find_attribute(}` can retrieve items such as "width", which are
529  /// data members of the `ImageSpec`, but not in `extra_attribs`. The
530  /// `tmpparam` is a storage area owned by the caller, which is used as
531  /// temporary buffer in cases where the information does not correspond
532  /// to an actual `extra_attribs` (in this case, the return value will be
533  /// `&tmpparam`). The extra names it understands are:
534  ///
535  /// - `"x"` `"y"` `"z"` `"width"` `"height"` `"depth"`
536  /// `"full_x"` `"full_y"` `"full_z"` `"full_width"` `"full_height"` `"full_depth"`
537  ///
538  /// Returns the `ImageSpec` fields of those names (despite the
539  /// fact that they are technically not arbitrary named attributes
540  /// in `extra_attribs`). All are of type `int`.
541  ///
542  /// - `"datawindow"`
543  ///
544  /// Without a type, or if requested explicitly as an `int[4]`,
545  /// returns the OpenEXR-like pixel data min and max coordinates,
546  /// as a 4-element integer array: `{ x, y, x+width-1, y+height-1
547  /// }`. If instead you specifically request as an `int[6]`, it
548  /// will return the volumetric data window, `{ x, y, z, x+width-1,
549  /// y+height-1, z+depth-1 }`.
550  ///
551  /// - `"displaywindow"`
552  ///
553  /// Without a type, or if requested explicitly as an `int[4]`,
554  /// returns the OpenEXR-like pixel display min and max
555  /// coordinates, as a 4-element integer array: `{ full_x, full_y,
556  /// full_x+full_width-1, full_y+full_height-1 }`. If instead you
557  /// specifically request as an `int[6]`, it will return the
558  /// volumetric display window, `{ full_x, full_y, full_z,
559  /// full_x+full_width-1, full_y+full_height-1, full_z+full_depth-1 }`.
560  ///
561  /// EXAMPLES
562  ///
563  /// ImageSpec spec; // has the info
564  /// Imath::Box2i dw; // we want the displaywindow here
565  /// ParamValue tmp; // so we can retrieve pseudo-values
566  /// TypeDesc int4("int[4]"); // Equivalent: TypeDesc int4(TypeDesc::INT,4);
567  /// const ParamValue* p = spec.find_attribute ("displaywindow", int4);
568  /// if (p)
569  /// dw = Imath::Box2i(p->get<int>(0), p->get<int>(1),
570  /// p->get<int>(2), p->get<int>(3));
571  ///
572  /// p = spec.find_attribute("temperature", TypeFloat);
573  /// if (p)
574  /// float temperature = p->get<float>();
575  ///
576  const ParamValue * find_attribute (string_view name,
577  ParamValue &tmpparam,
578  TypeDesc searchtype=TypeDesc::UNKNOWN,
579  bool casesensitive=false) const;
580 
581  /// If the named attribute can be found in the `ImageSpec`, return its
582  /// data type. If no such attribute exists, return `TypeUnknown`.
583  ///
584  /// This was added in version 2.1.
585  TypeDesc getattributetype (string_view name,
586  bool casesensitive = false) const;
587 
588  /// If the `ImageSpec` contains the named attribute and its type matches
589  /// `type`, copy the attribute value into the memory pointed to by `val`
590  /// (it is up to the caller to ensure there is enough space) and return
591  /// `true`. If no such attribute is found, or if it doesn't match the
592  /// type, return `false` and do not modify `val`.
593  ///
594  /// EXAMPLES:
595  ///
596  /// ImageSpec spec;
597  /// ...
598  /// // Retrieving an integer attribute:
599  /// int orientation = 0;
600  /// spec.getattribute ("orientation", TypeInt, &orientation);
601  ///
602  /// // Retrieving a string attribute with a char*:
603  /// const char* compression = nullptr;
604  /// spec.getattribute ("compression", TypeString, &compression);
605  ///
606  /// // Alternately, retrieving a string with a ustring:
607  /// ustring compression;
608  /// spec.getattribute ("compression", TypeString, &compression);
609  ///
610  /// Note that when passing a string, you need to pass a pointer to the
611  /// `char*`, not a pointer to the first character. Also, the `char*`
612  /// will end up pointing to characters owned by the `ImageSpec`; the
613  /// caller does not need to ever free the memory that contains the
614  /// characters.
615  ///
616  /// This was added in version 2.1.
618  bool casesensitive = false) const;
619 
620  /// Retrieve the named metadata attribute and return its value as an
621  /// `int`. Any integer type will convert to `int` by truncation or
622  /// expansion, string data will parsed into an `int` if its contents
623  /// consist of of the text representation of one integer. Floating point
624  /// data will not succeed in converting to an `int`. If no such metadata
625  /// exists, or are of a type that cannot be converted, the `defaultval`
626  /// will be returned.
627  int get_int_attribute (string_view name, int defaultval=0) const;
628 
629  /// Retrieve the named metadata attribute and return its value as a
630  /// `float`. Any integer or floating point type will convert to `float`
631  /// in the obvious way (like a C cast), and so will string metadata if
632  /// its contents consist of of the text representation of one floating
633  /// point value. If no such metadata exists, or are of a type that cannot
634  /// be converted, the `defaultval` will be returned.
635  float get_float_attribute (string_view name, float defaultval=0) const;
636 
637  /// Retrieve any metadata attribute, converted to a string.
638  /// If no such metadata exists, the `defaultval` will be returned.
640  string_view defaultval = string_view()) const;
641 
642  /// For a given parameter `p`, format the value nicely as a string. If
643  /// `human` is true, use especially human-readable explanations (units,
644  /// or decoding of values) for certain known metadata.
645  static std::string metadata_val (const ParamValue &p, bool human=false);
646 
647  enum SerialFormat { SerialText, SerialXML };
648  enum SerialVerbose { SerialBrief, SerialDetailed, SerialDetailedHuman };
649 
650  /// Returns, as a string, a serialized version of the `ImageSpec`. The
651  /// `format` may be either `ImageSpec::SerialText` or
652  /// `ImageSpec::SerialXML`. The `verbose` argument may be one of:
653  /// `ImageSpec::SerialBrief` (just resolution and other vital
654  /// statistics, one line for `SerialText`, `ImageSpec::SerialDetailed`
655  /// (contains all metadata in original form), or
656  /// `ImageSpec::SerialDetailedHuman` (contains all metadata, in many
657  /// cases with human-readable explanation).
658  std::string serialize (SerialFormat format,
659  SerialVerbose verbose = SerialDetailed) const;
660 
661  /// Converts the contents of the `ImageSpec` as an XML string.
662  std::string to_xml () const;
663 
664  /// Populates the fields of the `ImageSpec` based on the XML passed in.
665  void from_xml (const char *xml);
666 
667  /// Hunt for the "Compression" and "CompressionQuality" settings in the
668  /// spec and turn them into the compression name and quality. This
669  /// handles compression name/qual combos of the form "name:quality".
670  std::pair<string_view, int>
671  decode_compression_metadata(string_view defaultcomp = "",
672  int defaultqual = -1) const;
673 
674  /// Helper function to verify that the given pixel range exactly covers
675  /// a set of tiles. Also returns false if the spec indicates that the
676  /// image isn't tiled at all.
677  bool valid_tile_range (int xbegin, int xend, int ybegin, int yend,
678  int zbegin, int zend) noexcept {
679  return (tile_width &&
680  ((xbegin-x) % tile_width) == 0 &&
681  ((ybegin-y) % tile_height) == 0 &&
682  ((zbegin-z) % tile_depth) == 0 &&
683  (((xend-x) % tile_width) == 0 || (xend-x) == width) &&
684  (((yend-y) % tile_height) == 0 || (yend-y) == height) &&
685  (((zend-z) % tile_depth) == 0 || (zend-z) == depth));
686  }
687 
688  /// Return the channelformat of the given channel. This is safe even
689  /// if channelformats is not filled out.
690  TypeDesc channelformat (int chan) const {
691  return chan >= 0 && chan < (int)channelformats.size()
692  ? channelformats[chan] : format;
693  }
694 
695  /// Return the channel name of the given channel. This is safe even if
696  /// channelnames is not filled out.
697  string_view channel_name (int chan) const {
698  return chan >= 0 && chan < (int)channelnames.size()
699  ? string_view(channelnames[chan]) : "";
700  }
701 
702  /// Fill in an array of channel formats describing all channels in
703  /// the image. (Note that this differs slightly from the member
704  /// data channelformats, which is empty if there are not separate
705  /// per-channel formats.)
706  void get_channelformats (std::vector<TypeDesc> &formats) const {
707  formats = channelformats;
708  if ((int)formats.size() < nchannels)
709  formats.resize (nchannels, format);
710  }
711 
712  /// Return the index of the channel with the given name, or -1 if no
713  /// such channel is present in `channelnames`.
714  int channelindex (string_view name) const;
715 
716  /// Return pixel data window for this ImageSpec expressed as a ROI.
717  ROI roi () const noexcept {
718  return ROI (x, x+width, y, y+height, z, z+depth, 0, nchannels);
719  }
720 
721  /// Return full/display window for this ImageSpec expressed as a ROI.
722  ROI roi_full () const noexcept {
723  return ROI (full_x, full_x+full_width, full_y, full_y+full_height,
724  full_z, full_z+full_depth, 0, nchannels);
725  }
726 
727  /// Set pixel data window parameters (x, y, z, width, height, depth)
728  /// for this ImageSpec from an ROI.
729  /// Does NOT change the channels of the spec, regardless of r.
730  void set_roi (const ROI &r) noexcept {
731  x = r.xbegin;
732  y = r.ybegin;
733  z = r.zbegin;
734  width = r.width();
735  height = r.height();
736  depth = r.depth();
737  }
738 
739  /// Set full/display window parameters (full_x, full_y, full_z,
740  /// full_width, full_height, full_depth) for this ImageSpec from an ROI.
741  /// Does NOT change the channels of the spec, regardless of r.
742  void set_roi_full (const ROI &r) noexcept {
743  full_x = r.xbegin;
744  full_y = r.ybegin;
745  full_z = r.zbegin;
746  full_width = r.width();
747  full_height = r.height();
748  full_depth = r.depth();
749  }
750 
751  /// Copy from `other` the image dimensions (x, y, z, width, height,
752  /// depth, full*, nchannels, format) and data types. It does *not* copy
753  /// arbitrary named metadata or channel names (thus, for an `ImageSpec`
754  /// with lots of metadata, it is much less expensive than copying the
755  /// whole thing with `operator=()`).
756  void copy_dimensions (const ImageSpec &other) {
757  x = other.x;
758  y = other.y;
759  z = other.z;
760  width = other.width;
761  height = other.height;
762  depth = other.depth;
763  full_x = other.full_x;
764  full_y = other.full_y;
765  full_z = other.full_z;
766  full_width = other.full_width;
767  full_height = other.full_height;
768  full_depth = other.full_depth;
769  tile_width = other.tile_width;
770  tile_height = other.tile_height;
771  tile_depth = other.tile_depth;
772  nchannels = other.nchannels;
773  format = other.format;
774  channelformats = other.channelformats;
775  alpha_channel = other.alpha_channel;
776  z_channel = other.z_channel;
777  deep = other.deep;
778  }
779 
780  /// Returns `true` for a newly initialized (undefined) `ImageSpec`.
781  /// (Designated by no channels and undefined data type -- true of the
782  /// uninitialized state of an ImageSpec, and presumably not for any
783  /// ImageSpec that is useful or purposefully made.)
784  bool undefined () const noexcept {
785  return nchannels == 0 && format == TypeUnknown;
786  }
787 
788  /// Array indexing by string will create an AttrDelegate that enables a
789  /// convenient shorthand for adding and retrieving values from the spec:
790  ///
791  /// 1. Assigning to the delegate adds a metadata attribute:
792  ///
793  /// ImageSpec spec;
794  /// spec["foo"] = 42; // int
795  /// spec["pi"] = float(M_PI); // float
796  /// spec["oiio:ColorSpace"] = "sRGB"; // string
797  /// spec["cameratoworld"] = Imath::Matrix44(...); // matrix
798  ///
799  /// Be very careful, the attribute's type will be implied by the C++
800  /// type of what you assign.
801  ///
802  /// 2. String data may be retrieved directly, and for other types, the
803  /// delegate supports a get<T>() that retrieves an item of type T:
804  ///
805  /// std::string colorspace = spec["oiio:ColorSpace"];
806  /// int dither = spec["oiio:dither"].get<int>();
807  ///
808  /// This was added in version 2.1.
810  {
811  return { this, name };
812  }
814  {
815  return { this, name };
816  }
817 };
818 
819 
820 
821 
822 /// ImageInput abstracts the reading of an image file in a file
823 /// format-agnostic manner.
825 public:
826  /// unique_ptr to an ImageInput
827  using unique_ptr = std::unique_ptr<ImageInput>;
828 
829  /// @{
830  /// @name Creating an ImageIntput
831 
832  /// Create an ImageInput subclass instance that is able to read the
833  /// given file and open it, returning a `unique_ptr` to the ImageInput
834  /// if successful. The `unique_ptr` is set up with an appropriate
835  /// deleter so the ImageInput will be properly closed and deleted when
836  /// the `unique_ptr` goes out of scope or is reset. If the open fails,
837  /// return an empty `unique_ptr` and set an error that can be retrieved
838  /// by `OIIO::geterror()`.
839  ///
840  /// The `config`, if not nullptr, points to an ImageSpec giving hints,
841  /// requests, or special instructions. ImageInput implementations are
842  /// free to not respond to any such requests, so the default
843  /// implementation is just to ignore `config`.
844  ///
845  /// `open()` will first try to make an ImageInput corresponding to
846  /// the format implied by the file extension (for example, `"foo.tif"`
847  /// will try the TIFF plugin), but if one is not found or if the
848  /// inferred one does not open the file, every known ImageInput type
849  /// will be tried until one is found that will open the file.
850  ///
851  /// @param filename
852  /// The name of the file to open, UTF-8 encoded.
853  ///
854  /// @param config
855  /// Optional pointer to an ImageSpec whose metadata contains
856  /// "configuration hints."
857  ///
858  /// @param ioproxy
859  /// Optional pointer to an IOProxy to use (not supported by all
860  /// formats, see `supports("ioproxy")`). The caller retains
861  /// ownership of the proxy.
862  ///
863  /// @returns
864  /// A `unique_ptr` that will close and free the ImageInput when
865  /// it exits scope or is reset. The pointer will be empty if the
866  /// required writer was not able to be created.
867  static unique_ptr open (const std::string& filename,
868  const ImageSpec *config = nullptr,
869  Filesystem::IOProxy* ioproxy = nullptr);
870 
871  /// Create and open an ImageInput using a UTF-16 encoded wstring filename.
872  static unique_ptr open (const std::wstring& filename,
873  const ImageSpec *config = nullptr,
874  Filesystem::IOProxy* ioproxy = nullptr) {
875  return open(Strutil::utf16_to_utf8(filename), config, ioproxy);
876  }
877 
878  /// Create and return an ImageInput implementation that is able to read
879  /// the given file or format. If `do_open` is true (and the `filename`
880  /// is the name of a file, not just a format), fully open it if possible
881  /// (using the optional `config` configuration spec, if supplied),
882  /// otherwise just create the ImageInput but don't open it. The
883  /// plugin_searchpath parameter is an override of the searchpath.
884  /// colon-separated list of directories to search for ImageIO plugin
885  /// DSO/DLL's (not a searchpath for the image itself!).
886  ///
887  /// If the `filename` parameter is the name of a file format (such as
888  /// "openexr"), it will create an ImageInput that reads that particular
889  /// format. If the name is a file extension (such as "exr" or ".exr"),
890  /// it will guess the file format from the extension and return that
891  /// type of ImageInput.
892  ///
893  /// If `filename` is a full file name (such as "hawaii.exr"), it will
894  /// create an ImageInput that reads the format implied by the file
895  /// extension (".tif") and try to open the file with that reader. If the
896  /// file can be opened and appears to be of the correct type, then that
897  /// ImageInput (after being closed) will be returned to the caller. But
898  /// if it fails (say, because the file type does not match the
899  /// extension), then every known kind of image reader will be tried in
900  /// turn, until one can be found that succeeds in opening that file. The
901  /// `create()` file will fail entirely only if no known image reader
902  /// type succeeds.
903  ///
904  /// If the caller intends to immediately open the file, then it is often
905  /// simpler to call static `ImageInput::open()`.
906  ///
907  /// @param filename
908  /// The name of an image file, or a file extension, or the name
909  /// of a file format. The filename is UTF-8 encoded.
910  ///
911  /// @param do_open
912  /// If `true`, not only create but also open the file.
913  ///
914  /// @param config
915  /// Optional pointer to an ImageSpec whose metadata contains
916  /// "configuration hints" for the ImageInput implementation.
917  ///
918  /// @param ioproxy
919  /// Optional pointer to an IOProxy to use (not supported by all
920  /// formats, see `supports("ioproxy")`). The caller retains
921  /// ownership of the proxy. If this is not supplied, it is still
922  /// possible to set the proxy with a call to `set_proxy()` prior
923  /// to `open()`.
924  ///
925  /// @param plugin_searchpath
926  /// An optional colon-separated list of directories to search
927  /// for OpenImageIO plugin DSO/DLL's.
928  ///
929  /// @returns
930  /// A `unique_ptr` that will close and free the ImageInput when
931  /// it exits scope or is reset. The pointer will be empty if the
932  /// required writer was not able to be created.
933  static unique_ptr create (string_view filename, bool do_open=false,
934  const ImageSpec *config=nullptr,
935  Filesystem::IOProxy* ioproxy = nullptr,
936  string_view plugin_searchpath = "");
937 
938  /// Create an ImageInput using a UTF-16 encoded wstring filename.
939  static unique_ptr create (const std::wstring& filename, bool do_open=false,
940  const ImageSpec *config=nullptr,
941  Filesystem::IOProxy* ioproxy = nullptr,
942  string_view plugin_searchpath = "") {
943  return create(Strutil::utf16_to_utf8(filename), do_open, config,
944  ioproxy, plugin_searchpath);
945  }
946 
947  // DEPRECATED(2.2): back compatible version
948  static unique_ptr create (const std::string& filename, bool do_open,
949  const ImageSpec *config,
950  string_view plugin_searchpath);
951  // DEPRECATED(2.1) This method should no longer be used, it is redundant.
952  static unique_ptr create (const std::string& filename,
953  const std::string& plugin_searchpath);
954 
955  /// @}
956 
957  // DEPRECATED(2.1)
958  static void destroy (ImageInput *x);
959 
960 protected:
961  ImageInput ();
962 public:
963  virtual ~ImageInput ();
964 
965  /// Return the name of the format implemented by this class.
966  virtual const char *format_name (void) const = 0;
967 
968  /// Given the name of a "feature", return whether this ImageInput
969  /// supports output of images with the given properties. Most queries
970  /// will simply return 0 for "doesn't support" and 1 for "supports it,"
971  /// but it is acceptable to have queries return other nonzero integers
972  /// to indicate varying degrees of support or limits (but should be
973  /// clearly documented as such).
974  ///
975  /// Feature names that ImageInput implementations are expected to
976  /// recognize include:
977  ///
978  /// - `"arbitrary_metadata"` : Does this format allow metadata with
979  /// arbitrary names and types?
980  ///
981  /// - `"exif"` :
982  /// Can this format store Exif camera data?
983  ///
984  /// - `"ioproxy"` :
985  /// Does this format reader support reading from an `IOProxy`?
986  ///
987  /// - `"iptc"` :
988  /// Can this format store IPTC data?
989  ///
990  /// - `"procedural"` :
991  /// Can this format create images without reading from a disk
992  /// file?
993  ///
994  /// - `"thumbnail"` :
995  /// Does this format reader support retrieving a reduced
996  /// resolution copy of the image via the `thumbnail()` method?
997  ///
998  /// This list of queries may be extended in future releases. Since this
999  /// can be done simply by recognizing new query strings, and does not
1000  /// require any new API entry points, addition of support for new
1001  /// queries does not break ``link compatibility'' with
1002  /// previously-compiled plugins.
1003  virtual int supports (string_view feature OIIO_MAYBE_UNUSED) const {
1004  return false;
1005  }
1006 
1007  /// Return true if the `filename` names a file of the type for this
1008  /// ImageInput. The implementation will try to determine this as
1009  /// efficiently as possible, in most cases much less expensively than
1010  /// doing a full `open()`. Note that there can be false positives: a
1011  /// file can appear to be of the right type (i.e., `valid_file()`
1012  /// returning `true`) but still fail a subsequent call to `open()`, such
1013  /// as if the contents of the file are truncated, nonsensical, or
1014  /// otherwise corrupted. The filename is UTF-8 encoded.
1015  ///
1016  /// @returns
1017  /// `true` upon success, or `false` upon failure.
1018  virtual bool valid_file (const std::string& filename) const;
1019 
1020  /// Check valid vile using a UTF-16 encoded wstring filename.
1021  bool valid_file (const std::wstring& filename) const {
1022  return valid_file(Strutil::utf16_to_utf8(filename));
1023  }
1024 
1025  /// Opens the file with given name and seek to the first subimage in the
1026  /// file. Various file attributes are put in `newspec` and a copy
1027  /// is also saved internally to the `ImageInput` (retrievable via
1028  /// `spec()`. From examining `newspec` or `spec()`, you can
1029  /// discern the resolution, if it's tiled, number of channels, native
1030  /// data format, and other metadata about the image.
1031  ///
1032  /// @param name
1033  /// Filename to open, UTF-8 encoded.
1034  ///
1035  /// @param newspec
1036  /// Reference to an ImageSpec in which to deposit a full
1037  /// description of the contents of the first subimage of the
1038  /// file.
1039  ///
1040  /// @returns
1041  /// `true` if the file was found and opened successfully.
1042  virtual bool open (const std::string& name, ImageSpec &newspec) = 0;
1043 
1044  /// Open the ImageInput using a UTF-16 encoded wstring filename.
1045  bool open (const std::wstring& name, ImageSpec &newspec) {
1046  return open(Strutil::utf16_to_utf8(name), newspec);
1047  }
1048 
1049  /// Open file with given name, similar to `open(name,newspec)`. The
1050  /// `config` is an ImageSpec giving requests or special instructions.
1051  /// ImageInput implementations are free to not respond to any such
1052  /// requests, so the default implementation is just to ignore config and
1053  /// call regular `open(name,newspec)`.
1054  ///
1055  /// @param name
1056  /// Filename to open, UTF-8 encoded.
1057  ///
1058  /// @param newspec
1059  /// Reference to an ImageSpec in which to deposit a full
1060  /// description of the contents of the first subimage of the
1061  /// file.
1062  ///
1063  /// @param config
1064  /// An ImageSpec whose metadata contains "configuration hints"
1065  /// for the ImageInput implementation.
1066  ///
1067  /// @returns
1068  /// `true` if the file was found and opened successfully.
1069  virtual bool open (const std::string& name, ImageSpec &newspec,
1070  const ImageSpec& config OIIO_MAYBE_UNUSED) {
1071  return open(name,newspec);
1072  }
1073  /// Open the ImageInput using a UTF-16 encoded wstring filename.
1074  bool open (const std::wstring& name, ImageSpec &newspec,
1075  const ImageSpec& config OIIO_MAYBE_UNUSED) {
1076  return open(name,newspec);
1077  }
1078 
1079  /// Return a reference to the image specification of the current
1080  /// subimage/MIPlevel. Note that the contents of the spec are invalid
1081  /// before `open()` or after `close()`, and may change with a call to
1082  /// `seek_subimage()`. It is thus not thread-safe, since the spec may
1083  /// change if another thread calls `seek_subimage`, or any of the
1084  /// `read_*()` functions that take explicit subimage/miplevel.
1085  virtual const ImageSpec &spec (void) const { return m_spec; }
1086 
1087  /// Return a full copy of the ImageSpec of the designated subimage and
1088  /// MIPlevel. This method is thread-safe, but it is potentially
1089  /// expensive, due to the work that needs to be done to fully copy an
1090  /// ImageSpec if there is lots of named metadata to allocate and copy.
1091  /// See also the less expensive `spec_dimensions()`. Errors (such as
1092  /// having requested a nonexistent subimage) are indicated by returning
1093  /// an ImageSpec with `format==TypeUnknown`.
1094  virtual ImageSpec spec (int subimage, int miplevel=0);
1095 
1096  /// Return a copy of the ImageSpec of the designated subimage and
1097  /// miplevel, but only the dimension and type fields. Just as with a
1098  /// call to `ImageSpec::copy_dimensions()`, neither the channel names
1099  /// nor any of the arbitrary named metadata will be copied, thus this is
1100  /// a relatively inexpensive operation if you don't need that
1101  /// information. It is guaranteed to be thread-safe. Errors (such as
1102  /// having requested a nonexistent subimage) are indicated by returning
1103  /// an ImageSpec with `format==TypeUnknown`.
1104  virtual ImageSpec spec_dimensions (int subimage, int miplevel=0);
1105 
1106  /// Retrieve a reduced-resolution ("thumbnail") version of the given
1107  /// subimage. It is guaranteed to be thread-safe.
1108  ///
1109  /// @param thumb
1110  /// A reference to an `ImageBuf` which will be overwritten with
1111  /// the thumbnail image.
1112  /// @param subimage
1113  /// The index of the subimage in the file whose thumbnail is to
1114  /// be retrieved.
1115  /// @returns
1116  /// `true` upon success, `false` if no thumbnail was available,
1117  /// or if this file format (or reader) does not support
1118  /// thumbnails.
1119  ///
1120  /// @note This method was added to OpenImageIO 2.3.
1121  virtual bool get_thumbnail(ImageBuf& thumb, int subimage) {
1122  return false;
1123  }
1124 
1125  /// Close an open ImageInput. The call to close() is not strictly
1126  /// necessary if the ImageInput is destroyed immediately afterwards,
1127  /// since it is required for the destructor to close if the file is
1128  /// still open.
1129  ///
1130  /// @returns
1131  /// `true` upon success, or `false` upon failure.
1132  virtual bool close () = 0;
1133 
1134  /// Returns the index of the subimage that is currently being read.
1135  /// The first subimage (or the only subimage, if there is just one)
1136  /// is number 0.
1137  virtual int current_subimage (void) const { return 0; }
1138 
1139  /// Returns the index of the MIPmap image that is currently being read.
1140  /// The highest-res MIP level (or the only level, if there is just
1141  /// one) is number 0.
1142  virtual int current_miplevel (void) const { return 0; }
1143 
1144  /// Seek to the given subimage and MIP-map level within the open image
1145  /// file. The first subimage of the file has index 0, the highest-
1146  /// resolution MIP level has index 0. The new subimage's vital
1147  /// statistics=may be retrieved by `this->spec()`. The reader is
1148  /// expected to give the appearance of random access to subimages and
1149  /// MIP levels -- in other words, if it can't randomly seek to the given
1150  /// subimage/level, it should transparently close, reopen, and
1151  /// sequentially read through prior subimages and levels.
1152  ///
1153  /// @returns
1154  /// `true` upon success, or `false` upon failure. A failure may
1155  /// indicate that no such subimage or MIP level exists in the
1156  /// file.
1157  virtual bool seek_subimage (int subimage, int miplevel) {
1158  // Default implementation assumes no support for subimages or
1159  // mipmaps, so there is no work to do.
1160  return subimage == current_subimage() && miplevel == current_miplevel();
1161  }
1162 
1163  // Old version for backwards-compatibility: pass reference to newspec.
1164  // Some day this will be deprecated.
1165  bool seek_subimage (int subimage, int miplevel, ImageSpec &newspec) {
1166  bool ok = seek_subimage (subimage, miplevel);
1167  if (ok)
1168  newspec = spec();
1169  return ok;
1170  }
1171 
1172  // DEPRECATED(2.1)
1173  // Seek to the given subimage -- backwards-compatible call that
1174  // doesn't worry about MIP-map levels at all.
1175  bool seek_subimage (int subimage, ImageSpec &newspec) {
1176  return seek_subimage (subimage, 0 /* miplevel */, newspec);
1177  }
1178 
1179  /// @{
1180  /// @name Reading pixels
1181  ///
1182  /// Common features of all the `read` methods:
1183  ///
1184  /// * The `format` parameter describes the data type of the `data[]`
1185  /// buffer. The read methods automatically convert the data from the
1186  /// data type it is stored in the file into the `format` of the `data`
1187  /// buffer. If `format` is `TypeUnknown` it will just copy pixels of
1188  /// file's native data layout (including, possibly, per-channel data
1189  /// formats as specified by the ImageSpec's `channelformats` field).
1190  ///
1191  /// * The `stride` values describe the layout of the `data` buffer:
1192  /// `xstride` is the distance in bytes between successive pixels
1193  /// within each scanline. `ystride` is the distance in bytes between
1194  /// successive scanlines. For volumetric images `zstride` is the
1195  /// distance in bytes between successive "volumetric planes". Strides
1196  /// set to the special value `AutoStride` imply contiguous data, i.e.,
1197  ///
1198  /// xstride = format.size() * nchannels
1199  /// ystride = xstride * width
1200  /// zstride = ystride * height
1201  ///
1202  /// * Any *range* parameters (such as `ybegin` and `yend`) describe a
1203  /// "half open interval", meaning that `begin` is the first item and
1204  /// `end` is *one past the last item*. That means that the number of
1205  /// items is `end - begin`.
1206  ///
1207  /// * For ordinary 2D (non-volumetric) images, any `z` or `zbegin`
1208  /// coordinates should be 0 and any `zend` should be 1, indicating
1209  /// that only a single image "plane" exists.
1210  ///
1211  /// * Some read methods take a channel range [chbegin,chend) to allow
1212  /// reading of a contiguous subset of channels (chbegin=0,
1213  /// chend=spec.nchannels reads all channels).
1214  ///
1215  /// * ImageInput readers are expected to give the appearance of random
1216  /// access -- in other words, if it can't randomly seek to the given
1217  /// scanline or tile, it should transparently close, reopen, and
1218  /// sequentially read through prior scanlines.
1219  ///
1220  /// * All read functions return `true` for success, `false` for failure
1221  /// (after which a call to `geterror()` may retrieve a specific error
1222  /// message).
1223  ///
1224 
1225  /// Read the scanline that includes pixels (*,y,z) from the "current"
1226  /// subimage and MIP level. The `xstride` value gives the distance
1227  /// between successive pixels (in bytes). Strides set to `AutoStride`
1228  /// imply "contiguous" data.
1229  ///
1230  /// @note This variety of `read_scanline` is not re-entrant nor
1231  /// thread-safe. If you require concurrent reads to the same open
1232  /// ImageInput, you should use `read_scanlines` that has the `subimage`
1233  /// and `miplevel` passed explicitly.
1234  ///
1235  /// @param y/z The y & z coordinates of the scanline. For 2D
1236  /// images, z should be 0.
1237  /// @param format A TypeDesc describing the type of `data`.
1238  /// @param data Pointer to the pixel data buffer.
1239  /// @param xstride The distance in bytes between successive
1240  /// pixels in `data` (or `AutoStride`).
1241  /// @returns `true` upon success, or `false` upon failure.
1242  virtual bool read_scanline (int y, int z, TypeDesc format, void *data,
1243  stride_t xstride=AutoStride);
1244 
1245  /// Simple read_scanline reads into contiguous float pixels.
1246  bool read_scanline (int y, int z, float *data) {
1247  return read_scanline (y, z, TypeFloat, data);
1248  }
1249 
1250  /// Read multiple scanlines that include pixels (*,y,z) for all ybegin
1251  /// <= y < yend in the specified subimage and mip level, into `data`,
1252  /// using the strides given and converting to the requested data
1253  /// `format` (TypeUnknown indicates no conversion, just copy native data
1254  /// types). Only channels [chbegin,chend) will be read/copied
1255  /// (chbegin=0, chend=spec.nchannels reads all channels, yielding
1256  /// equivalent behavior to the simpler variant of `read_scanlines`).
1257  ///
1258  /// This version of read_scanlines, because it passes explicit
1259  /// subimage/miplevel, does not require a separate call to
1260  /// seek_subimage, and is guaranteed to be thread-safe against other
1261  /// concurrent calls to any of the read_* methods that take an explicit
1262  /// subimage/miplevel (but not against any other ImageInput methods).
1263  ///
1264  /// @param subimage The subimage to read from (starting with 0).
1265  /// @param miplevel The MIP level to read (0 is the highest
1266  /// resolution level).
1267  /// @param ybegin/yend The y range of the scanlines being passed.
1268  /// @param z The z coordinate of the scanline.
1269  /// @param chbegin/chend
1270  /// The channel range to read.
1271  /// @param format A TypeDesc describing the type of `data`.
1272  /// @param data Pointer to the pixel data.
1273  /// @param xstride/ystride
1274  /// The distance in bytes between successive pixels
1275  /// and scanlines (or `AutoStride`).
1276  /// @returns `true` upon success, or `false` upon failure.
1277  ///
1278  /// @note This call was changed for OpenImageIO 2.0 to include the
1279  /// explicit subimage and miplevel parameters. The previous
1280  /// versions, which lacked subimage and miplevel parameters (thus
1281  /// were dependent on a prior call to `seek_subimage`) are
1282  /// considered deprecated.
1283  virtual bool read_scanlines (int subimage, int miplevel,
1284  int ybegin, int yend, int z,
1285  int chbegin, int chend,
1286  TypeDesc format, void *data,
1287  stride_t xstride=AutoStride,
1288  stride_t ystride=AutoStride);
1289 
1290 #ifndef OIIO_DOXYGEN
1291  // DEPRECATED versions of read_scanlines (pre-1.9 OIIO). These will
1292  // eventually be removed. Try to replace these calls with ones to the
1293  // new variety of read_scanlines that takes an explicit subimage and
1294  // miplevel. These old versions are NOT THREAD-SAFE.
1295  bool read_scanlines (int ybegin, int yend, int z,
1296  TypeDesc format, void *data,
1297  stride_t xstride=AutoStride,
1298  stride_t ystride=AutoStride);
1299  bool read_scanlines (int ybegin, int yend, int z,
1300  int chbegin, int chend,
1301  TypeDesc format, void *data,
1302  stride_t xstride=AutoStride,
1303  stride_t ystride=AutoStride);
1304 #endif
1305 
1306  /// Read the tile whose upper-left origin is (x,y,z) into `data[]`,
1307  /// converting if necessary from the native data format of the file into
1308  /// the `format` specified. The stride values give the data spacing of
1309  /// adjacent pixels, scanlines, and volumetric slices (measured in
1310  /// bytes). Strides set to AutoStride imply 'contiguous' data in the
1311  /// shape of a full tile, i.e.,
1312  ///
1313  /// xstride = format.size() * spec.nchannels
1314  /// ystride = xstride * spec.tile_width
1315  /// zstride = ystride * spec.tile_height
1316  ///
1317  /// @note This variety of `read_tile` is not re-entrant nor thread-safe.
1318  /// If you require concurrent reads to the same open ImageInput, you
1319  /// should use `read_tiles()` that has the `subimage` and `miplevel`
1320  /// passed explicitly.
1321  ///
1322  /// @param x/y/z The upper left coordinate of the tile being passed.
1323  /// @param format A TypeDesc describing the type of `data`.
1324  /// @param data Pointer to the pixel data.
1325  /// @param xstride/ystride/zstride
1326  /// The distance in bytes between successive pixels,
1327  /// scanlines, and image planes (or `AutoStride` to
1328  /// indicate a "contiguous" single tile).
1329  /// @returns `true` upon success, or `false` upon failure.
1330  ///
1331  /// @note This call will fail if the image is not tiled, or if (x,y,z)
1332  /// is not the upper left corner coordinates of a tile.
1333  virtual bool read_tile (int x, int y, int z, TypeDesc format,
1334  void *data, stride_t xstride=AutoStride,
1335  stride_t ystride=AutoStride,
1336  stride_t zstride=AutoStride);
1337 
1338  /// Simple read_tile reads into contiguous float pixels.
1339  bool read_tile (int x, int y, int z, float *data) {
1340  return read_tile (x, y, z, TypeDesc::FLOAT, data,
1342  }
1343 
1344  /// Read the block of multiple tiles that include all pixels in
1345  ///
1346  /// [xbegin,xend) X [ybegin,yend) X [zbegin,zend)
1347  ///
1348  /// This is analogous to calling `read_tile(x,y,z,...)` for each tile
1349  /// in turn (but for some file formats, reading multiple tiles may allow
1350  /// it to read more efficiently or in parallel).
1351  ///
1352  /// The begin/end pairs must correctly delineate tile boundaries, with
1353  /// the exception that it may also be the end of the image data if the
1354  /// image resolution is not a whole multiple of the tile size. The
1355  /// stride values give the data spacing of adjacent pixels, scanlines,
1356  /// and volumetric slices (measured in bytes). Strides set to AutoStride
1357  /// imply contiguous data in the shape of the [begin,end) region, i.e.,
1358  ///
1359  /// xstride = format.size() * spec.nchannels
1360  /// ystride = xstride * (xend-xbegin)
1361  /// zstride = ystride * (yend-ybegin)
1362  ///
1363  /// This version of read_tiles, because it passes explicit subimage and
1364  /// miplevel, does not require a separate call to seek_subimage, and is
1365  /// guaranteed to be thread-safe against other concurrent calls to any
1366  /// of the read_* methods that take an explicit subimage/miplevel (but
1367  /// not against any other ImageInput methods).
1368  ///
1369  /// @param subimage The subimage to read from (starting with 0).
1370  /// @param miplevel The MIP level to read (0 is the highest
1371  /// resolution level).
1372  /// @param xbegin/xend The x range of the pixels covered by the group
1373  /// of tiles being read.
1374  /// @param ybegin/yend The y range of the pixels covered by the tiles.
1375  /// @param zbegin/zend The z range of the pixels covered by the tiles
1376  /// (for a 2D image, zbegin=0 and zend=1).
1377  /// @param chbegin/chend
1378  /// The channel range to read.
1379  /// @param format A TypeDesc describing the type of `data`.
1380  /// @param data Pointer to the pixel data.
1381  /// @param xstride/ystride/zstride
1382  /// The distance in bytes between successive pixels,
1383  /// scanlines, and image planes (or `AutoStride`).
1384  /// @returns `true` upon success, or `false` upon failure.
1385  ///
1386  /// @note The call will fail if the image is not tiled, or if the pixel
1387  /// ranges do not fall along tile (or image) boundaries, or if it is not
1388  /// a valid tile range.
1389  virtual bool read_tiles (int subimage, int miplevel, int xbegin, int xend,
1390  int ybegin, int yend, int zbegin, int zend,
1391  int chbegin, int chend, TypeDesc format, void *data,
1392  stride_t xstride=AutoStride, stride_t ystride=AutoStride,
1393  stride_t zstride=AutoStride);
1394 
1395 #ifndef OIIO_DOXYGEN
1396  // DEPRECATED versions of read_tiles (pre-1.9 OIIO). These will
1397  // eventually be removed. Try to replace these calls with ones to the
1398  // new variety of read_tiles that takes an explicit subimage and
1399  // miplevel. These old versions are NOT THREAD-SAFE.
1400  bool read_tiles (int xbegin, int xend, int ybegin, int yend,
1401  int zbegin, int zend, TypeDesc format, void *data,
1402  stride_t xstride=AutoStride, stride_t ystride=AutoStride,
1403  stride_t zstride=AutoStride);
1404  bool read_tiles (int xbegin, int xend, int ybegin, int yend,
1405  int zbegin, int zend, int chbegin, int chend,
1406  TypeDesc format, void *data, stride_t xstride=AutoStride,
1407  stride_t ystride=AutoStride, stride_t zstride=AutoStride);
1408 #endif
1409 
1410  /// Read the entire image of `spec.width x spec.height x spec.depth`
1411  /// pixels into a buffer with the given strides and in the desired
1412  /// data format.
1413  ///
1414  /// Depending on the spec, this will read either all tiles or all
1415  /// scanlines. Assume that data points to a layout in row-major order.
1416  ///
1417  /// This version of read_image, because it passes explicit subimage and
1418  /// miplevel, does not require a separate call to seek_subimage, and is
1419  /// guaranteed to be thread-safe against other concurrent calls to any
1420  /// of the read_* methods that take an explicit subimage/miplevel (but
1421  /// not against any other ImageInput methods).
1422  ///
1423  /// Because this may be an expensive operation, a progress callback
1424  /// may be passed. Periodically, it will be called as follows:
1425  ///
1426  /// progress_callback (progress_callback_data, float done);
1427  ///
1428  /// where `done` gives the portion of the image (between 0.0 and 1.0)
1429  /// that has been written thus far.
1430  ///
1431  /// @param subimage The subimage to read from (starting with 0).
1432  /// @param miplevel The MIP level to read (0 is the highest
1433  /// resolution level).
1434  /// @param chbegin/chend
1435  /// The channel range to read.
1436  /// @param format A TypeDesc describing the type of `data`.
1437  /// @param data Pointer to the pixel data.
1438  /// @param xstride/ystride/zstride
1439  /// The distance in bytes between successive pixels,
1440  /// scanlines, and image planes (or `AutoStride`).
1441  /// @param progress_callback/progress_callback_data
1442  /// Optional progress callback.
1443  /// @returns `true` upon success, or `false` upon failure.
1444  virtual bool read_image (int subimage, int miplevel,
1445  int chbegin, int chend,
1446  TypeDesc format, void *data,
1447  stride_t xstride=AutoStride,
1448  stride_t ystride=AutoStride,
1449  stride_t zstride=AutoStride,
1450  ProgressCallback progress_callback=NULL,
1451  void *progress_callback_data=NULL);
1452 
1453 #ifndef OIIO_DOXYGEN
1454  // DEPRECATED versions of read_image (pre-1.9 OIIO). These will
1455  // eventually be removed. Try to replace these calls with ones to the
1456  // new variety of read_image that takes an explicit subimage and
1457  // miplevel. These old versions are NOT THREAD-SAFE.
1458  virtual bool read_image (TypeDesc format, void *data,
1459  stride_t xstride=AutoStride,
1460  stride_t ystride=AutoStride,
1461  stride_t zstride=AutoStride,
1462  ProgressCallback progress_callback=NULL,
1463  void *progress_callback_data=NULL);
1464  virtual bool read_image (int chbegin, int chend,
1465  TypeDesc format, void *data,
1466  stride_t xstride=AutoStride,
1467  stride_t ystride=AutoStride,
1468  stride_t zstride=AutoStride,
1469  ProgressCallback progress_callback=NULL,
1470  void *progress_callback_data=NULL);
1471  bool read_image (float *data) {
1472  return read_image (TypeDesc::FLOAT, data);
1473  }
1474 #endif
1475 
1476  /// Read deep scanlines containing pixels (*,y,z), for all y in the
1477  /// range [ybegin,yend) into `deepdata`. This will fail if it is not a
1478  /// deep file.
1479  ///
1480  /// @param subimage The subimage to read from (starting with 0).
1481  /// @param miplevel The MIP level to read (0 is the highest
1482  /// resolution level).
1483  /// @param chbegin/chend
1484  /// The channel range to read.
1485  /// @param ybegin/yend The y range of the scanlines being passed.
1486  /// @param z The z coordinate of the scanline.
1487  /// @param deepdata A `DeepData` object into which the data for
1488  /// these scanlines will be placed.
1489  /// @returns `true` upon success, or `false` upon failure.
1490  virtual bool read_native_deep_scanlines (int subimage, int miplevel,
1491  int ybegin, int yend, int z,
1492  int chbegin, int chend,
1493  DeepData &deepdata);
1494 
1495  /// Read into `deepdata` the block of native deep data tiles that
1496  /// include all pixels and channels specified by pixel range.
1497  ///
1498  /// @param subimage The subimage to read from (starting with 0).
1499  /// @param miplevel The MIP level to read (0 is the highest
1500  /// resolution level).
1501  /// @param xbegin/xend The x range of the pixels covered by the group
1502  /// of tiles being read.
1503  /// @param ybegin/yend The y range of the pixels covered by the tiles.
1504  /// @param zbegin/zend The z range of the pixels covered by the tiles
1505  /// (for a 2D image, zbegin=0 and zend=1).
1506  /// @param chbegin/chend
1507  /// The channel range to read.
1508  /// @param deepdata A `DeepData` object into which the data for
1509  /// these tiles will be placed.
1510  /// @returns `true` upon success, or `false` upon failure.
1511  ///
1512  /// @note The call will fail if the image is not tiled, or if the pixel
1513  /// ranges do not fall along tile (or image) boundaries, or if it is not
1514  /// a valid tile range.
1515  virtual bool read_native_deep_tiles (int subimage, int miplevel,
1516  int xbegin, int xend,
1517  int ybegin, int yend,
1518  int zbegin, int zend,
1519  int chbegin, int chend,
1520  DeepData &deepdata);
1521 
1522  /// Read the entire deep data image of spec.width x spec.height x
1523  /// spec.depth pixels, all channels, into `deepdata`.
1524  ///
1525  /// @param subimage The subimage to read from (starting with 0).
1526  /// @param miplevel The MIP level to read (0 is the highest
1527  /// resolution level).
1528  /// @param deepdata A `DeepData` object into which the data for
1529  /// the image will be placed.
1530  /// @returns `true` upon success, or `false` upon failure.
1531  virtual bool read_native_deep_image (int subimage, int miplevel,
1532  DeepData &deepdata);
1533 
1534 #ifndef OIIO_DOXYGEN
1535  // DEPRECATED(1.9), Now just used for back compatibility:
1536  bool read_native_deep_scanlines (int ybegin, int yend, int z,
1537  int chbegin, int chend, DeepData &deepdata) {
1538  return read_native_deep_scanlines (current_subimage(), current_miplevel(),
1539  ybegin, yend, z,
1540  chbegin, chend, deepdata);
1541  }
1542  bool read_native_deep_tiles (int xbegin, int xend, int ybegin, int yend,
1543  int zbegin, int zend, int chbegin, int chend,
1544  DeepData &deepdata) {
1545  return read_native_deep_tiles (current_subimage(), current_miplevel(),
1546  xbegin, xend, ybegin, yend,
1547  zbegin, zend, chbegin, chend, deepdata);
1548  }
1550  return read_native_deep_image (current_subimage(), current_miplevel(),
1551  deepdata);
1552  }
1553 #endif
1554 
1555  /// @}
1556 
1557  /// @{
1558  /// @name Reading native pixels -- implementation overloads
1559  ///
1560  /// @note read_native_* methods are usually not directly called by user
1561  /// code (except for read_native_deep_* varieties). These are the
1562  /// methods that are overloaded by the ImageInput subclasses that
1563  /// implement the individual file format readers.
1564  //
1565  // The read_native_* methods always read the "native" data types
1566  // (including per-channel data types) and assume that `data` points to
1567  // contiguous memory (no non-default strides). In contrast, the
1568  // read_scanline/scanlines/tile/tiles handle data type translation and
1569  // arbitrary strides.
1570  //
1571  // The read_native_* methods take an explicit subimage and miplevel, and
1572  // thus do not require a prior call to seek_subimage (and therefore no
1573  // saved state). They are all required to be thread-safe when called
1574  // concurrently with any other read_native_* call or with the varieties
1575  // of read_tiles() that also takes an explicit subimage and miplevel
1576  // parameter.
1577  //
1578  // As far as format-reading ImageInput subclasses are concerned, the
1579  // only truly required overloads are read_native_scanline (always) and
1580  // read_native_tile (only for formats that support tiles). The other
1581  // varieties are special cases, for example if the particular format is
1582  // able to efficiently read multiple scanlines or tiles at once, and if
1583  // the subclass does not provide overloads, the base class
1584  // implementaiton will be used instead, which is implemented by reducing
1585  // the operation to multiple calls to read_scanline or read_tile.
1586 
1587  /// Read a single scanline (all channels) of native data into contiguous
1588  /// memory.
1589  virtual bool read_native_scanline (int subimage, int miplevel,
1590  int y, int z, void *data) = 0;
1591  /// Read a range of scanlines (all channels) of native data into
1592  /// contiguous memory.
1593  virtual bool read_native_scanlines (int subimage, int miplevel,
1594  int ybegin, int yend, int z,
1595  void *data);
1596  /// Read a range of scanlines (with optionally a subset of channels) of
1597  /// native data into contiguous memory.
1598  virtual bool read_native_scanlines (int subimage, int miplevel,
1599  int ybegin, int yend, int z,
1600  int chbegin, int chend, void *data);
1601 
1602  /// Read a single tile (all channels) of native data into contiguous
1603  /// memory. The base class read_native_tile fails. A format reader that
1604  /// supports tiles MUST overload this virtual method that reads a single
1605  /// tile (all channels).
1606  virtual bool read_native_tile (int subimage, int miplevel,
1607  int x, int y, int z, void *data);
1608 
1609  /// Read multiple tiles (all channels) of native data into contigious
1610  /// memory. A format reader that supports reading multiple tiles at once
1611  /// (in a way that's more efficient than reading the tiles one at a
1612  /// time) is advised (but not required) to overload this virtual method.
1613  /// If an ImageInput subclass does not overload this, the default
1614  /// implementation here is simply to loop over the tiles, calling the
1615  /// single-tile read_native_tile() for each one.
1616  virtual bool read_native_tiles (int subimage, int miplevel,
1617  int xbegin, int xend, int ybegin, int yend,
1618  int zbegin, int zend, void *data);
1619 
1620  /// Read multiple tiles (potentially a subset of channels) of native
1621  /// data into contigious memory. A format reader that supports reading
1622  /// multiple tiles at once, and can handle a channel subset while doing
1623  /// so, is advised (but not required) to overload this virtual method.
1624  /// If an ImageInput subclass does not overload this, the default
1625  /// implementation here is simply to loop over the tiles, calling the
1626  /// single-tile read_native_tile() for each one (and copying carefully
1627  /// to handle the channel subset issues).
1628  virtual bool read_native_tiles (int subimage, int miplevel,
1629  int xbegin, int xend, int ybegin, int yend,
1630  int zbegin, int zend,
1631  int chbegin, int chend, void *data);
1632  /// @}
1633 
1634 
1635  // General message passing between client and image input server. This
1636  // is currently undefined and is reserved for future use.
1637  virtual int send_to_input (const char *format, ...);
1638  int send_to_client (const char *format, ...);
1639 
1640  /// Set an IOProxy for this reader. This must be called prior to
1641  /// `open()`, and only for readers that support them
1642  /// (`supports("ioproxy")`). The caller retains ownership of the proxy.
1643  ///
1644  /// @returns `true` for success, `false` for failure.
1645  virtual bool set_ioproxy (Filesystem::IOProxy* ioproxy) {
1646  return (ioproxy == nullptr);
1647  }
1648 
1649  /// Is there a pending error message waiting to be retrieved, that
1650  /// resulted from an ImageInput API call made by the this thread?
1651  ///
1652  /// Note that any `error()` calls issued are thread-specific, and the
1653  /// `geterror()/has_error()` are expected to be called by the same
1654  /// thread that called whichever API function encountered an error.
1655  bool has_error() const;
1656 
1657  /// Return the text of all pending error messages issued against this
1658  /// ImageInput by the calling thread, and clear the pending error
1659  /// message unless `clear` is false. If no error message is pending, it
1660  /// will return an empty string.
1661  ///
1662  /// Note that any `error()` calls issued are thread-specific, and the
1663  /// `geterror()/has_error()` are expected to be called by the same
1664  /// thread that called whichever API function encountered an error.
1665  std::string geterror(bool clear = true) const;
1666 
1667  /// Error reporting for the plugin implementation: call this with
1668  /// Strutil::format-like arguments. It is not necessary to have the
1669  /// error message contain a trailing newline.
1670  /// Use with caution! Some day this will change to be fmt-like rather
1671  /// than printf-like.
1672  template<typename... Args>
1674  void error(const char* fmt, const Args&... args) const {
1675  append_error(Strutil::format (fmt, args...));
1676  }
1677 
1678  /// Error reporting for the plugin implementation: call this with
1679  /// printf-like arguments. It is not necessary to have the error message
1680  /// contain a trailing newline.
1681  template<typename... Args>
1682  void errorf(const char* fmt, const Args&... args) const {
1683  append_error(Strutil::sprintf (fmt, args...));
1684  }
1685 
1686  /// Error reporting for the plugin implementation: call this with
1687  /// std::format-like arguments. It is not necessary to have the error
1688  /// message contain a trailing newline.
1689  template<typename... Args>
1690  void errorfmt(const char* fmt, const Args&... args) const {
1691  append_error(Strutil::fmt::format (fmt, args...));
1692  }
1693 
1694  // Error reporting for the plugin implementation: call this with
1695  // std::format-like arguments. It is not necessary to have the
1696  // error message contain a trailing newline.
1697  template<typename... Args>
1698  OIIO_DEPRECATED("use `errorfmt` instead")
1699  void fmterror(const char* fmt, const Args&... args) const {
1700  append_error(Strutil::fmt::format (fmt, args...));
1701  }
1702 
1703  /// Set the threading policy for this ImageInput, controlling the
1704  /// maximum amount of parallelizing thread "fan-out" that might occur
1705  /// during large read operations. The default of 0 means that the global
1706  /// `attribute("threads")` value should be used (which itself defaults
1707  /// to using as many threads as cores; see Section `Global Attributes`_).
1708  ///
1709  /// The main reason to change this value is to set it to 1 to indicate
1710  /// that the calling thread should do all the work rather than spawning
1711  /// new threads. That is probably the desired behavior in situations
1712  /// where the calling application has already spawned multiple worker
1713  /// threads.
1714  void threads(int n);
1715 
1716  /// Retrieve the current thread-spawning policy.
1717  /// @see `threads(int)`
1718  int threads() const;
1719 
1720  /// There is a (hidden) internal recursive mutex to each ImageInput
1721  /// that can be used by the II to enforce thread safety. This is exposed
1722  /// via the obvious lock()/unlock()/try_lock() semantics.
1723  void lock() const;
1724  void unlock() const;
1725  bool try_lock() const;
1726 
1727  /// The presence of lock() and unlock() establish an ImageInput itself
1728  /// as having the BasicLockable concept and therefore can be used by
1729  /// std::lock_guard.
1730  typedef std::lock_guard<const ImageInput&> lock_guard;
1731 
1732  // Custom new and delete to ensure that allocations & frees happen in
1733  // the OpenImageIO library, not in the app or plugins (because Windows).
1734  void* operator new (size_t size);
1735  void operator delete (void *ptr);
1736 
1737  /// Call signature of a function that creates and returns an
1738  /// `ImageInput*`.
1739  typedef ImageInput* (*Creator)();
1740 
1741 protected:
1742  ImageSpec m_spec; // format spec of the current open subimage/MIPlevel
1743  // BEWARE using m_spec directly -- not thread-safe
1744 
1745 private:
1746  // PIMPL idiom -- this lets us hide details of the internals of the
1747  // ImageInput parent class so that changing them does not break the
1748  // ABI.
1749  class Impl;
1750  static void impl_deleter(Impl*);
1751  std::unique_ptr<Impl, decltype(&impl_deleter)> m_impl;
1752 
1753  void append_error(string_view message) const; // add to error message
1754  // Deprecated:
1755  OIIO_DEPRECATED("Deprecated")
1756  static unique_ptr create (const std::string& filename, bool do_open,
1757  const std::string& plugin_searchpath);
1758 };
1759 
1760 
1761 
1762 
1763 /// ImageOutput abstracts the writing of an image file in a file
1764 /// format-agnostic manner.
1765 ///
1766 /// Users don't directly declare these. Instead, you call the `create()`
1767 /// static method, which will return a `unique_ptr` holding a subclass of
1768 /// ImageOutput that implements writing the particular format.
1769 ///
1771 public:
1772  /// unique_ptr to an ImageOutput.
1773  using unique_ptr = std::unique_ptr<ImageOutput>;
1774 
1775  /// @{
1776  /// @name Creating an ImageOutput
1777 
1778  /// Create an `ImageOutput` that can be used to write an image file.
1779  /// The type of image file (and hence, the particular subclass of
1780  /// `ImageOutput` returned, and the plugin that contains its methods) is
1781  /// inferred from the name, if it appears to be a full filename, or it
1782  /// may also name the format.
1783  ///
1784  /// @param filename
1785  /// The name of the file format (e.g., "openexr"), a file
1786  /// extension (e.g., "exr"), or a filename from which the the
1787  /// file format can be inferred from its extension (e.g.,
1788  /// "hawaii.exr"). The filename is UTF-8 encoded.
1789  ///
1790  /// @param plugin_searchpath
1791  /// An optional colon-separated list of directories to search
1792  /// for OpenImageIO plugin DSO/DLL's.
1793  ///
1794  /// @param ioproxy
1795  /// Optional pointer to an IOProxy to use (not supported by all
1796  /// formats, see `supports("ioproxy")`). The caller retains
1797  /// ownership of the proxy.
1798  ///
1799  /// @returns
1800  /// A `unique_ptr` that will close and free the ImageOutput when
1801  /// it exits scope or is reset. The pointer will be empty if the
1802  /// required writer was not able to be created.
1803  static unique_ptr create (string_view filename,
1804  Filesystem::IOProxy* ioproxy = nullptr,
1805  string_view plugin_searchpath = "");
1806 
1807  /// Create an ImageOutput using a UTF-16 encoded wstring filename and
1808  /// plugin searchpath.
1809  static unique_ptr create (const std::wstring& filename,
1810  Filesystem::IOProxy* ioproxy = nullptr,
1811  const std::wstring& plugin_searchpath = {}) {
1812  return create(Strutil::utf16_to_utf8(filename), ioproxy,
1813  Strutil::utf16_to_utf8(plugin_searchpath));
1814  }
1815 
1816  // DEPRECATED(2.2)
1817  static unique_ptr create (const std::string &filename,
1818  const std::string &plugin_searchpath);
1819 
1820  /// @}
1821 
1822  // @deprecated
1823  static void destroy (ImageOutput *x);
1824 
1825 protected:
1826  ImageOutput ();
1827 public:
1828  virtual ~ImageOutput ();
1829 
1830  /// Return the name of the format implemented by this class.
1831  virtual const char *format_name (void) const = 0;
1832 
1833  // Override these functions in your derived output class
1834  // to inform the client which formats are supported
1835 
1836  /// @{
1837  /// @name Opening and closing files for output
1838 
1839  /// Given the name of a "feature", return whether this ImageOutput
1840  /// supports output of images with the given properties. Most queries
1841  /// will simply return 0 for "doesn't support" and 1 for "supports it,"
1842  /// but it is acceptable to have queries return other nonzero integers
1843  /// to indicate varying degrees of support or limits (but should be
1844  /// clearly documented as such).
1845  ///
1846  /// Feature names that ImageOutput implementations are expected to
1847  /// recognize include:
1848  ///
1849  /// - `"tiles"` :
1850  /// Is this format writer able to write tiled images?
1851  ///
1852  /// - `"rectangles"` :
1853  /// Does this writer accept arbitrary rectangular pixel regions
1854  /// (via `write_rectangle()`)? Returning 0 indicates that
1855  /// pixels must be transmitted via `write_scanline()` (if
1856  /// scanline-oriented) or `write_tile()` (if tile-oriented, and
1857  /// only if `supports("tiles")` returns true).
1858  ///
1859  /// - `"random_access"` :
1860  /// May tiles or scanlines be written in any order (0 indicates
1861  /// that they *must* be in successive order)?
1862  ///
1863  /// - `"multiimage"` :
1864  /// Does this format support multiple subimages within a file?
1865  ///
1866  /// - `"appendsubimage"` :
1867  /// Does this format support multiple subimages that can be
1868  /// successively appended at will via
1869  /// `open(name,spec,AppendSubimage)`? A value of 0 means that
1870  /// the format requires pre-declaring the number and
1871  /// specifications of the subimages when the file is first
1872  /// opened, with `open(name,subimages,specs)`.
1873  ///
1874  /// - `"mipmap"` :
1875  /// Does this format support multiple resolutions for an
1876  /// image/subimage?
1877  ///
1878  /// - `"volumes"` :
1879  /// Does this format support "3D" pixel arrays (a.k.a. volume
1880  /// images)?
1881  ///
1882  /// - `"alpha"` :
1883  /// Can this format support an alpha channel?
1884  ///
1885  /// - `"nchannels"` :
1886  /// Can this format support arbitrary number of channels (beyond RGBA)?
1887  ///
1888  /// - `"rewrite"` :
1889  /// May the same scanline or tile be sent more than once?
1890  /// Generally, this is true for plugins that implement
1891  /// interactive display, rather than a saved image file.
1892  ///
1893  /// - `"empty"` :
1894  /// Does this plugin support passing a NULL data pointer to the
1895  /// various `write` routines to indicate that the entire data
1896  /// block is composed of pixels with value zero? Plugins that
1897  /// support this achieve a speedup when passing blank scanlines
1898  /// or tiles (since no actual data needs to be transmitted or
1899  /// converted).
1900  ///
1901  /// - `"channelformats"` :
1902  /// Does this format writer support per-channel data formats,
1903  /// respecting the ImageSpec's `channelformats` field? If not,
1904  /// it only accepts a single data format for all channels and
1905  /// will ignore the `channelformats` field of the spec.
1906  ///
1907  /// - `"displaywindow"` :
1908  /// Does the format support display ("full") windows distinct
1909  /// from the pixel data window?
1910  ///
1911  /// - `"origin"` :
1912  /// Does the image format support specifying a pixel window
1913  /// origin (i.e., nonzero ImageSpec `x`, `y`, `z`)?
1914  ///
1915  /// - `"negativeorigin"` :
1916  /// Does the image format allow data and display window origins
1917  /// (i.e., ImageSpec `x`, `y`, `z`, `full_x`, `full_y`, `full_z`)
1918  /// to have negative values?
1919  ///
1920  /// - `"deepdata"` :
1921  /// Does the image format allow "deep" data consisting of
1922  /// multiple values per pixel (and potentially a differing number
1923  /// of values from pixel to pixel)?
1924  ///
1925  /// - `"arbitrary_metadata"` :
1926  /// Does the image file format allow metadata with arbitrary
1927  /// names (and either arbitrary, or a reasonable set of, data
1928  /// types)? (Versus the file format supporting only a fixed list
1929  /// of specific metadata names/values.)
1930  ///
1931  /// - `"exif"`
1932  /// Does the image file format support Exif camera data (either
1933  /// specifically, or via arbitrary named metadata)?
1934  ///
1935  /// - `"iptc"`
1936  /// Does the image file format support IPTC data (either
1937  /// specifically, or via arbitrary named metadata)?
1938  ///
1939  /// - `"ioproxy"`
1940  /// Does the image file format support writing to an `IOProxy`?
1941  ///
1942  /// - `"procedural"` :
1943  /// Is this a purely procedural output that doesn't write an
1944  /// actual file?
1945  ///
1946  /// - `"thumbnail"` :
1947  /// Does this format writer support adding a reduced resolution
1948  /// copy of the image via the `thumbnail()` method?
1949  ///
1950  /// - `"thumbnail_after_write"` :
1951  /// Does this format writer support calling `thumbnail()` after
1952  /// the scanlines or tiles have been specified? (Supporting
1953  /// `"thumbnail"` but not `"thumbnail_after_write"` means that any
1954  /// thumbnail must be supplied immediately after `open()`, prior
1955  /// to any of the `write_*()` calls.)
1956  ///
1957  /// This list of queries may be extended in future releases. Since this
1958  /// can be done simply by recognizing new query strings, and does not
1959  /// require any new API entry points, addition of support for new
1960  /// queries does not break ``link compatibility'' with
1961  /// previously-compiled plugins.
1962  virtual int supports (string_view feature OIIO_MAYBE_UNUSED) const {
1963  return false;
1964  }
1965 
1966  /// Modes passed to the `open()` call.
1967  enum OpenMode { Create, AppendSubimage, AppendMIPLevel };
1968 
1969  /// Open the file with given name, with resolution and other format
1970  /// data as given in newspec. It is legal to call open multiple times
1971  /// on the same file without a call to `close()`, if it supports
1972  /// multiimage and mode is AppendSubimage, or if it supports
1973  /// MIP-maps and mode is AppendMIPLevel -- this is interpreted as
1974  /// appending a subimage, or a MIP level to the current subimage,
1975  /// respectively.
1976  ///
1977  /// @param filename The name of the image file to open, UTF-8 encoded.
1978  /// @param newspec The ImageSpec describing the resolution, data
1979  /// types, etc.
1980  /// @param mode Specifies whether the purpose of the `open` is
1981  /// to create/truncate the file (default: `Create`),
1982  /// append another subimage (`AppendSubimage`), or
1983  /// append another MIP level (`AppendMIPLevel`).
1984  /// @returns `true` upon success, or `false` upon failure.
1985  virtual bool open (const std::string &filename, const ImageSpec &newspec,
1986  OpenMode mode=Create) = 0;
1987 
1988  /// Open an ImageOutput using a UTF-16 encoded wstring filename.
1989  bool open (const std::wstring &filename, const ImageSpec &newspec,
1990  OpenMode mode=Create) {
1991  return open(Strutil::utf16_to_utf8(filename), newspec, mode);
1992  }
1993 
1994  /// Open a multi-subimage file with given name and specifications for
1995  /// each of the subimages. Upon success, the first subimage will be
1996  /// open and ready for transmission of pixels. Subsequent subimages
1997  /// will be denoted with the usual call of
1998  /// `open(name,spec,AppendSubimage)` (and MIP levels by
1999  /// `open(name,spec,AppendMIPLevel)`).
2000  ///
2001  /// The purpose of this call is to accommodate format-writing
2002  /// libraries that must know the number and specifications of the
2003  /// subimages upon first opening the file; such formats can be
2004  /// detected by::
2005  /// supports("multiimage") && !supports("appendsubimage")
2006  /// The individual specs passed to the appending open() calls for
2007  /// subsequent subimages *must* match the ones originally passed.
2008  ///
2009  /// @param filename The name of the image file to open, UTF-8 encoded.
2010  /// @param subimages The number of subimages (and therefore the
2011  /// length of the `specs[]` array.
2012  /// @param specs[]
2013  /// Pointer to an array of `ImageSpec` objects
2014  /// describing each of the expected subimages.
2015  /// @returns `true` upon success, or `false` upon failure.
2016  virtual bool open (const std::string &filename,
2017  int subimages OIIO_MAYBE_UNUSED,
2018  const ImageSpec *specs) {
2019  // Default implementation: just a regular open, assume that
2020  // appending will work.
2021  return open (filename, specs[0]);
2022  }
2023 
2024  bool open (const std::wstring &filename, int subimages OIIO_MAYBE_UNUSED,
2025  const ImageSpec *specs) {
2026  // Default implementation: just a regular open, assume that
2027  // appending will work.
2028  return open (Strutil::utf16_to_utf8(filename), specs[0]);
2029  }
2030 
2031  /// Return a reference to the image format specification of the current
2032  /// subimage. Note that the contents of the spec are invalid before
2033  /// `open()` or after `close()`.
2034  const ImageSpec &spec (void) const { return m_spec; }
2035 
2036  /// Closes the currently open file associated with this ImageOutput and
2037  /// frees any memory or resources associated with it.
2038  virtual bool close () = 0;
2039  /// @}
2040 
2041  /// @{
2042  /// @name Writing pixels
2043  ///
2044  /// Common features of all the `write` methods:
2045  ///
2046  /// * The `format` parameter describes the data type of the `data[]`. The
2047  /// write methods automatically convert the data from the specified
2048  /// `format` to the actual output data type of the file (as was
2049  /// specified by the ImageSpec passed to `open()`). If `format` is
2050  /// `TypeUnknown`, then rather than converting from `format`, it will
2051  /// just copy pixels assumed to already be in the file's native data
2052  /// layout (including, possibly, per-channel data formats as specified
2053  /// by the ImageSpec's `channelformats` field).
2054  ///
2055  /// * The `stride` values describe the layout of the `data` buffer:
2056  /// `xstride` is the distance in bytes between successive pixels
2057  /// within each scanline. `ystride` is the distance in bytes between
2058  /// successive scanlines. For volumetric images `zstride` is the
2059  /// distance in bytes between successive "volumetric planes". Strides
2060  /// set to the special value `AutoStride` imply contiguous data, i.e.,
2061  ///
2062  /// xstride = format.size() * nchannels
2063  /// ystride = xstride * width
2064  /// zstride = ystride * height
2065  ///
2066  /// * Any *range* parameters (such as `ybegin` and `yend`) describe a
2067  /// "half open interval", meaning that `begin` is the first item and
2068  /// `end` is *one past the last item*. That means that the number of
2069  /// items is `end - begin`.
2070  ///
2071  /// * For ordinary 2D (non-volumetric) images, any `z` or `zbegin`
2072  /// coordinates should be 0 and any `zend` should be 1, indicating
2073  /// that only a single image "plane" exists.
2074  ///
2075  /// * Scanlines or tiles must be written in successive increasing
2076  /// coordinate order, unless the particular output file driver allows
2077  /// random access (indicated by `supports("random_access")`).
2078  ///
2079  /// * All write functions return `true` for success, `false` for failure
2080  /// (after which a call to `geterror()` may retrieve a specific error
2081  /// message).
2082  ///
2083 
2084  /// Write the full scanline that includes pixels (*,y,z). For 2D
2085  /// non-volume images, `z` should be 0. The `xstride` value gives the
2086  /// distance between successive pixels (in bytes). Strides set to
2087  /// `AutoStride` imply "contiguous" data.
2088  ///
2089  /// @param y/z The y & z coordinates of the scanline.
2090  /// @param format A TypeDesc describing the type of `data`.
2091  /// @param data Pointer to the pixel data.
2092  /// @param xstride The distance in bytes between successive
2093  /// pixels in `data` (or `AutoStride`).
2094  /// @returns `true` upon success, or `false` upon failure.
2095  virtual bool write_scanline (int y, int z, TypeDesc format,
2096  const void *data, stride_t xstride=AutoStride);
2097 
2098  /// Write multiple scanlines that include pixels (*,y,z) for all ybegin
2099  /// <= y < yend, from data. This is analogous to
2100  /// `write_scanline(y,z,format,data,xstride)` repeatedly for each of the
2101  /// scanlines in turn (the advantage, though, is that some image file
2102  /// types may be able to write multiple scanlines more efficiently or
2103  /// in parallel, than it could with one scanline at a time).
2104  ///
2105  /// @param ybegin/yend The y range of the scanlines being passed.
2106  /// @param z The z coordinate of the scanline.
2107  /// @param format A TypeDesc describing the type of `data`.
2108  /// @param data Pointer to the pixel data.
2109  /// @param xstride/ystride
2110  /// The distance in bytes between successive pixels
2111  /// and scanlines (or `AutoStride`).
2112  /// @returns `true` upon success, or `false` upon failure.
2113  virtual bool write_scanlines (int ybegin, int yend, int z,
2114  TypeDesc format, const void *data,
2115  stride_t xstride=AutoStride,
2116  stride_t ystride=AutoStride);
2117 
2118  /// Write the tile with (x,y,z) as the upper left corner. The three
2119  /// stride values give the distance (in bytes) between successive
2120  /// pixels, scanlines, and volumetric slices, respectively. Strides set
2121  /// to AutoStride imply 'contiguous' data in the shape of a full tile,
2122  /// i.e.,
2123  ///
2124  /// xstride = format.size() * spec.nchannels
2125  /// ystride = xstride * spec.tile_width
2126  /// zstride = ystride * spec.tile_height
2127  ///
2128  /// @param x/y/z The upper left coordinate of the tile being passed.
2129  /// @param format A TypeDesc describing the type of `data`.
2130  /// @param data Pointer to the pixel data.
2131  /// @param xstride/ystride/zstride
2132  /// The distance in bytes between successive pixels,
2133  /// scanlines, and image planes (or `AutoStride` to
2134  /// indicate a "contiguous" single tile).
2135  /// @returns `true` upon success, or `false` upon failure.
2136  ///
2137  /// @note This call will fail if the image is not tiled, or if (x,y,z)
2138  /// is not the upper left corner coordinates of a tile.
2139  virtual bool write_tile (int x, int y, int z, TypeDesc format,
2140  const void *data, stride_t xstride=AutoStride,
2141  stride_t ystride=AutoStride,
2142  stride_t zstride=AutoStride);
2143 
2144  /// Write the block of multiple tiles that include all pixels in
2145  ///
2146  /// [xbegin,xend) X [ybegin,yend) X [zbegin,zend)
2147  ///
2148  /// This is analogous to calling `write_tile(x,y,z,...)` for each tile
2149  /// in turn (but for some file formats, passing multiple tiles may allow
2150  /// it to write more efficiently or in parallel).
2151  ///
2152  /// The begin/end pairs must correctly delineate tile boundaries, with
2153  /// the exception that it may also be the end of the image data if the
2154  /// image resolution is not a whole multiple of the tile size. The
2155  /// stride values give the data spacing of adjacent pixels, scanlines,
2156  /// and volumetric slices (measured in bytes). Strides set to AutoStride
2157  /// imply contiguous data in the shape of the [begin,end) region, i.e.,
2158  ///
2159  /// xstride = format.size() * spec.nchannels
2160  /// ystride = xstride * (xend-xbegin)
2161  /// zstride = ystride * (yend-ybegin)
2162  ///
2163  /// @param xbegin/xend The x range of the pixels covered by the group
2164  /// of tiles passed.
2165  /// @param ybegin/yend The y range of the pixels covered by the tiles.
2166  /// @param zbegin/zend The z range of the pixels covered by the tiles
2167  /// (for a 2D image, zbegin=0 and zend=1).
2168  /// @param format A TypeDesc describing the type of `data`.
2169  /// @param data Pointer to the pixel data.
2170  /// @param xstride/ystride/zstride
2171  /// The distance in bytes between successive pixels,
2172  /// scanlines, and image planes (or `AutoStride`).
2173  /// @returns `true` upon success, or `false` upon failure.
2174  ///
2175  /// @note The call will fail if the image is not tiled, or if the pixel
2176  /// ranges do not fall along tile (or image) boundaries, or if it is not
2177  /// a valid tile range.
2178  virtual bool write_tiles (int xbegin, int xend, int ybegin, int yend,
2179  int zbegin, int zend, TypeDesc format,
2180  const void *data, stride_t xstride=AutoStride,
2181  stride_t ystride=AutoStride,
2182  stride_t zstride=AutoStride);
2183 
2184  /// Write a rectangle of pixels given by the range
2185  ///
2186  /// [xbegin,xend) X [ybegin,yend) X [zbegin,zend)
2187  ///
2188  /// The stride values give the data spacing of adjacent pixels,
2189  /// scanlines, and volumetric slices (measured in bytes). Strides set to
2190  /// AutoStride imply contiguous data in the shape of the [begin,end)
2191  /// region, i.e.,
2192  ///
2193  /// xstride = format.size() * spec.nchannels
2194  /// ystride = xstride * (xend-xbegin)
2195  /// zstride = ystride * (yend-ybegin)
2196  ///
2197  /// @param xbegin/xend The x range of the pixels being passed.
2198  /// @param ybegin/yend The y range of the pixels being passed.
2199  /// @param zbegin/zend The z range of the pixels being passed
2200  /// (for a 2D image, zbegin=0 and zend=1).
2201  /// @param format A TypeDesc describing the type of `data`.
2202  /// @param data Pointer to the pixel data.
2203  /// @param xstride/ystride/zstride
2204  /// The distance in bytes between successive pixels,
2205  /// scanlines, and image planes (or `AutoStride`).
2206  /// @returns `true` upon success, or `false` upon failure.
2207  ///
2208  /// @note The call will fail for a format plugin that does not return
2209  /// true for `supports("rectangles")`.
2210  virtual bool write_rectangle (int xbegin, int xend, int ybegin, int yend,
2211  int zbegin, int zend, TypeDesc format,
2212  const void *data, stride_t xstride=AutoStride,
2213  stride_t ystride=AutoStride,
2214  stride_t zstride=AutoStride);
2215 
2216  /// Write the entire image of `spec.width x spec.height x spec.depth`
2217  /// pixels, from a buffer with the given strides and in the desired
2218  /// format.
2219  ///
2220  /// Depending on the spec, this will write either all tiles or all
2221  /// scanlines. Assume that data points to a layout in row-major order.
2222  ///
2223  /// Because this may be an expensive operation, a progress callback
2224  /// may be passed. Periodically, it will be called as follows:
2225  ///
2226  /// progress_callback (progress_callback_data, float done);
2227  ///
2228  /// where `done` gives the portion of the image (between 0.0 and 1.0)
2229  /// that has been written thus far.
2230  ///
2231  /// @param format A TypeDesc describing the type of `data`.
2232  /// @param data Pointer to the pixel data.
2233  /// @param xstride/ystride/zstride
2234  /// The distance in bytes between successive pixels,
2235  /// scanlines, and image planes (or `AutoStride`).
2236  /// @param progress_callback/progress_callback_data
2237  /// Optional progress callback.
2238  /// @returns `true` upon success, or `false` upon failure.
2239  virtual bool write_image (TypeDesc format, const void *data,
2240  stride_t xstride=AutoStride,
2241  stride_t ystride=AutoStride,
2242  stride_t zstride=AutoStride,
2243  ProgressCallback progress_callback=nullptr,
2244  void *progress_callback_data=nullptr);
2245 
2246  /// Write deep scanlines containing pixels (*,y,z), for all y in the
2247  /// range [ybegin,yend), to a deep file. This will fail if it is not a
2248  /// deep file.
2249  ///
2250  /// @param ybegin/yend The y range of the scanlines being passed.
2251  /// @param z The z coordinate of the scanline.
2252  /// @param deepdata A `DeepData` object with the data for these
2253  /// scanlines.
2254  /// @returns `true` upon success, or `false` upon failure.
2255  virtual bool write_deep_scanlines (int ybegin, int yend, int z,
2256  const DeepData &deepdata);
2257 
2258  /// Write the block of deep tiles that include all pixels in
2259  /// the range
2260  ///
2261  /// [xbegin,xend) X [ybegin,yend) X [zbegin,zend)
2262  ///
2263  /// The begin/end pairs must correctly delineate tile boundaries, with
2264  /// the exception that it may also be the end of the image data if the
2265  /// image resolution is not a whole multiple of the tile size.
2266  ///
2267  /// @param xbegin/xend The x range of the pixels covered by the group
2268  /// of tiles passed.
2269  /// @param ybegin/yend The y range of the pixels covered by the tiles.
2270  /// @param zbegin/zend The z range of the pixels covered by the tiles
2271  /// (for a 2D image, zbegin=0 and zend=1).
2272  /// @param deepdata A `DeepData` object with the data for the tiles.
2273  /// @returns `true` upon success, or `false` upon failure.
2274  ///
2275  /// @note The call will fail if the image is not tiled, or if the pixel
2276  /// ranges do not fall along tile (or image) boundaries, or if it is not
2277  /// a valid tile range.
2278  virtual bool write_deep_tiles (int xbegin, int xend, int ybegin, int yend,
2279  int zbegin, int zend,
2280  const DeepData &deepdata);
2281 
2282  /// Write the entire deep image described by `deepdata`. Depending on
2283  /// the spec, this will write either all tiles or all scanlines.
2284  ///
2285  /// @param deepdata A `DeepData` object with the data for the image.
2286  /// @returns `true` upon success, or `false` upon failure.
2287  virtual bool write_deep_image (const DeepData &deepdata);
2288 
2289  /// Specify a reduced-resolution ("thumbnail") version of the image.
2290  /// Note that many image formats may require the thumbnail to be
2291  /// specified prior to writing the pixels.
2292  ///
2293  /// @param thumb
2294  /// A reference to an `ImageBuf` containing the thumbnail image.
2295  /// @returns
2296  /// `true` upon success, `false` if it was not possible to write
2297  /// the thumbnail, or if this file format (or writer) does not
2298  /// support thumbnails.
2299  ///
2300  /// @note This method was added to OpenImageIO 2.3.
2301  virtual bool set_thumbnail(const ImageBuf& thumb) { return false; }
2302 
2303  /// @}
2304 
2305  /// Read the pixels of the current subimage of `in`, and write it as the
2306  /// next subimage of `*this`, in a way that is efficient and does not
2307  /// alter pixel values, if at all possible. Both `in` and `this` must
2308  /// be a properly-opened `ImageInput` and `ImageOutput`, respectively,
2309  /// and their current images must match in size and number of channels.
2310  ///
2311  /// If a particular ImageOutput implementation does not supply a
2312  /// `copy_image` method, it will inherit the default implementation,
2313  /// which is to simply read scanlines or tiles from `in` and write them
2314  /// to `*this`. However, some file format implementations may have a
2315  /// special technique for directly copying raw pixel data from the input
2316  /// to the output, when both are the same file type and the same pixel
2317  /// data type. This can be more efficient than `in->read_image()`
2318  /// followed by `out->write_image()`, and avoids any unintended pixel
2319  /// alterations, especially for formats that use lossy compression.
2320  ///
2321  /// Note: this method is NOT thread-safe, since it depends on persistent
2322  /// state in the ImageInput.
2323  ///
2324  /// @param in A pointer to the open `ImageInput` to read from.
2325  /// @returns `true` upon success, or `false` upon failure.
2326  virtual bool copy_image (ImageInput *in);
2327 
2328  // General message passing between client and image output server. This
2329  // is currently undefined and is reserved for future use.
2330  virtual int send_to_output (const char *format, ...);
2331  int send_to_client (const char *format, ...);
2332 
2333  /// Set an IOProxy for this writer. This must be called prior to
2334  /// `open()`, and only for writers that support them
2335  /// (`supports("ioproxy")`). The caller retains ownership of the proxy.
2336  ///
2337  /// @returns `true` for success, `false` for failure.
2338  virtual bool set_ioproxy (Filesystem::IOProxy* ioproxy) {
2339  return (ioproxy == nullptr);
2340  }
2341 
2342  /// Is there a pending error message waiting to be retrieved, that
2343  /// resulted from an ImageOutput API call made by the this thread?
2344  ///
2345  /// Note that any `error()` calls issued are thread-specific, and the
2346  /// `geterror()/has_error()` are expected to be called by the same
2347  /// thread that called whichever API function encountered an error.
2348  bool has_error() const;
2349 
2350  /// Return the text of all pending error messages issued against this
2351  /// ImageOutput by the calling thread, and clear the pending error
2352  /// message unless `clear` is false. If no error message is pending, it
2353  /// will return an empty string.
2354  ///
2355  /// Note that any `error()` calls issued are thread-specific, and the
2356  /// `geterror()/has_error()` are expected to be called by the same
2357  /// thread that called whichever API function encountered an error.
2358  std::string geterror(bool clear = true) const;
2359 
2360  /// Error reporting for the plugin implementation: call this with
2361  /// `Strutil::format`-like arguments. It is not necessary to have the
2362  /// error message contain a trailing newline.
2363  /// Use with caution! Some day this will change to be fmt-like rather
2364  /// than printf-like.
2365  template<typename... Args>
2367  void error(const char* fmt, const Args&... args) const {
2368  append_error(Strutil::format (fmt, args...));
2369  }
2370 
2371  /// Error reporting for the plugin implementation: call this with
2372  /// printf-like arguments. It is not necessary to have the error message
2373  /// contain a trailing newline.
2374  template<typename... Args>
2375  void errorf(const char* fmt, const Args&... args) const {
2376  append_error(Strutil::sprintf (fmt, args...));
2377  }
2378 
2379  /// Error reporting for the plugin implementation: call this with
2380  /// std::format-like arguments. It is not necessary to have the error
2381  /// message contain a trailing newline.
2382  template<typename... Args>
2383  void errorfmt(const char* fmt, const Args&... args) const {
2384  append_error(Strutil::fmt::format (fmt, args...));
2385  }
2386 
2387  // Error reporting for the plugin implementation: call this with
2388  // std::format-like arguments. It is not necessary to have the error
2389  // message contain a trailing newline.
2390  template<typename... Args>
2391  OIIO_DEPRECATED("use `errorfmt` instead")
2392  void fmterror(const char* fmt, const Args&... args) const {
2393  append_error(Strutil::fmt::format (fmt, args...));
2394  }
2395 
2396  /// Set the threading policy for this ImageOutput, controlling the
2397  /// maximum amount of parallelizing thread "fan-out" that might occur
2398  /// during large write operations. The default of 0 means that the
2399  /// global `attribute("threads")` value should be used (which itself
2400  /// defaults to using as many threads as cores; see Section
2401  /// `Global Attributes`_).
2402  ///
2403  /// The main reason to change this value is to set it to 1 to indicate
2404  /// that the calling thread should do all the work rather than spawning
2405  /// new threads. That is probably the desired behavior in situations
2406  /// where the calling application has already spawned multiple worker
2407  /// threads.
2408  void threads(int n);
2409 
2410  /// Retrieve the current thread-spawning policy.
2411  /// @see `threads(int)`
2412  int threads() const;
2413 
2414  // Custom new and delete to ensure that allocations & frees happen in
2415  // the OpenImageIO library, not in the app or plugins (because Windows).
2416  void* operator new (size_t size);
2417  void operator delete (void *ptr);
2418 
2419  /// Call signature of a function that creates and returns an
2420  /// `ImageOutput*`.
2421  typedef ImageOutput* (*Creator)();
2422 
2423 protected:
2424  /// Helper routines used by write_* implementations: convert data (in
2425  /// the given format and stride) to the "native" format of the file
2426  /// (described by the 'spec' member variable), in contiguous order. This
2427  /// requires a scratch space to be passed in so that there are no memory
2428  /// leaks. Returns a pointer to the native data, which may be the
2429  /// original data if it was already in native format and contiguous, or
2430  /// it may point to the scratch space if it needed to make a copy or do
2431  /// conversions. For float->uint8 conversions only, if dither is
2432  /// nonzero, random dither will be added to reduce quantization banding
2433  /// artifacts; in this case, the specific nonzero dither value is used
2434  /// as a seed for the hash function that produces the per-pixel dither
2435  /// amounts, and the optional [xyz]origin parameters help it to align
2436  /// the pixels to the right position in the dither pattern.
2437  const void *to_native_scanline (TypeDesc format,
2438  const void *data, stride_t xstride,
2439  std::vector<unsigned char> &scratch,
2440  unsigned int dither=0,
2441  int yorigin=0, int zorigin=0);
2442  const void *to_native_tile (TypeDesc format, const void *data,
2443  stride_t xstride, stride_t ystride,
2444  stride_t zstride,
2445  std::vector<unsigned char> &scratch,
2446  unsigned int dither=0,
2447  int xorigin=0, int yorigin=0, int zorigin=0);
2448  const void *to_native_rectangle (int xbegin, int xend, int ybegin, int yend,
2449  int zbegin, int zend,
2450  TypeDesc format, const void *data,
2451  stride_t xstride, stride_t ystride,
2452  stride_t zstride,
2453  std::vector<unsigned char> &scratch,
2454  unsigned int dither=0,
2455  int xorigin=0, int yorigin=0, int zorigin=0);
2456 
2457  /// Helper function to copy a rectangle of data into the right spot in
2458  /// an image-sized buffer. In addition to copying to the right place,
2459  /// this handles data format conversion and dither (if the spec's
2460  /// "oiio:dither" is nonzero, and if it's converting from a float-like
2461  /// type to UINT8). The buf_format describes the type of image_buffer,
2462  /// if it's TypeDesc::UNKNOWN it will be assumed to be spec.format.
2463  bool copy_to_image_buffer (int xbegin, int xend, int ybegin, int yend,
2464  int zbegin, int zend, TypeDesc format,
2465  const void *data, stride_t xstride,
2466  stride_t ystride, stride_t zstride,
2467  void *image_buffer,
2468  TypeDesc buf_format = TypeDesc::UNKNOWN);
2469  /// Helper function to copy a tile of data into the right spot in an
2470  /// image-sized buffer. This is really just a wrapper for
2471  /// copy_to_image_buffer, passing all the right parameters to copy
2472  /// exactly one tile.
2473  bool copy_tile_to_image_buffer (int x, int y, int z, TypeDesc format,
2474  const void *data, stride_t xstride,
2475  stride_t ystride, stride_t zstride,
2476  void *image_buffer,
2477  TypeDesc buf_format = TypeDesc::UNKNOWN);
2478 
2479 protected:
2480  ImageSpec m_spec; ///< format spec of the currently open image
2481 
2482 private:
2483  // PIMPL idiom -- this lets us hide details of the internals of the
2484  // ImageInput parent class so that changing them does not break the
2485  // ABI.
2486  class Impl;
2487  static void impl_deleter(Impl*);
2488  std::unique_ptr<Impl, decltype(&impl_deleter)> m_impl;
2489 
2490  void append_error(string_view message) const; // add to m_errmessage
2491 };
2492 
2493 
2494 
2495 // Utility functions
2496 
2497 /// Returns a numeric value for the version of OpenImageIO, 10000 for each
2498 /// major version, 100 for each minor version, 1 for each patch. For
2499 /// example, OpenImageIO 1.2.3 would return a value of 10203. One example of
2500 /// how this is useful is for plugins to query the version to be sure they
2501 /// are linked against an adequate version of the library.
2503 
2504 /// Is there a pending global error message waiting to be retrieved?
2505 OIIO_API bool has_error();
2506 
2507 /// Returns any error string describing what went wrong if
2508 /// `ImageInput::create()` or `ImageOutput::create()` failed (since in such
2509 /// cases, the ImageInput or ImageOutput itself does not exist to have its
2510 /// own `geterror()` function called). This function returns the last error
2511 /// for this particular thread, and clear the pending error message unless
2512 /// `clear` is false; separate threads will not clobber each other's global
2513 /// error messages.
2514 OIIO_API std::string geterror(bool clear = true);
2515 
2516 /// `OIIO::attribute()` sets a global attribute (i.e., a property or
2517 /// option) of OpenImageIO. The `name` designates the name of the attribute,
2518 /// `type` describes the type of data, and `val` is a pointer to memory
2519 /// containing the new value for the attribute.
2520 ///
2521 /// If the name is known, valid attribute that matches the type specified,
2522 /// the attribute will be set to the new value and `attribute()` will return
2523 /// `true`. If `name` is not recognized, or if the types do not match
2524 /// (e.g., `type` is `TypeFloat` but the named attribute is a string), the
2525 /// attribute will not be modified, and `attribute()` will return `false`.
2526 ///
2527 /// The following are the recognized attributes:
2528 ///
2529 /// - `string options`
2530 ///
2531 /// This catch-all is simply a comma-separated list of `name=value`
2532 /// settings of named options, which will be parsed and individually set.
2533 /// For example,
2534 ///
2535 /// OIIO::attribute ("options", "threads=4,log_times=1");
2536 ///
2537 /// Note that if an option takes a string value that must itself contain
2538 /// a comma, it is permissible to enclose the value in either 'single'
2539 /// or "double" quotes.
2540 ///
2541 /// - `int threads`
2542 ///
2543 /// How many threads to use for operations that can be sped up by being
2544 /// multithreaded. (Examples: simultaneous format conversions of multiple
2545 /// scanlines read together, or many ImageBufAlgo operations.) The
2546 /// default is 0, meaning to use the full available hardware concurrency
2547 /// detected.
2548 ///
2549 /// Situations where the main application logic is essentially single
2550 /// threaded (i.e., one top-level call into OIIO at a time) should leave
2551 /// this at the default value, or some reasonable number of cores, thus
2552 /// allowing lots of threads to fill the cores when OIIO has big tasks to
2553 /// complete. But situations where you have many threads at the
2554 /// application level, each of which is expected to be making separate
2555 /// OIIO calls simultaneously, should set this to 1, thus having each
2556 /// calling thread do its own work inside of OIIO rather than spawning
2557 /// new threads with a high overall "fan out."
2558 ///
2559 /// - `int exr_threads`
2560 ///
2561 /// Sets the internal OpenEXR thread pool size. The default is to use as
2562 /// many threads as the amount of hardware concurrency detected. Note
2563 /// that this is separate from the OIIO `"threads"` attribute.
2564 ///
2565 /// - `string font_searchpath`
2566 ///
2567 /// Colon-separated (or semicolon-separated) list of directories to search
2568 /// if fonts are needed. (Such as for `ImageBufAlgo::render_text()`.)
2569 ///
2570 /// - `string plugin_searchpath`
2571 ///
2572 /// Colon-separated (or semicolon-separated) list of directories to search
2573 /// for dynamically-loaded format plugins.
2574 ///
2575 /// - `int try_all_readers`
2576 ///
2577 /// When nonzero (the default), a call to `ImageInput::create()` or
2578 /// `ImageInput::open()` that does not succeed in opening the file with the
2579 /// format reader implied by the file extension will try all available
2580 /// format readers to see if one of them can open the file. If this is
2581 /// zero, the only reader that will be tried is the one implied by the file
2582 /// extension.
2583 ///
2584 /// - `int read_chunk`
2585 ///
2586 /// When performing a `read_image()`, this is the number of scanlines it
2587 /// will attempt to read at a time (some formats are more efficient when
2588 /// reading and decoding multiple scanlines). The default is 256. The
2589 /// special value of 0 indicates that it should try to read the whole
2590 /// image if possible.
2591 ///
2592 /// - `float[] missingcolor`, `string missingcolor`
2593 ///
2594 /// This attribute may either be an array of float values, or a string
2595 /// containing a comma-separated list of the values. Setting this option
2596 /// globally is equivalent to always passing an `ImageInput`
2597 /// open-with-configuration hint `"oiio:missingcolor"` with the value.
2598 ///
2599 /// When set, it gives some `ImageInput` readers the option of ignoring
2600 /// any *missing* tiles or scanlines in the file, and instead of treating
2601 /// the read failure of an individual tile as a full error, will
2602 /// interpret is as an intentionally missing tile and proceed by simply
2603 /// filling in the missing pixels with the color specified. If the first
2604 /// element is negative, it will use the absolute value, but draw
2605 /// alternating diagonal stripes of the color. For example,
2606 ///
2607 /// float missing[4] = { -1.0, 0.0, 0.0, 0.0 }; // striped red
2608 /// OIIO::attribute ("missingcolor", TypeDesc("float[4]"), &missing);
2609 ///
2610 /// Note that only some file formats support files with missing tiles or
2611 /// scanlines, and this is only taken as a hint. Please see
2612 /// chap-bundledplugins_ for details on which formats accept a
2613 /// `"missingcolor"` configuration hint.
2614 ///
2615 /// - `int debug`
2616 ///
2617 /// When nonzero, various debug messages may be printed. The default is 0
2618 /// for release builds, 1 for DEBUG builds (values > 1 are for OIIO
2619 /// developers to print even more debugging information), This attribute
2620 /// but also may be overridden by the OPENIMAGEIO_DEBUG environment
2621 /// variable.
2622 ///
2623 /// - `int tiff:half`
2624 ///
2625 /// When nonzero, allows TIFF to write `half` pixel data. N.B. Most apps
2626 /// may not read these correctly, but OIIO will. That's why the default
2627 /// is not to support it.
2628 ///
2629 /// - `int openexr:core`
2630 ///
2631 /// When nonzero, use the new "OpenEXR core C library" when available,
2632 /// for OpenEXR >= 3.1. This is experimental, and currently defaults to 0.
2633 ///
2634 /// - `int limits:channels` (1024)
2635 ///
2636 /// When nonzero, the maximum number of color channels in an image. Image
2637 /// files whose headers indicate they have more channels might be assumed
2638 /// to be corrupted or malicious files. In situations when more channels
2639 /// are expected to be encountered, the application should raise this
2640 /// limit. The default is 1024 channels.
2641 ///
2642 /// - `int limits:imagesize_MB` (32768)
2643 ///
2644 /// When nonzero, the maximum size in MB of the uncompressed pixel data of
2645 /// a single 2D image. Images whose headers indicate that they are larger
2646 /// than this might be assumed to be corrupted or malicious files. The
2647 /// default is 32768 (32 GB of uncompressed pixel data -- equivalent to 64k
2648 /// x 64k x 4 channel x half). In situations when images larger than this
2649 /// are expected to be encountered, you should raise this limit.
2650 ///
2651 /// - `int log_times`
2652 ///
2653 /// When the `"log_times"` attribute is nonzero, `ImageBufAlgo` functions
2654 /// are instrumented to record the number of times they were called and
2655 /// the total amount of time spent executing them. It can be overridden
2656 /// by environment variable `OPENIMAGEIO_LOG_TIMES`. The totals will be
2657 /// recorded and can be retrieved as a string by using
2658 /// `OIIO::getattribute("timing_report", ...)`. Additionally, if the
2659 /// value is 2 or more, the timing report will be printed to `stdout`
2660 /// upon application exit (not advised in contexts where it isn't ok to
2661 /// print to the terminal via stdout, such as GUI apps or libraries).
2662 ///
2663 /// When enabled, there is a slight runtime performance cost due to
2664 /// checking the time at the start and end of each of those function
2665 /// calls, and the locking and recording of the data structure that holds
2666 /// the log information. When the `log_times` attribute is disabled,
2667 /// there is no additional performance cost.
2668 ///
2669 OIIO_API bool attribute(string_view name, TypeDesc type, const void* val);
2670 
2671 /// Shortcut attribute() for setting a single integer.
2672 inline bool attribute (string_view name, int val) {
2673  return attribute (name, TypeInt, &val);
2674 }
2675 /// Shortcut attribute() for setting a single float.
2676 inline bool attribute (string_view name, float val) {
2677  return attribute (name, TypeFloat, &val);
2678 }
2679 /// Shortcut attribute() for setting a single string.
2681  const char *s = val.c_str();
2682  return attribute (name, TypeString, &s);
2683 }
2684 
2685 /// Get the named global attribute of OpenImageIO, store it in `*val`.
2686 /// Return `true` if found and it was compatible with the type specified,
2687 /// otherwise return `false` and do not modify the contents of `*val`. It
2688 /// is up to the caller to ensure that `val` points to the right kind and
2689 /// size of storage for the given type.
2690 ///
2691 /// In addition to being able to retrieve all the attributes that are
2692 /// documented as settable by the `OIIO::attribute()` call, `getattribute()`
2693 /// can also retrieve the following read-only attributes:
2694 ///
2695 /// - `string format_list`
2696 /// - `string input_format_list`
2697 /// - `string output_format_list`
2698 ///
2699 /// A comma-separated list of all the names of, respectively, all
2700 /// supported image formats, all formats accepted as inputs, and all
2701 /// formats accepted as outputs.
2702 ///
2703 /// - `string extension_list`
2704 ///
2705 /// For each format, the format name, followed by a colon, followed by a
2706 /// comma-separated list of all extensions that are presumed to be used
2707 /// for that format. Semicolons separate the lists for formats. For
2708 /// example,
2709 ///
2710 /// "tiff:tif;jpeg:jpg,jpeg;openexr:exr"
2711 ///
2712 /// - `string library_list`
2713 ///
2714 /// For each format that uses a dependent library, the format name,
2715 /// followed by a colon, followed by the name and version of the
2716 /// dependency. Semicolons separate the lists for formats. For example,
2717 ///
2718 /// "tiff:LIBTIFF 4.0.4;gif:gif_lib 4.2.3;openexr:OpenEXR 2.2.0"
2719 ///
2720 /// - string "timing_report"
2721 /// A string containing the report of all the log_times.
2722 ///
2723 /// - `string hw:simd`
2724 /// - `string oiio:simd` (read-only)
2725 ///
2726 /// A comma-separated list of hardware CPU features for SIMD (and some
2727 /// other things). The `"oiio:simd"` attribute is similarly a list of
2728 /// which features this build of OIIO was compiled to support.
2729 ///
2730 /// This was added in OpenImageIO 1.8.
2731 ///
2732 /// - `float resident_memory_used_MB`
2733 ///
2734 /// This read-only attribute can be used for debugging purposes to report
2735 /// the approximate process memory used (resident) by the application, in
2736 /// MB.
2737 ///
2738 /// - `string timing_report`
2739 ///
2740 /// Retrieving this attribute returns the timing report generated by the
2741 /// `log_timing` attribute (if it was enabled). The report is sorted
2742 /// alphabetically and for each named instrumentation region, prints the
2743 /// number of times it executed, the total runtime, and the average per
2744 /// call, like this:
2745 ///
2746 /// IBA::computePixelStats 2 2.69ms (avg 1.34ms)
2747 /// IBA::make_texture 1 74.05ms (avg 74.05ms)
2748 /// IBA::mul 8 2.42ms (avg 0.30ms)
2749 /// IBA::over 10 23.82ms (avg 2.38ms)
2750 /// IBA::resize 20 0.24s (avg 12.18ms)
2751 /// IBA::zero 8 0.66ms (avg 0.08ms)
2752 ///
2754 
2755 /// Shortcut getattribute() for retrieving a single integer.
2756 /// The value is placed in `val`, and the function returns `true` if the
2757 /// attribute was found and was legally convertible to an int.
2758 inline bool getattribute (string_view name, int &val) {
2759  return getattribute (name, TypeInt, &val);
2760 }
2761 /// Shortcut getattribute() for retrieving a single float.
2762 /// The value is placed in `val`, and the function returns `true` if the
2763 /// attribute was found and was legally convertible to a float.
2764 inline bool getattribute (string_view name, float &val) {
2765  return getattribute (name, TypeFloat, &val);
2766 }
2767 /// Shortcut getattribute() for retrieving a single string as a
2768 /// `std::string`. The value is placed in `val`, and the function returns
2769 /// `true` if the attribute was found.
2771  ustring s;
2772  bool ok = getattribute (name, TypeString, &s);
2773  if (ok)
2774  val = s.string();
2775  return ok;
2776 }
2777 /// Shortcut getattribute() for retrieving a single string as a `char*`.
2778 inline bool getattribute (string_view name, char **val) {
2779  return getattribute (name, TypeString, val);
2780 }
2781 /// Shortcut getattribute() for retrieving a single integer, with a supplied
2782 /// default value that will be returned if the attribute is not found or
2783 /// could not legally be converted to an int.
2784 inline int get_int_attribute (string_view name, int defaultval=0) {
2785  int val;
2786  return getattribute (name, TypeInt, &val) ? val : defaultval;
2787 }
2788 /// Shortcut getattribute() for retrieving a single float, with a supplied
2789 /// default value that will be returned if the attribute is not found or
2790 /// could not legally be converted to a float.
2791 inline float get_float_attribute (string_view name, float defaultval=0) {
2792  float val;
2793  return getattribute (name, TypeFloat, &val) ? val : defaultval;
2794 }
2795 /// Shortcut getattribute() for retrieving a single string, with a supplied
2796 /// default value that will be returned if the attribute is not found.
2798  string_view defaultval = string_view()) {
2799  ustring val;
2800  return getattribute (name, TypeString, &val) ? string_view(val) : defaultval;
2801 }
2802 
2803 
2804 /// Register the input and output 'create' routines and list of file
2805 /// extensions for a particular format.
2806 OIIO_API void declare_imageio_format (const std::string &format_name,
2807  ImageInput::Creator input_creator,
2808  const char **input_extensions,
2809  ImageOutput::Creator output_creator,
2810  const char **output_extensions,
2811  const char *lib_version);
2812 
2813 /// Is `name` one of the known format names?
2815 
2816 /// Utility: Parse the "extension_list" attribute into a std::map string
2817 /// keys are the names of all the file formats OIIO knows how to read, and
2818 /// whose values are vectors of strings of the file extensions associated
2819 /// with the file format. (Added in OIIO 2.2.13.)
2820 inline std::map<std::string, std::vector<std::string>>
2822 {
2823  std::map<std::string, std::vector<std::string>> map;
2824  auto all_extensions = OIIO::get_string_attribute("extension_list");
2825  for (auto oneformat : OIIO::Strutil::splitsv(all_extensions, ";")) {
2826  auto format_exts = OIIO::Strutil::splitsv(oneformat, ":", 2);
2827  if (format_exts.size() != 2)
2828  continue; // something went wrong
2829  map[format_exts[0]] = OIIO::Strutil::splits(format_exts[1], ",");
2830  }
2831  return map;
2832 }
2833 
2834 
2835 
2836 /// Helper function: convert contiguous data between two arbitrary pixel
2837 /// data types (specified by TypeDesc's). Return true if ok, false if it
2838 /// didn't know how to do the conversion. If dst_type is UNKNOWN, it will
2839 /// be assumed to be the same as src_type.
2840 ///
2841 /// The conversion is of normalized (pixel-like) values -- for example
2842 /// 'UINT8' 255 will convert to float 1.0 and vice versa, not float 255.0.
2843 /// If you want a straight C-like data cast convertion (e.g., uint8 255 ->
2844 /// float 255.0), then you should prefer the un-normalized convert_type()
2845 /// utility function found in typedesc.h.
2846 OIIO_API bool convert_pixel_values (TypeDesc src_type, const void *src,
2847  TypeDesc dst_type, void *dst, int n = 1);
2848 
2849 /// DEPRECATED(2.1): old name
2850 inline bool convert_types (TypeDesc src_type, const void *src,
2851  TypeDesc dst_type, void *dst, int n = 1) {
2852  return convert_pixel_values (src_type, src, dst_type, dst, n);
2853 }
2854 
2855 
2856 /// Helper routine for data conversion: Convert an image of nchannels x
2857 /// width x height x depth from src to dst. The src and dst may have
2858 /// different data formats and layouts. Clever use of this function can
2859 /// not only exchange data among different formats (e.g., half to 8-bit
2860 /// unsigned), but also can copy selective channels, copy subimages,
2861 /// etc. If you're lazy, it's ok to pass AutoStride for any of the
2862 /// stride values, and they will be auto-computed assuming contiguous
2863 /// data. Return true if ok, false if it didn't know how to do the
2864 /// conversion.
2865 OIIO_API bool convert_image (int nchannels, int width, int height, int depth,
2866  const void *src, TypeDesc src_type,
2867  stride_t src_xstride, stride_t src_ystride,
2868  stride_t src_zstride,
2869  void *dst, TypeDesc dst_type,
2870  stride_t dst_xstride, stride_t dst_ystride,
2871  stride_t dst_zstride);
2872 /// DEPRECATED(2.0) -- the alpha_channel, z_channel were never used
2873 inline bool convert_image(int nchannels, int width, int height, int depth,
2874  const void *src, TypeDesc src_type,
2875  stride_t src_xstride, stride_t src_ystride, stride_t src_zstride,
2876  void *dst, TypeDesc dst_type,
2877  stride_t dst_xstride, stride_t dst_ystride, stride_t dst_zstride,
2878  int /*alpha_channel*/, int /*z_channel*/ = -1)
2879 {
2880  return convert_image(nchannels, width, height, depth, src, src_type,
2881  src_xstride, src_ystride, src_zstride, dst, dst_type,
2882  dst_xstride, dst_ystride, dst_zstride);
2883 }
2884 
2885 
2886 /// A version of convert_image that will break up big jobs into multiple
2887 /// threads.
2889  int nchannels, int width, int height, int depth,
2890  const void *src, TypeDesc src_type,
2891  stride_t src_xstride, stride_t src_ystride,
2892  stride_t src_zstride,
2893  void *dst, TypeDesc dst_type,
2894  stride_t dst_xstride, stride_t dst_ystride,
2895  stride_t dst_zstride, int nthreads=0);
2896 /// DEPRECATED(2.0) -- the alpha_channel, z_channel were never used
2898  int nchannels, int width, int height, int depth,
2899  const void *src, TypeDesc src_type,
2900  stride_t src_xstride, stride_t src_ystride, stride_t src_zstride,
2901  void *dst, TypeDesc dst_type,
2902  stride_t dst_xstride, stride_t dst_ystride, stride_t dst_zstride,
2903  int /*alpha_channel*/, int /*z_channel*/, int nthreads=0)
2904 {
2905  return parallel_convert_image (nchannels, width, height, depth,
2906  src, src_type, src_xstride, src_ystride, src_zstride,
2907  dst, dst_type, dst_xstride, dst_ystride, dst_zstride, nthreads);
2908 }
2909 
2910 /// Add random [-ditheramplitude,ditheramplitude] dither to the color channels
2911 /// of the image. Dither will not be added to the alpha or z channel. The
2912 /// image origin and dither seed values allow a reproducible (or variable)
2913 /// dither pattern. If the strides are set to AutoStride, they will be
2914 /// assumed to be contiguous floats in data of the given dimensions.
2915 OIIO_API void add_dither (int nchannels, int width, int height, int depth,
2916  float *data,
2917  stride_t xstride, stride_t ystride, stride_t zstride,
2918  float ditheramplitude,
2919  int alpha_channel = -1, int z_channel = -1,
2920  unsigned int ditherseed = 1,
2921  int chorigin=0, int xorigin=0,
2922  int yorigin=0, int zorigin=0);
2923 
2924 /// Convert unassociated to associated alpha by premultiplying all color
2925 /// (non-alpha, non-z) channels by alpha. The nchannels, width, height, and
2926 /// depth parameters describe the "shape" of the image data (along with
2927 /// optional stride overrides). The chbegin/chend describe which range of
2928 /// channels to actually premultiply.
2929 OIIO_API void premult (int nchannels, int width, int height, int depth,
2930  int chbegin, int chend,
2931  TypeDesc datatype, void *data, stride_t xstride,
2932  stride_t ystride, stride_t zstride,
2933  int alpha_channel = -1, int z_channel = -1);
2934 
2935 /// Helper routine for data conversion: Copy an image of nchannels x
2936 /// width x height x depth from src to dst. The src and dst may have
2937 /// different data layouts, but must have the same data type. Clever
2938 /// use of this function can change layouts or strides, copy selective
2939 /// channels, copy subimages, etc. If you're lazy, it's ok to pass
2940 /// AutoStride for any of the stride values, and they will be
2941 /// auto-computed assuming contiguous data. Return true if ok, false if
2942 /// it didn't know how to do the conversion.
2943 OIIO_API bool copy_image (int nchannels, int width, int height, int depth,
2944  const void *src, stride_t pixelsize,
2945  stride_t src_xstride, stride_t src_ystride,
2946  stride_t src_zstride,
2947  void *dst, stride_t dst_xstride,
2948  stride_t dst_ystride, stride_t dst_zstride);
2949 
2950 
2951 // All the wrap_foo functions implement a wrap mode, wherein coord is
2952 // altered to be origin <= coord < origin+width. The return value
2953 // indicates if the resulting wrapped value is valid (example, for
2954 // wrap_black, values outside the region are invalid and do not modify
2955 // the coord parameter).
2956 OIIO_API bool wrap_black (int &coord, int origin, int width);
2957 OIIO_API bool wrap_clamp (int &coord, int origin, int width);
2958 OIIO_API bool wrap_periodic (int &coord, int origin, int width);
2959 OIIO_API bool wrap_periodic_pow2 (int &coord, int origin, int width);
2960 OIIO_API bool wrap_mirror (int &coord, int origin, int width);
2961 
2962 // Typedef for the function signature of a wrap implementation.
2963 typedef bool (*wrap_impl) (int &coord, int origin, int width);
2964 
2965 
2966 /// `debug(format, ...)` prints debugging message when attribute "debug" is
2967 /// nonzero, which it is by default for DEBUG compiles or when the
2968 /// environment variable OPENIMAGEIO_DEBUG is set. This is preferred to raw
2969 /// output to stderr for debugging statements.
2970 OIIO_API void debug (string_view str);
2971 
2972 /// debug output with `std::format` conventions.
2973 template<typename T1, typename... Args>
2974 void debugfmt (const char* fmt, const T1& v1, const Args&... args)
2975 {
2976  debug (Strutil::fmt::format(fmt, v1, args...));
2977 }
2978 
2979 // (Unfortunate old synonym)
2980 template<typename T1, typename... Args>
2981 OIIO_DEPRECATED("use `debugfmt` instead")
2982 void fmtdebug (const char* fmt, const T1& v1, const Args&... args)
2983 {
2984  debug (Strutil::fmt::format(fmt, v1, args...));
2985 }
2986 
2987 /// debug output with printf conventions.
2988 template<typename T1, typename... Args>
2989 void debugf (const char* fmt, const T1& v1, const Args&... args)
2990 {
2991  debug (Strutil::sprintf(fmt, v1, args...));
2992 }
2993 
2994 /// debug output with the same conventions as Strutil::format. Beware, this
2995 /// will change one day!
2996 template<typename T1, typename... Args>
2998 void debug (const char* fmt, const T1& v1, const Args&... args)
2999 {
3000  debug (Strutil::format(fmt, v1, args...));
3001 }
3002 
3003 
3004 // to force correct linkage on some systems
3006 
int chend
Definition: imageio.h:100
int tile_width
tile width (0 for a non-tiled image)
Definition: imageio.h:267
int nchannels
number of image channels, e.g., 4 for RGBA
Definition: imageio.h:271
static void auto_stride(stride_t &xstride, TypeDesc format, int nchannels) noexcept
Definition: imageio.h:463
int alpha_channel
Definition: imageio.h:291
std::unique_ptr< ImageInput > unique_ptr
unique_ptr to an ImageInput
Definition: imageio.h:827
32-bit IEEE floating point values, (C/C++ float).
Definition: typedesc.h:82
std::unique_ptr< ImageOutput > unique_ptr
unique_ptr to an ImageOutput.
Definition: imageio.h:1773
bool read_native_deep_image(DeepData &deepdata)
Definition: imageio.h:1549
GLuint GLsizei const GLchar * message
Definition: glcorearb.h:2543
OIIO_API bool wrap_periodic_pow2(int &coord, int origin, int width)
OIIO_API std::string geterror(bool clear=true)
typedef int(APIENTRYP RE_PFNGLXSWAPINTERVALSGIPROC)(int)
int xend
Definition: imageio.h:97
OIIO_API bool has_error()
Is there a pending global error message waiting to be retrieved?
void set_roi(const ROI &r) noexcept
Definition: imageio.h:730
int tile_depth
Definition: imageio.h:269
string_view channel_name(int chan) const
Definition: imageio.h:697
int64_t stride_t
Definition: imageio.h:48
GT_API const UT_StringHolder filename
bool convert_types(TypeDesc src_type, const void *src, TypeDesc dst_type, void *dst, int n=1)
DEPRECATED(2.1): old name.
Definition: imageio.h:2850
virtual bool set_ioproxy(Filesystem::IOProxy *ioproxy)
Definition: imageio.h:1645
bool seek_subimage(int subimage, int miplevel, ImageSpec &newspec)
Definition: imageio.h:1165
void errorfmt(const char *fmt, const Args &...args) const
Definition: imageio.h:1690
virtual bool open(const std::string &filename, int subimages OIIO_MAYBE_UNUSED, const ImageSpec *specs)
Definition: imageio.h:2016
OIIO_UTIL_API std::vector< string_view > splitsv(string_view str, string_view sep="", int maxsplit=-1)
*get result *(waiting if necessary)*A common idiom is to fire a bunch of sub tasks at the and then *wait for them to all complete We provide a helper class
Definition: thread.h:623
ImageOutput *(* Creator)()
Definition: imageio.h:2421
void
Definition: png.h:1083
const ImageSpec & spec(void) const
Definition: imageio.h:2034
bool valid_file(const std::wstring &filename) const
Check valid vile using a UTF-16 encoded wstring filename.
Definition: imageio.h:1021
constexpr imagesize_t npixels() const noexcept
Total number of pixels in the region.
Definition: imageio.h:134
bool undefined() const noexcept
Definition: imageio.h:784
std::string format(const Str &fmt, Args &&...args)
Definition: strutil.h:121
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
bool read_tile(int x, int y, int z, float *data)
Simple read_tile reads into contiguous float pixels.
Definition: imageio.h:1339
constexpr bool contains(int x, int y, int z=0, int ch=0) const noexcept
Test if the coordinate is within the ROI.
Definition: imageio.h:163
friend constexpr bool operator==(const ROI &a, const ROI &b) noexcept
Test equality of two ROIs.
Definition: imageio.h:148
void get_channelformats(std::vector< TypeDesc > &formats) const
Definition: imageio.h:706
ROI roi_full() const noexcept
Return full/display window for this ImageSpec expressed as a ROI.
Definition: imageio.h:722
GLdouble GLdouble GLdouble z
Definition: glcorearb.h:848
static unique_ptr open(const std::wstring &filename, const ImageSpec *config=nullptr, Filesystem::IOProxy *ioproxy=nullptr)
Create and open an ImageInput using a UTF-16 encoded wstring filename.
Definition: imageio.h:872
ImageSpec m_spec
Definition: imageio.h:1742
virtual int current_subimage(void) const
Definition: imageio.h:1137
GLboolean GLboolean GLboolean GLboolean a
Definition: glcorearb.h:1222
unknown type
Definition: typedesc.h:57
GLdouble s
Definition: glad.h:3009
static unique_ptr create(const std::wstring &filename, Filesystem::IOProxy *ioproxy=nullptr, const std::wstring &plugin_searchpath={})
Definition: imageio.h:1809
constexpr ROI() noexcept
Definition: imageio.h:105
OIIO_API bool wrap_periodic(int &coord, int origin, int width)
bool open(const std::wstring &name, ImageSpec &newspec, const ImageSpec &config OIIO_MAYBE_UNUSED)
Open the ImageInput using a UTF-16 encoded wstring filename.
Definition: imageio.h:1074
TypeDesc channelformat(int chan) const
Definition: imageio.h:690
ImageBuf OIIO_API min(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
int depth
depth of pixel data, >1 indicates a "volume"
Definition: imageio.h:260
int full_height
height of the full (display) window
Definition: imageio.h:265
std::vector< std::string > channelnames
Definition: imageio.h:288
OIIO_API void declare_imageio_format(const std::string &format_name, ImageInput::Creator input_creator, const char **input_extensions, ImageOutput::Creator output_creator, const char **output_extensions, const char *lib_version)
void copy_dimensions(const ImageSpec &other)
Definition: imageio.h:756
#define OIIO_DEPRECATED(msg)
Definition: platform.h:458
GLint y
Definition: glcorearb.h:103
void attribute(string_view name, int value)
Add an int attribute to extra_attribs.
Definition: imageio.h:479
std::lock_guard< const ImageInput & > lock_guard
Definition: imageio.h:1730
bool read_scanline(int y, int z, float *data)
Simple read_scanline reads into contiguous float pixels.
Definition: imageio.h:1246
int tile_height
tile height (0 for a non-tiled image)
Definition: imageio.h:268
virtual const ImageSpec & spec(void) const
Definition: imageio.h:1085
void close() override
static constexpr ROI All() noexcept
Definition: imageio.h:145
String-related utilities, all in namespace Strutil.
void attribute(string_view name, string_view value)
Add a string attribute to extra_attribs.
Definition: imageio.h:489
int zend
Definition: imageio.h:99
OIIO_FORMAT_DEPRECATED void error(const char *fmt, const Args &...args) const
Definition: imageio.h:2367
friend std::ostream & operator<<(std::ostream &out, const ROI &roi)
Stream output of the range.
Definition: imageio.h:177
ImageInput *(* Creator)()
Definition: imageio.h:1739
static unique_ptr create(const std::wstring &filename, bool do_open=false, const ImageSpec *config=nullptr, Filesystem::IOProxy *ioproxy=nullptr, string_view plugin_searchpath="")
Create an ImageInput using a UTF-16 encoded wstring filename.
Definition: imageio.h:939
bool read_native_deep_tiles(int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, int chbegin, int chend, DeepData &deepdata)
Definition: imageio.h:1542
bool valid_tile_range(int xbegin, int xend, int ybegin, int yend, int zbegin, int zend) noexcept
Definition: imageio.h:677
std::map< std::string, std::vector< std::string > > get_extension_map()
Definition: imageio.h:2821
OIIO_API void premult(int nchannels, int width, int height, int depth, int chbegin, int chend, TypeDesc datatype, void *data, stride_t xstride, stride_t ystride, stride_t zstride, int alpha_channel=-1, int z_channel=-1)
OIIO_API void add_dither(int nchannels, int width, int height, int depth, float *data, stride_t xstride, stride_t ystride, stride_t zstride, float ditheramplitude, int alpha_channel=-1, int z_channel=-1, unsigned int ditherseed=1, int chorigin=0, int xorigin=0, int yorigin=0, int zorigin=0)
basic_string_view< char > string_view
Definition: core.h:522
constexpr size_type size() const noexcept
Definition: string_view.h:150
OIIO_API bool wrap_black(int &coord, int origin, int width)
static void auto_stride(stride_t &xstride, stride_t &ystride, stride_t &zstride, TypeDesc format, int nchannels, int width, int height) noexcept
Definition: imageio.h:454
void errorfmt(const char *fmt, const Args &...args) const
Definition: imageio.h:2383
virtual int current_miplevel(void) const
Definition: imageio.h:1142
GLint GLsizei GLsizei height
Definition: glcorearb.h:103
Wrappers and utilities for multithreading.
#define OIIO_MAYBE_UNUSED
Definition: platform.h:433
virtual bool seek_subimage(int subimage, int miplevel)
Definition: imageio.h:1157
GLdouble n
Definition: glcorearb.h:2008
constexpr int height() const noexcept
Width.
Definition: imageio.h:124
constexpr ROI roi_intersection(const ROI &A, const ROI &B) noexcept
Intersection of two regions.
Definition: imageio.h:198
bool(* ProgressCallback)(void *opaque_data, float portion_done)
Definition: imageio.h:65
void errorf(const char *fmt, const Args &...args) const
Definition: imageio.h:1682
ImageSpec m_spec
format spec of the currently open image
Definition: imageio.h:2480
int open(float queuesize) override
void debugfmt(const char *fmt, const T1 &v1, const Args &...args)
debug output with std::format conventions.
Definition: imageio.h:2974
constexpr bool defined() const noexcept
Is a region defined?
Definition: imageio.h:118
virtual bool set_ioproxy(Filesystem::IOProxy *ioproxy)
Definition: imageio.h:2338
virtual int supports(string_view feature OIIO_MAYBE_UNUSED) const
Definition: imageio.h:1003
OIIO_API bool convert_image(int nchannels, int width, int height, int depth, const void *src, TypeDesc src_type, stride_t src_xstride, stride_t src_ystride, stride_t src_zstride, void *dst, TypeDesc dst_type, stride_t dst_xstride, stride_t dst_ystride, stride_t dst_zstride)
constexpr int depth() const noexcept
Definition: imageio.h:125
void set_roi_full(const ROI &r) noexcept
Definition: imageio.h:742
OIIO_API bool parallel_convert_image(int nchannels, int width, int height, int depth, const void *src, TypeDesc src_type, stride_t src_xstride, stride_t src_ystride, stride_t src_zstride, void *dst, TypeDesc dst_type, stride_t dst_xstride, stride_t dst_ystride, stride_t dst_zstride, int nthreads=0)
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
constexpr ROI roi_union(const ROI &A, const ROI &B) noexcept
Union of two regions, the smallest region containing both.
Definition: imageio.h:188
constexpr int nchannels() const noexcept
Definition: imageio.h:131
SerialFormat
Definition: imageio.h:647
friend constexpr bool operator!=(const ROI &a, const ROI &b) noexcept
Test inequality of two ROIs.
Definition: imageio.h:155
virtual bool get_thumbnail(ImageBuf &thumb, int subimage)
Definition: imageio.h:1121
void attribute(string_view name, unsigned int value)
Add an unsigned int attribute to extra_attribs.
Definition: imageio.h:474
int full_width
width of the full (display) window
Definition: imageio.h:264
OIIO_API void _ImageIO_force_link()
bool deep
Definition: imageio.h:300
OIIO_API bool wrap_mirror(int &coord, int origin, int width)
GLuint const GLchar * name
Definition: glcorearb.h:786
OIIO_HOSTDEVICE size_t size() const noexcept
Definition: typedesc.h:207
int full_y
origin of the full (display) window
Definition: imageio.h:262
void set_format(string_view fmt) noexcept
Definition: imageio.h:356
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1222
GLint GLenum GLint x
Definition: glcorearb.h:409
bool read_image(float *data)
Definition: imageio.h:1471
float get_float_attribute(string_view name, float defaultval=0)
Definition: imageio.h:2791
GLenum mode
Definition: glcorearb.h:99
GLint GLint GLsizei GLsizei GLsizei depth
Definition: glcorearb.h:476
ROI roi() const noexcept
Return pixel data window for this ImageSpec expressed as a ROI.
Definition: imageio.h:717
Character string.
Definition: typedesc.h:84
virtual bool set_thumbnail(const ImageBuf &thumb)
Definition: imageio.h:2301
ParamValue ImageIOParameter
Definition: imageio.h:70
int full_depth
depth of the full (display) window
Definition: imageio.h:266
OIIO_API void debug(string_view str)
OIIO_API bool wrap_clamp(int &coord, int origin, int width)
std::vector< TypeDesc > channelformats
Definition: imageio.h:278
int x
origin (upper left corner) of pixel data
Definition: imageio.h:255
GLsizeiptr size
Definition: glcorearb.h:664
OIIO_API bool is_imageio_format_name(string_view name)
Is name one of the known format names?
GLenum GLenum dst
Definition: glcorearb.h:1793
OIIO_API int openimageio_version()
virtual bool open(const std::string &name, ImageSpec &newspec, const ImageSpec &config OIIO_MAYBE_UNUSED)
Definition: imageio.h:1069
Definition: imageio.h:85
OIIO_API bool getattribute(string_view name, TypeDesc type, void *val)
static void auto_stride(stride_t &xstride, stride_t &ystride, stride_t &zstride, stride_t channelsize, int nchannels, int width, int height) noexcept
Definition: imageio.h:440
constexpr int width() const noexcept
Height.
Definition: imageio.h:123
const stride_t AutoStride
Definition: imageio.h:56
bool seek_subimage(int subimage, ImageSpec &newspec)
Definition: imageio.h:1175
int z
origin (upper left corner) of pixel data
Definition: imageio.h:257
ParamValueList extra_attribs
Definition: imageio.h:305
bool read_native_deep_scanlines(int ybegin, int yend, int z, int chbegin, int chend, DeepData &deepdata)
Definition: imageio.h:1536
int xbegin
Definition: imageio.h:97
int full_z
origin of the full (display) window
Definition: imageio.h:263
int width
width of the pixel data window
Definition: imageio.h:258
int chbegin
Definition: imageio.h:100
OIIO_FORMAT_DEPRECATED void error(const char *fmt, const Args &...args) const
Definition: imageio.h:1674
bool(* wrap_impl)(int &coord, int origin, int width)
Definition: imageio.h:2963
OIIO_UTIL_API std::vector< std::string > splits(string_view str, string_view sep="", int maxsplit=-1)
GLfloat GLfloat v1
Definition: glcorearb.h:817
auto ptr(T p) -> const void *
Definition: format.h:2448
GLuint GLfloat * val
Definition: glcorearb.h:1608
ImageBuf OIIO_API max(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
void fmtdebug(const char *fmt, const T1 &v1, const Args &...args)
Definition: imageio.h:2982
int z_channel
Definition: imageio.h:296
constexpr bool contains(const ROI &other) const noexcept
Test if another ROI is entirely within our ROI.
Definition: imageio.h:169
OIIO_API bool attribute(string_view name, TypeDesc type, const void *val)
SerialVerbose
Definition: imageio.h:648
**If you just want to fire and args
Definition: thread.h:609
GLint GLsizei width
Definition: glcorearb.h:103
AttrDelegate< ImageSpec > operator[](string_view name)
Definition: imageio.h:809
ParamValueList ImageIOParameterList
Definition: imageio.h:71
#define OIIO_FORMAT_DEPRECATED
Definition: strutil.h:49
Definition: core.h:1131
constexpr ROI(int xbegin, int xend, int ybegin, int yend, int zbegin=0, int zend=1, int chbegin=0, int chend=10000) noexcept
Definition: imageio.h:111
int height
height of the pixel data window
Definition: imageio.h:259
GLboolean r
Definition: glcorearb.h:1222
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:94
auto sprintf(const S &fmt, const T &...args) -> std::basic_string< Char >
Definition: printf.h:574
const char * c_str() const
void debugf(const char *fmt, const T1 &v1, const Args &...args)
debug output with printf conventions.
Definition: imageio.h:2989
int zbegin
Definition: imageio.h:99
int yend
Definition: imageio.h:98
AttrDelegate< const ImageSpec > operator[](string_view name) const
Definition: imageio.h:813
string_view get_string_attribute(string_view name, string_view defaultval=string_view())
Definition: imageio.h:2797
bool open(const std::wstring &filename, const ImageSpec &newspec, OpenMode mode=Create)
Open an ImageOutput using a UTF-16 encoded wstring filename.
Definition: imageio.h:1989
std::string OIIO_UTIL_API utf16_to_utf8(const std::wstring &utf16str) noexcept
type
Definition: core.h:1059
OIIO_API bool copy_image(int nchannels, int width, int height, int depth, const void *src, stride_t pixelsize, stride_t src_xstride, stride_t src_ystride, stride_t src_zstride, void *dst, stride_t dst_xstride, stride_t dst_ystride, stride_t dst_zstride)
int get_int_attribute(string_view name, int defaultval=0)
Definition: imageio.h:2784
uint64_t imagesize_t
Definition: imageio.h:52
const std::string & string() const noexcept
Return a C++ std::string representation of a ustring.
Definition: ustring.h:278
OIIO_API bool convert_pixel_values(TypeDesc src_type, const void *src, TypeDesc dst_type, void *dst, int n=1)
virtual int supports(string_view feature OIIO_MAYBE_UNUSED) const
Definition: imageio.h:1962
TypeDesc format
Definition: imageio.h:273
void attribute(string_view name, float value)
Add a float attribute to extra_attribs.
Definition: imageio.h:484
void errorf(const char *fmt, const Args &...args) const
Definition: imageio.h:2375
Definition: format.h:895
OpenMode
Modes passed to the open() call.
Definition: imageio.h:1967
bool open(const std::wstring &filename, int subimages OIIO_MAYBE_UNUSED, const ImageSpec *specs)
Modes passed to the open() call.
Definition: imageio.h:2024
int full_x
origin of the full (display) window
Definition: imageio.h:261
bool open(const std::wstring &name, ImageSpec &newspec)
Open the ImageInput using a UTF-16 encoded wstring filename.
Definition: imageio.h:1045
int ybegin
Definition: imageio.h:98
int y
origin (upper left corner) of pixel data
Definition: imageio.h:256
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:93
#define OIIO_API
Definition: export.h:65
GLenum src
Definition: glcorearb.h:1793