|
HDK
|
#include <imagebuf.h>
Classes | |
| class | ConstIterator |
| class | Iterator |
| class | IteratorBase |
Public Types | |
| enum | IBStorage { UNINITIALIZED, LOCALBUFFER, APPBUFFER, IMAGECACHE } |
| enum | WrapMode { WrapDefault, WrapBlack, WrapClamp, WrapPeriodic, WrapMirror, _WrapLast } |
Static Public Member Functions | |
| static WrapMode | WrapMode_from_string (string_view name) |
Protected Member Functions | |
| const void * | retile (int x, int y, int z, pvt::ImageCacheTile *&tile, int &tilexbegin, int &tileybegin, int &tilezbegin, int &tilexend, bool exists, WrapMode wrap=WrapDefault) const |
| const void * | blackpixel () const |
| bool | do_wrap (int &x, int &y, int &z, WrapMode wrap) const |
Static Protected Member Functions | |
| static void | impl_deleter (ImageBufImpl *) |
Protected Attributes | |
| std::unique_ptr< ImageBufImpl, decltype(&impl_deleter)> | m_impl |
Friends | |
| class | IteratorBase |
An ImageBuf is a simple in-memory representation of a 2D image. It uses ImageInput and ImageOutput underneath for its file I/O, and has simple routines for setting and getting individual pixels, that hides most of the details of memory layout and data representation (translating to/from float automatically).
ImageBuf makes an important simplification: all channels are just one data type. For example, if an image file on disk has a mix of half and float channels, the in-memory ImageBuf representation will be entirely float (for mixed data types, it will try to pick one that can best represent all channels without a loss of precision or range). However, by using the set_write_format() method, it is still possible to write an ImageBuf to a file with mixed channel types.
Most of the time, ImageBuf data is read lazily (I/O only happens when you first call methods that actually need metadata or pixel data). Explicit calls to read() are therefore optional and are only needed if you want to specify non-default arguments (such as choosing something other than the first subimage of the file, or forcing the read to translate into a different data format than appears in the file).
ImageBuf data coming from disk files is backed by ImageCache. That is, especially for tiled files, specific regions of the image will only be read if and when they are needed, and if there are many large ImageBuf's, memory holding pixels not recently accesssed will be automatically freed. Thus, performance of ImageBuf on very large images (or if there are many ImageBuf's simultaneously in use) can be sensitive to choices of the ImageCache parameters such as "autotile". It may be wise for maximum performance to explicitly read() (with force=true) small images into memory rather than using the ImageCache, in cases where your application has no need for the ImageCache features that limit memory footprint (such as if you know for sure that your app will only read a small number of images, of reasonable size, and will need to access all the pixels of all the images it reads).
Writeable ImageBufs are always stored entirely in memory, and do not use the ImageCache or any other clever schemes to limit memory. If you have enough simultaneous writeable large ImageBuf's, you can run out of RAM. Note that if an ImageBuf starts as readable (backed by ImageCache), any alterations to its pixels (for example, via setpixel() or traversing it with a non-const Iterator) will cause it to be read entirely into memory and remain in memory thereafter for the rest of the life of that ImageBuf.
Notes about ImageBuf thread safety:
init_spec(), read(), spec(), all the getpixel flavors and ConstIterator over the pixels, and other informational methods such as roi(), all are thread-safe and may be called concurrently with any of the other thread-safe methods.Iterator over the pixels, and the write() method are "thread safe" in the sense that you won't crash your app by doing these concurrently with each other or with the reading functionality, but on the other hand, if two threads are changing the same pixels simultaneously or one is writing while others are reading, you may end up with an inconsistent resulting image.reset(), and anything that alters image metadata (such as writes through specmod()) are NOT THREAD SAFE and you should ensure that you are not doing any of these calls simultaneously with any other operations on the same ImageBuf. Definition at line 121 of file imagebuf.h.
| enum ImageBuf::IBStorage |
An ImageBuf can store its pixels in one of several ways (each identified by an IBStorage enumerated value):
| Enumerator | |
|---|---|
| UNINITIALIZED |
An ImageBuf that doesn't represent any image at all (either because it is newly constructed with the default constructor, or had an error during construction). |
| LOCALBUFFER |
"Local storage" is allocated to hold the image pixels internal to the ImageBuf. This memory will be freed when the ImageBuf is destroyed. |
| APPBUFFER |
The ImageBuf "wraps" pixel memory already allocated and owned by the calling application. The caller will continue to own that memory and be responsible for freeing it after the ImageBuf is destroyed. |
| IMAGECACHE |
The ImageBuf is "backed" by an ImageCache, which will automatically be used to retrieve pixels when requested, but the ImageBuf will not allocate separate storage for it. This brings all the advantages of the ImageCache, but can only be used for read-only ImageBuf's that reference a stored image file. |
Definition at line 125 of file imagebuf.h.
| enum ImageBuf::WrapMode |
Wrap mode describes what happens when an iterator points to a value outside the usual data range of an image.
| Enumerator | |
|---|---|
| WrapDefault | |
| WrapBlack | |
| WrapClamp | |
| WrapPeriodic | |
| WrapMirror | |
| _WrapLast | |
Definition at line 341 of file imagebuf.h.
| ImageBuf::ImageBuf | ( | ) |
| ImageBuf::~ImageBuf | ( | ) |
Destructor for an ImageBuf.
|
explicit |
Construct a read-only ImageBuf that will be used to read the named file (at the given subimage and MIP-level, defaulting to the first in the file). But don't read it yet! The image will actually be read lazily, only when other methods need to access the spec and/or pixels, or when an explicit call to init_spec() or read() is made, whichever comes first.
The implementation may end up either reading the entire image internally owned memory (if so, the storage will be LOCALBUFFER), or it may rely on being backed by an ImageCache (in this case, the storage will be IMAGECACHE) – depending on the image size and other factors.
| name | The image to read. |
| subimage/miplevel | The subimage and MIP level to read (defaults to the first subimage of the file, highest-res MIP level). |
| imagecache | Optionally, a particular ImageCache to use. If nullptr, the default global/shared image cache will be used. If a custom ImageCache (not the global/shared one), it is important that the IC should not be destroyed while the ImageBuf is still alive. |
| config | Optionally, a pointer to an ImageSpec whose metadata contains configuration hints that set options related to the opening and reading of the file. |
| ioproxy | Optional pointer to an IOProxy to use when reading from the file. The caller retains ownership of the proxy. |
| ImageBuf::ImageBuf | ( | string_view | name, |
| ImageCache * | imagecache | ||
| ) |
|
explicit |
Construct a writable ImageBuf with the given specification (including resolution, data type, metadata, etc.). The ImageBuf will allocate and own its own pixel memory and will free that memory automatically upon destruction, clear(), or reset(). Upon successful initialization, the storage will be reported as LOCALBUFFER.
| spec | An ImageSpec describing the image and its metadata. If not enough information is given to know how much memory to allocate (width, height, depth, channels, and data format), the ImageBuf will remain in an UNINITIALIZED state and will have no local pixel storage. |
| zero | After a successful allocation of the local pixel storage, this parameter controls whether the pixels will be initialized to hold zero (black) values (InitializePixels::Yes) or if the pixel memory will remain uninitialized (InitializePixels::No) and thus may hold nonsensical values. Choosing No may save the time of writing to the pixel memory if you know for sure that you are about to overwrite it completely before you will need to read any pixel values. |
| ImageBuf::ImageBuf | ( | string_view | name, |
| const ImageSpec & | spec, | ||
| InitializePixels | zero = InitializePixels::Yes |
||
| ) |
| ImageBuf::ImageBuf | ( | const ImageSpec & | spec, |
| void * | buffer, | ||
| stride_t | xstride = AutoStride, |
||
| stride_t | ystride = AutoStride, |
||
| stride_t | zstride = AutoStride |
||
| ) |
Construct a writable ImageBuf that "wraps" existing pixel memory owned by the calling application. The ImageBuf does not own the pixel storage and will will not free/delete that memory, even when the ImageBuf is destroyed. Upon successful initialization, the storage will be reported as APPBUFFER.
| spec | An ImageSpec describing the image and its metadata. If not enough information is given to know the "shape" of the image (width, height, depth, channels, and data format), the ImageBuf will remain in an UNINITIALIZED state. |
| buffer | A pointer to the caller-owned memory containing the storage for the pixels. It must be already allocated with enough space to hold a full image as described by spec. |
| xstride/ystride/zstride | The distance in bytes between successive pixels, scanlines, and image planes in the buffer (or AutoStride to indicate "contiguous" data in any of those dimensions). |
| ImageBuf::ImageBuf | ( | string_view | name, |
| const ImageSpec & | spec, | ||
| void * | buffer | ||
| ) |
| bool ImageBuf::cachedpixels | ( | ) | const |
Are the pixels backed by an ImageCache, rather than the whole image being in RAM somewhere?
| void ImageBuf::clear | ( | ) |
Default constructor makes an empty/uninitialized ImageBuf. There isn't much you can do with an uninitialized buffer until you call reset(). The storage type of a default-constructed ImageBuf is IBStorage::UNINITIALIZED.
| void ImageBuf::clear_thumbnail | ( | ) |
Clear any thumbnail associated with this ImageBuf. This call will invalidate any references previously returned by thumbnail().
| bool ImageBuf::contains_roi | ( | ROI | roi | ) | const |
Is the specified roi completely contained in the data window of this ImageBuf?
| bool ImageBuf::contiguous | ( | ) | const |
Is the data layout "contiguous", i.e., ``` pixel_stride == nchannels * pixeltype().size() scanline_stride == pixel_stride * spec().width z_stride == scanline_stride * spec().height ```
Try to copy the pixels and metadata from src to *this (optionally with an explicit data format conversion).
If the previous state of *this was uninitialized, owning its own local pixel memory, or referring to a read-only image backed by ImageCache, then local pixel memory will be allocated to hold the new pixels and the call always succeeds unless the memory cannot be allocated. In this case, the format parameter may request a pixel data type that is different from that of the source buffer.
If *this previously referred to an app-owned memory buffer, the memory cannot be re-allocated, so the call will only succeed if the app-owned buffer is already the correct resolution and number of channels. The data type of the pixels will be converted automatically to the data type of the app buffer.
| src | Another ImageBuf from which to copy the pixels and metadata. |
| format | Optionally request the pixel data type to be used. The default of TypeUnknown means to use whatever data type is used by the src. If *this is already initialized and has APPBUFFER storage ("wrapping" an application buffer), this parameter is ignored. |
true upon success or false upon error/failure. Return a full copy of this ImageBuf (optionally with an explicit data format conversion).
| bool ImageBuf::copy_deep_pixel | ( | int | x, |
| int | y, | ||
| int | z, | ||
| const ImageBuf & | src, | ||
| int | srcx, | ||
| int | srcy, | ||
| int | srcz | ||
| ) |
Copy a deep pixel from another ImageBuf – it is required to have the same channels.
Copy all the metadata from src to *this (except for pixel data resolution, channel types and names, and data format).
Copy the pixel data from src to *this, automatically converting to the existing data format of *this. It only copies pixels in the overlap regions (and channels) of the two images; pixel data in *this that do exist in src will be set to 0, and pixel data in src that do not exist in *this will not be copied.
| bool ImageBuf::deep | ( | ) | const |
Remove nsamples samples, starting at position samplepos of pixel (x,y,z).
Insert nsamples new samples, starting at position samplepos of pixel (x,y,z).
Return a pointer to the raw data of pixel (x,y,z), channel c, sample s. Return nullptr if the pixel coordinates or channel number are out of range, if the pixel/channel has no deep samples, or if the image is not deep. Use with caution — these pointers may be invalidated by calls that adjust the number of samples in any pixel.
Retrieve the number of deep data samples corresponding to pixel (x,y,z). Return 0 if not a deep image, or if the pixel is outside of the data window, or if the designated pixel has no deep samples.
Return the value (as a float) of sample s of channel c of pixel (x,y,z). Return 0 if not a deep image or if the pixel coordinates or channel number are out of range or if that pixel has no deep samples.
Return the value (as a uint32_t) of sample s of channel c of pixel (x,y,z). Return 0 if not a deep image or if the pixel coordinates or channel number are out of range or if that pixel has no deep samples.
| DeepData* ImageBuf::deepdata | ( | ) |
Retrieve the "deep" data.
| void ImageBuf::error | ( | string_view | message | ) | const |
Add simple string to the error message list for this IB. It is not necessary to have the error message contain a trailing newline.
|
inline |
Error reporting for ImageBuf: call this with Strutil::format formatting conventions. It is not necessary to have the error message contain a trailing newline. Beware, this is in transition, is currently printf-like but will someday change to python-like!
Definition at line 1086 of file imagebuf.h.
|
inline |
Error reporting for ImageBuf: call this with printf-like arguments to report an error. It is not necessary to have the error message contain a trailing newline.
Definition at line 1076 of file imagebuf.h.
|
inline |
Error reporting for ImageBuf: call this with std::format style formatting specification. It is not necessary to have the error message contain a trailing newline.
Definition at line 1067 of file imagebuf.h.
| string_view ImageBuf::file_format_name | ( | void | ) | const |
|
inline |
Add simple string to the error message list for this IB. It is not necessary to have the error message contain a trailing newline.
Definition at line 1096 of file imagebuf.h.
| bool ImageBuf::get_pixels | ( | ROI | roi, |
| TypeDesc | format, | ||
| void * | result, | ||
| stride_t | xstride = AutoStride, |
||
| stride_t | ystride = AutoStride, |
||
| stride_t | zstride = AutoStride |
||
| ) | const |
Retrieve the rectangle of pixels spanning the ROI (including channels) at the current subimage and MIP-map level, storing the pixel values beginning at the address specified by result and with the given strides (by default, AutoStride means the usual contiguous packing of pixels) and converting into the data type described by format. It is up to the caller to ensure that result points to an area of memory big enough to accommodate the requested rectangle. Return true if the operation could be completed, otherwise return false.
| std::shared_ptr<ImageBuf> ImageBuf::get_thumbnail | ( | ) | const |
Return a shared pointer to an ImageBuf containing a thumbnail of the image (if it existed in the file), which may be empty if there is no thumbnail.
Retrieve a single channel of one pixel.
| x/y/z | The pixel coordinates. |
| c | The channel index to retrieve. |
| wrap | WrapMode that determines the behavior if the pixel coordinates are outside the data window: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror. |
float. | std::string ImageBuf::geterror | ( | bool | clear = true | ) | const |
Return the text of all pending error messages issued against this ImageBuf, and clear the pending error message unless clear is false. If no error message is pending, it will return an empty string.
| void ImageBuf::getpixel | ( | int | x, |
| int | y, | ||
| int | z, | ||
| float * | pixel, | ||
| int | maxchannels = 1000, |
||
| WrapMode | wrap = WrapBlack |
||
| ) | const |
Retrieve the pixel value by x, y, z pixel indices, placing its contents in pixel[0..n-1] where n is the smaller of maxchannels the actual number of channels stored in the buffer.
| x/y/z | The pixel coordinates. |
| pixel | The results are stored in pixel[0..nchannels-1]. It is up to the caller to ensure that pixel points to enough memory to hold the required number of channels. |
| maxchannels | Optional clamp to the number of channels retrieved. |
| wrap | WrapMode that determines the behavior if the pixel coordinates are outside the data window: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror. |
Retrieve a single channel of one pixel.
| x/y/z | The pixel coordinates. |
| c | The channel index to retrieve. |
| wrap | WrapMode that determines the behavior if the pixel coordinates are outside the data window: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror. |
float. Definition at line 700 of file imagebuf.h.
| bool ImageBuf::has_error | ( | void | ) | const |
Returns true if the ImageBuf has had an error and has an error message ready to retrieve via geterror().
| bool ImageBuf::has_thumbnail | ( | ) | const |
Does this ImageBuf have an associated thumbnail?
| ImageCache* ImageBuf::imagecache | ( | ) | const |
A pointer to the underlying ImageCache.
|
staticprotected |
| bool ImageBuf::init_spec | ( | string_view | filename, |
| int | subimage, | ||
| int | miplevel | ||
| ) |
Read the ImageSpec for the given file, subimage, and MIP level into the ImageBuf, but will not read the pixels or allocate any local storage (until a subsequent call to read()). This is helpful if you have an ImageBuf and you need to know information about the image, but don't want to do a full read yet, and maybe won't need to do the full read, depending on what's found in the spec.
Note that init_spec() is not strictly necessary. If you are happy with the filename, subimage and MIP level specified by the ImageBuf constructor (or the last call to reset()), then the spec will be automatically read the first time you make any other ImageBuf API call that requires it. The only reason to call read() yourself is if you are changing the filename, subimage, or MIP level, or if you want to use force=true or a specific convert value to force data format conversion.
| filename | The filename to read from (should be the same as the filename used when the ImageBuf was constructed or reset.) |
| subimage/miplevel | The subimage and MIP level to read. |
true upon success, or false if the read failed (in which case, you should be able to retrieve an error message via geterror()). | bool ImageBuf::initialized | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
Sample the image plane at pixel coordinates (x,y), using linear interpolation between pixels, placing the result in pixel[].
| x/y | The pixel coordinates. Note that pixel data values themselves are at the pixel centers, so pixel (i,j) is at image plane coordinate (i+0.5, j+0.5). |
| pixel | The results are stored in pixel[0..nchannels-1]. It is up to the caller to ensure that pixel points to enough memory to hold the number of channels in the image. |
| wrap | WrapMode that determines the behavior if the pixel coordinates are outside the data window: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror. |
| void ImageBuf::interppixel_bicubic | ( | float | x, |
| float | y, | ||
| float * | pixel, | ||
| WrapMode | wrap = WrapBlack |
||
| ) | const |
Bicubic interpolation at pixel coordinates (x,y).
| void ImageBuf::interppixel_bicubic_NDC | ( | float | s, |
| float | t, | ||
| float * | pixel, | ||
| WrapMode | wrap = WrapBlack |
||
| ) | const |
Bicubic interpolation at NDC space coordinates (s,t), where (0,0) is the upper left corner of the display (a.k.a. "full") window, (1,1) the lower right corner of the display window.
Linearly interpolate at NDC coordinates (s,t), where (0,0) is the upper left corner of the display window, (1,1) the lower right corner of the display window.
interppixel() uses pixel coordinates (ranging 0..resolution) whereas interppixel_NDC() uses NDC coordinates (ranging 0..1). | void ImageBuf::interppixel_NDC_full | ( | float | s, |
| float | t, | ||
| float * | pixel, | ||
| WrapMode | wrap = WrapBlack |
||
| ) | const |
Retrieve a single channel of one pixel.
| x/y/z | The pixel coordinates. |
| c | The channel index to retrieve. |
| wrap | WrapMode that determines the behavior if the pixel coordinates are outside the data window: WrapBlack, WrapClamp, WrapPeriodic, WrapMirror. |
float. | void* ImageBuf::localpixels | ( | ) |
Return a raw pointer to "local" pixel memory, if they are fully in RAM and not backed by an ImageCache, or nullptr otherwise. You can also test it like a bool to find out if pixels are local.
Note that the data are not necessarily contiguous; use the pixel_stride(), scanline_stride(), and z_stride() methods to find out the spacing between pixels, scanlines, and volumetric planes, respectively.
Returns true if the ImageBuf is initialized, false if not yet initialized.
| bool ImageBuf::make_writable | ( | bool | keep_cache_type = false | ) |
Make the ImageBuf be writable. That means that if it was previously backed by an ImageCache (storage was IMAGECACHE), it will force a full read so that the whole image is in local memory. This will invalidate any current iterators on the image. It has no effect if the image storage is not IMAGECACHE.
| keep_cache_type | If true, preserve any ImageCache-forced data types (you might want to do this if it is critical that the apparent data type doesn't change, for example if you are calling make_writable() from within a type-specialized function). |
true if it works (including if no read was necessary), false if something went horribly wrong. | bool ImageBuf::make_writeable | ( | bool | keep_cache_type = false | ) |
| int ImageBuf::miplevel | ( | ) | const |
| string_view ImageBuf::name | ( | void | ) | const |
Returns the name of the buffer (name of the file, for an ImageBuf read from disk).
Return a read-only (const) reference to the "native" image spec (that describes the file, which may be slightly different than the spec of the ImageBuf, particularly if the IB is backed by an ImageCache that is imposing some particular data format or tile size).
This may differ from spec() — for example, if a data format conversion was requested, if the buffer is backed by an ImageCache which stores the pixels internally in a different data format than that of the file, or if the file had differing per-channel data formats (ImageBuf must contain a single data format for all channels).
| int ImageBuf::nchannels | ( | ) | const |
Return the number of color channels in the image. This is equivalent to spec().nchannels.
| int ImageBuf::nmiplevels | ( | ) | const |
| int ImageBuf::nsubimages | ( | ) | const |
Read the particular subimage and MIP level of the image. Generally, this will skip the expensive read if the file has already been read into the ImageBuf (at the specified subimage and MIP level). It will clear and re-allocate memory if the previously allocated space was not appropriate for the size or data type of the image being read.
In general, read() will try not to do any I/O at the time of the read() call, but rather to have the ImageBuf "backed" by an ImageCache, which will do the file I/O on demand, as pixel values are needed, and in that case the ImageBuf doesn't actually allocate memory for the pixels (the data lives in the ImageCache). However, there are several conditions for which the ImageCache will be bypassed, the ImageBuf will allocate "local" memory, and the disk file will be read directly into allocated buffer at the time of the read() call: (a) if the force parameter is true; (b) if the convert parameter requests a data format conversion to a type that is not the native file type and also is not one of the internal types supported by the ImageCache (specifically, float and UINT8); (c) if the ImageBuf already has local pixel memory allocated, or "wraps" an application buffer.
Note that read() is not strictly necessary. If you are happy with the filename, subimage and MIP level specified by the ImageBuf constructor (or the last call to reset()), and you want the storage to be backed by the ImageCache (including storing the pixels in whatever data format that implies), then the file contents will be automatically read the first time you make any other ImageBuf API call that requires the spec or pixel values. The only reason to call read() yourself is if you are changing the filename, subimage, or MIP level, or if you want to use force = true or a specific convert value to force data format conversion.
| subimage/miplevel | The subimage and MIP level to read. |
| force | If true, will force an immediate full read into ImageBuf-owned local pixel memory (yielding a LOCALPIXELS storage buffer). Otherwise, it is up to the implementation whether to immediately read or have the image backed by an ImageCache (storage IMAGECACHE.) |
| convert | If set to a specific type (notUNKNOWN), the ImageBuf memory will be allocated for that type specifically and converted upon read. |
| progress_callback/progress_callback_data | If progress_callback is non-NULL, the underlying read, if expensive, may make several calls to progress_callback(progress_callback_data, portion_done) which allows you to implement some sort of progress meter. Note that if the ImageBuf is backed by an ImageCache, the progress callback will never be called, since no actual file I/O will occur at this time (ImageCache will load tiles or scanlines on demand, as individual pixel values are needed). |
true upon success, or false if the read failed (in which case, you should be able to retrieve an error message via geterror()). | int ImageBuf::orientation | ( | ) | const |
Return the current "Orientation" metadata for the image, per the table in sec-metadata-orientation_
| int ImageBuf::oriented_full_height | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| int ImageBuf::oriented_full_width | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| int ImageBuf::oriented_full_x | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| int ImageBuf::oriented_full_y | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| int ImageBuf::oriented_height | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| int ImageBuf::oriented_width | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| int ImageBuf::oriented_x | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| int ImageBuf::oriented_y | ( | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| stride_t ImageBuf::pixel_stride | ( | ) | const |
Pixel-to-pixel stride within the localpixels memory.
Return the address where pixel (x,y,z), channel ch, is stored in the image buffer. Use with extreme caution! Will return nullptr if the pixel values aren't local in RAM.
Returns true if the ImageBuf is initialized, false if not yet initialized.
Return the index of pixel (x,y,z). If check_range is true, return -1 for an invalid coordinate that is not within the data window.
| bool ImageBuf::pixels_valid | ( | void | ) | const |
Returns true if the ImageBuf is initialized, false if not yet initialized.
| TypeDesc ImageBuf::pixeltype | ( | ) | const |
The data type of the pixels stored in the buffer (equivalent to spec().format).
| bool ImageBuf::read | ( | int | subimage = 0, |
| int | miplevel = 0, |
||
| bool | force = false, |
||
| TypeDesc | convert = TypeDesc::UNKNOWN, |
||
| ProgressCallback | progress_callback = nullptr, |
||
| void * | progress_callback_data = nullptr |
||
| ) |
Read the particular subimage and MIP level of the image. Generally, this will skip the expensive read if the file has already been read into the ImageBuf (at the specified subimage and MIP level). It will clear and re-allocate memory if the previously allocated space was not appropriate for the size or data type of the image being read.
In general, read() will try not to do any I/O at the time of the read() call, but rather to have the ImageBuf "backed" by an ImageCache, which will do the file I/O on demand, as pixel values are needed, and in that case the ImageBuf doesn't actually allocate memory for the pixels (the data lives in the ImageCache). However, there are several conditions for which the ImageCache will be bypassed, the ImageBuf will allocate "local" memory, and the disk file will be read directly into allocated buffer at the time of the read() call: (a) if the force parameter is true; (b) if the convert parameter requests a data format conversion to a type that is not the native file type and also is not one of the internal types supported by the ImageCache (specifically, float and UINT8); (c) if the ImageBuf already has local pixel memory allocated, or "wraps" an application buffer.
Note that read() is not strictly necessary. If you are happy with the filename, subimage and MIP level specified by the ImageBuf constructor (or the last call to reset()), and you want the storage to be backed by the ImageCache (including storing the pixels in whatever data format that implies), then the file contents will be automatically read the first time you make any other ImageBuf API call that requires the spec or pixel values. The only reason to call read() yourself is if you are changing the filename, subimage, or MIP level, or if you want to use force = true or a specific convert value to force data format conversion.
| subimage/miplevel | The subimage and MIP level to read. |
| force | If true, will force an immediate full read into ImageBuf-owned local pixel memory (yielding a LOCALPIXELS storage buffer). Otherwise, it is up to the implementation whether to immediately read or have the image backed by an ImageCache (storage IMAGECACHE.) |
| convert | If set to a specific type (notUNKNOWN), the ImageBuf memory will be allocated for that type specifically and converted upon read. |
| progress_callback/progress_callback_data | If progress_callback is non-NULL, the underlying read, if expensive, may make several calls to progress_callback(progress_callback_data, portion_done) which allows you to implement some sort of progress meter. Note that if the ImageBuf is backed by an ImageCache, the progress callback will never be called, since no actual file I/O will occur at this time (ImageCache will load tiles or scanlines on demand, as individual pixel values are needed). |
true upon success, or false if the read failed (in which case, you should be able to retrieve an error message via geterror()). | bool ImageBuf::read | ( | int | subimage, |
| int | miplevel, | ||
| int | chbegin, | ||
| int | chend, | ||
| bool | force, | ||
| TypeDesc | convert, | ||
| ProgressCallback | progress_callback = nullptr, |
||
| void * | progress_callback_data = nullptr |
||
| ) |
Read the file, if possible only allocating and reading a subset of channels, [chbegin..chend-1]. This can be a performance and memory improvement for some image file formats, if you know that any use of the ImageBuf will only access a subset of channels from a many-channel file.
Additional parameters:
| chbegin/chend | The subset (a range with "exclusive end") of channels to read, if the implementation is able to read only a subset of channels and have a performance advantage by doing so. If chbegin is 0 and chend is either negative or greater than the number of channels in the file, all channels will be read. Please note that it is "advisory" and not guaranteed to be honored by the underlying implementation. |
|
inline |
Destroy any previous contents of the ImageBuf and re-initialize it to resemble a freshly constructed ImageBuf using the default constructor (holding no image, with storage IBStorage::UNINITIALIZED).
Definition at line 276 of file imagebuf.h.
| void ImageBuf::reset | ( | string_view | name, |
| ImageCache * | imagecache | ||
| ) |
| void ImageBuf::reset | ( | string_view | name, |
| int | subimage = 0, |
||
| int | miplevel = 0, |
||
| ImageCache * | imagecache = nullptr, |
||
| const ImageSpec * | config = nullptr, |
||
| Filesystem::IOProxy * | ioproxy = nullptr |
||
| ) |
Destroy any previous contents of the ImageBuf and re-initialize it as if newly constructed with the same arguments, as a read-only representation of an existing image file.
| void ImageBuf::reset | ( | const ImageSpec & | spec, |
| InitializePixels | zero = InitializePixels::Yes |
||
| ) |
Destroy any previous contents of the ImageBuf and re-initialize it as if newly constructed with the same arguments, as a read/write image with locally allocated storage that can hold an image as described by spec. The optional zero parameter controls whether the pixel values are filled with black/empty, or are left uninitialized after being allocated.
Note that if the ImageSpec does not contain enough information to specify how much memory to allocate (width, height, channels, and data format), the ImageBuf will remain uninitialized (regardless of how zero is set).
| void ImageBuf::reset | ( | string_view | name, |
| const ImageSpec & | spec, | ||
| InitializePixels | zero = InitializePixels::Yes |
||
| ) |
| void ImageBuf::reset | ( | const ImageSpec & | spec, |
| void * | buffer, | ||
| stride_t | xstride = AutoStride, |
||
| stride_t | ystride = AutoStride, |
||
| stride_t | zstride = AutoStride |
||
| ) |
Destroy any previous contents of the ImageBuf and re-initialize it as if newly constructed with the same arguments, to "wrap" existing pixel memory owned by the calling application.
|
protected |
| stride_t ImageBuf::scanline_stride | ( | ) | const |
Scanline-to-scanline stride within the localpixels memory.
Set the number of deep samples for pixel (x,y,z). If data has already been allocated, this is equivalent to inserting or erasing samples.
Set the value of sample s of channel c of pixel (x,y,z) to a float value (it is expected that channel c is a floating point type).
Set the value of sample s of channel c of pixel (x,y,z) to a uint32_t value (it is expected that channel c is an integer type).
Set the "full" (a.k.a. display) window to Alters the metadata of the spec in the ImageBuf to reset the "full" image size (a.k.a. "display window") to
[xbegin,xend) x [ybegin,yend) x [zbegin,zend)`
This does not affect the size of the pixel data window.
Alters the metadata of the spec in the ImageBuf to reset the "origin" of the pixel data window to be the specified coordinates. This does not affect the size of the pixel data window, only its position.
| bool ImageBuf::set_pixels | ( | ROI | roi, |
| TypeDesc | format, | ||
| const void * | data, | ||
| stride_t | xstride = AutoStride, |
||
| stride_t | ystride = AutoStride, |
||
| stride_t | zstride = AutoStride |
||
| ) |
Copy the data into the given ROI of the ImageBuf. The data points to values specified by format, with layout detailed by the stride values (in bytes, with AutoStride indicating "contiguous" layout). It is up to the caller to ensure that data points to an area of memory big enough to account for the ROI. If roi is set to ROI::all(), the data buffer is assumed to have the same resolution as the ImageBuf itself. Return true if the operation could be completed, otherwise return false.
Reset the thumbnail image associated with this ImageBuf to thumb. This call will invalidate any references previously returned by thumbnail().
Set the per-channel pixel data format that will be used for subsequent write() calls that do not themselves request a specific data type request.
| format | The type of each channel (in order). Any channel's format specified as TypeUnknown will default to be whatever type is described in the ImageSpec of the buffer. |
| void ImageBuf::set_write_ioproxy | ( | Filesystem::IOProxy * | ioproxy | ) |
Override the tile sizing for subsequent calls to the write() method (the variety that does not take an open ImageOutput*). Setting all three dimensions to 0 indicates that the output should be a scanline-oriented file.
This lets you write a tiled file from an ImageBuf that may have been read originally from a scanline file, or change the dimensions of a tiled file, or to force the file written to be scanline even if it was originally read from a tiled file.
In all cases, if the file format ultimately written does not support tiling, or the tile dimensions requested, a suitable supported tiling choice will be made automatically.
Set the pixel with coordinates (x,y,0) to have the values in span pixel[]. The number of channels copied is the minimum of the span length and the actual number of channels in the image.
Definition at line 753 of file imagebuf.h.
Set the pixel with coordinates (x,y,z) to have the values in span pixel[]. The number of channels copied is the minimum of the span length and the actual number of channels in the image.
Definition at line 761 of file imagebuf.h.
Set the i-th pixel value of the image (out of width*height*depth), from floating-point values in span pixel[]. The number of channels copied is the minimum of the span length and the actual number of channels in the image.
Definition at line 770 of file imagebuf.h.
Set the pixel with coordinates (x,y,0) to have the values in pixel[0..n-1]. The number of channels copied, n, is the minimum of maxchannels and the actual number of channels in the image.
Definition at line 778 of file imagebuf.h.
Set the pixel with coordinates (x,y,z) to have the values in pixel[0..n-1]. The number of channels copied, n, is the minimum of maxchannels and the actual number of channels in the image.
Set the i-th pixel value of the image (out of width*height*depth), from floating-point values in pixel[]. Set at most maxchannels (will be clamped to the actual number of channels).
Return a read-only (const) reference to the image spec that describes the buffer.
| ImageSpec& ImageBuf::specmod | ( | ) |
Return a writable reference to the ImageSpec that describes the buffer. It's ok to modify most of the metadata, but if you modify the spec's format, width, height, or depth fields, you get the pain you deserve, as the ImageBuf will no longer have correct knowledge of its pixel memory layout. USE WITH EXTREME CAUTION.
| IBStorage ImageBuf::storage | ( | ) | const |
Which type of storage is being used for the pixels? Returns an enumerated type describing the type of storage currently employed by the ImageBuf: UNINITIALIZED (no storage), LOCALBUFFER (the ImageBuf has allocated and owns the pixel memory), APPBUFFER (the ImageBuf "wraps" memory owned by the calling application), or IMAGECACHE (the image is backed by an ImageCache).
| int ImageBuf::subimage | ( | ) | const |
Swap the entire contents with another ImageBuf.
Definition at line 657 of file imagebuf.h.
Set the threading policy for this ImageBuf, controlling the maximum amount of parallelizing thread "fan-out" that might occur during expensive operations. The default of 0 means that the global attribute("threads") value should be used (which itself defaults to using as many threads as cores).
The main reason to change this value is to set it to 1 to indicate that the calling thread should do all the work rather than spawning new threads. That is probably the desired behavior in situations where the calling application has already spawned multiple worker threads.
|
static |
Return the WrapMode corresponding to the name ("default", "black", "clamp", "periodic", "mirror"). For an unknown name, this will return WrapDefault.
| bool ImageBuf::write | ( | string_view | filename, |
| TypeDesc | dtype = TypeUnknown, |
||
| string_view | fileformat = string_view(), |
||
| ProgressCallback | progress_callback = nullptr, |
||
| void * | progress_callback_data = nullptr |
||
| ) | const |
Write the image to the named file, converted to the specified pixel data type dtype (TypeUnknown signifies to use the data type of the buffer), and file format (an empty fileformat means to infer the type from the filename extension).
By default, it will always try to write a scanline-oriented file, unless the set_write_tiles() method has been used to override this.
| filename | The filename to write to. |
| dtype | Optional override of the pixel data format to use in the file being written. The default (UNKNOWN) means to try writing the same data format that as pixels are stored within the ImageBuf memory (or whatever type was specified by a prior call to set_write_format()). In either case, if the file format does not support that data type, another will be automatically chosen that is supported by the file type and loses as little precision as possible. |
| fileformat | Optional override of the file format to write. The default (empty string) means to infer the file format from the extension of the filename (for example, "foo.tif" will write a TIFF file). |
| progress_callback/progress_callback_data | If progress_callback is non-NULL, the underlying write, if expensive, may make several calls to progress_callback(progress_callback_data, portion_done) which allows you to implement some sort of progress meter. |
true upon success, or false if the write failed (in which case, you should be able to retrieve an error message via geterror()). | bool ImageBuf::write | ( | ImageOutput * | out, |
| ProgressCallback | progress_callback = nullptr, |
||
| void * | progress_callback_data = nullptr |
||
| ) | const |
Write the pixels of the ImageBuf to an open ImageOutput. The ImageOutput must have already been opened with a spec that indicates a resolution identical to that of this ImageBuf (but it may have specified a different pixel data type, in which case data conversions will happen automatically). This method does NOT close the file when it's done (and so may be called in a loop to write a multi-image file).
Note that since this uses an already-opened ImageOutput, which is too late to change how it was opened, it does not honor any prior calls to set_write_format or set_write_tiles.
The main application of this method is to allow an ImageBuf (which by design may hold only a single image) to be used for the output of one image of a multi-subimage and/or MIP-mapped image file.
| out | A pointer to an already-opened ImageOutput to which the pixels of the ImageBuf will be written. |
| progress_callback/progress_callback_data | If progress_callback is non-NULL, the underlying write, if expensive, may make several calls to progress_callback(progress_callback_data, portion_done) which allows you to implement some sort of progress meter. |
true if all went ok, false if there were errors writing. | int ImageBuf::xbegin | ( | ) | const |
Return the beginning (minimum) x coordinate of the defined image.
| int ImageBuf::xend | ( | ) | const |
Return the end (one past maximum) x coordinate of the defined image.
| int ImageBuf::xmax | ( | ) | const |
Return the maximum x coordinate of the defined image.
| int ImageBuf::xmin | ( | ) | const |
Return the minimum x coordinate of the defined image.
| int ImageBuf::ybegin | ( | ) | const |
Return the beginning (minimum) y coordinate of the defined image.
| int ImageBuf::yend | ( | ) | const |
Return the end (one past maximum) y coordinate of the defined image.
| int ImageBuf::ymax | ( | ) | const |
Return the maximum y coordinate of the defined image.
| int ImageBuf::ymin | ( | ) | const |
Return the minimum y coordinate of the defined image.
| stride_t ImageBuf::z_stride | ( | ) | const |
Z plane stride within the localpixels memory.
| int ImageBuf::zbegin | ( | ) | const |
Return the beginning (minimum) z coordinate of the defined image.
| int ImageBuf::zend | ( | ) | const |
Return the end (one past maximum) z coordinate of the defined image.
| int ImageBuf::zmax | ( | ) | const |
Return the maximum z coordinate of the defined image.
| int ImageBuf::zmin | ( | ) | const |
Return the minimum z coordinate of the defined image.
|
friend |
Definition at line 1186 of file imagebuf.h.
| string_view ImageBuf::fileformat |
Read the particular subimage and MIP level of the image. Generally, this will skip the expensive read if the file has already been read into the ImageBuf (at the specified subimage and MIP level). It will clear and re-allocate memory if the previously allocated space was not appropriate for the size or data type of the image being read.
In general, read() will try not to do any I/O at the time of the read() call, but rather to have the ImageBuf "backed" by an ImageCache, which will do the file I/O on demand, as pixel values are needed, and in that case the ImageBuf doesn't actually allocate memory for the pixels (the data lives in the ImageCache). However, there are several conditions for which the ImageCache will be bypassed, the ImageBuf will allocate "local" memory, and the disk file will be read directly into allocated buffer at the time of the read() call: (a) if the force parameter is true; (b) if the convert parameter requests a data format conversion to a type that is not the native file type and also is not one of the internal types supported by the ImageCache (specifically, float and UINT8); (c) if the ImageBuf already has local pixel memory allocated, or "wraps" an application buffer.
Note that read() is not strictly necessary. If you are happy with the filename, subimage and MIP level specified by the ImageBuf constructor (or the last call to reset()), and you want the storage to be backed by the ImageCache (including storing the pixels in whatever data format that implies), then the file contents will be automatically read the first time you make any other ImageBuf API call that requires the spec or pixel values. The only reason to call read() yourself is if you are changing the filename, subimage, or MIP level, or if you want to use force = true or a specific convert value to force data format conversion.
| subimage/miplevel | The subimage and MIP level to read. |
| force | If true, will force an immediate full read into ImageBuf-owned local pixel memory (yielding a LOCALPIXELS storage buffer). Otherwise, it is up to the implementation whether to immediately read or have the image backed by an ImageCache (storage IMAGECACHE.) |
| convert | If set to a specific type (notUNKNOWN), the ImageBuf memory will be allocated for that type specifically and converted upon read. |
| progress_callback/progress_callback_data | If progress_callback is non-NULL, the underlying read, if expensive, may make several calls to progress_callback(progress_callback_data, portion_done) which allows you to implement some sort of progress meter. Note that if the ImageBuf is backed by an ImageCache, the progress callback will never be called, since no actual file I/O will occur at this time (ImageCache will load tiles or scanlines on demand, as individual pixel values are needed). |
true upon success, or false if the read failed (in which case, you should be able to retrieve an error message via geterror()). Definition at line 519 of file imagebuf.h.
|
protected |
Definition at line 1783 of file imagebuf.h.
| string_view ProgressCallback ImageBuf::progress_callback = nullptr |
Read the particular subimage and MIP level of the image. Generally, this will skip the expensive read if the file has already been read into the ImageBuf (at the specified subimage and MIP level). It will clear and re-allocate memory if the previously allocated space was not appropriate for the size or data type of the image being read.
In general, read() will try not to do any I/O at the time of the read() call, but rather to have the ImageBuf "backed" by an ImageCache, which will do the file I/O on demand, as pixel values are needed, and in that case the ImageBuf doesn't actually allocate memory for the pixels (the data lives in the ImageCache). However, there are several conditions for which the ImageCache will be bypassed, the ImageBuf will allocate "local" memory, and the disk file will be read directly into allocated buffer at the time of the read() call: (a) if the force parameter is true; (b) if the convert parameter requests a data format conversion to a type that is not the native file type and also is not one of the internal types supported by the ImageCache (specifically, float and UINT8); (c) if the ImageBuf already has local pixel memory allocated, or "wraps" an application buffer.
Note that read() is not strictly necessary. If you are happy with the filename, subimage and MIP level specified by the ImageBuf constructor (or the last call to reset()), and you want the storage to be backed by the ImageCache (including storing the pixels in whatever data format that implies), then the file contents will be automatically read the first time you make any other ImageBuf API call that requires the spec or pixel values. The only reason to call read() yourself is if you are changing the filename, subimage, or MIP level, or if you want to use force = true or a specific convert value to force data format conversion.
| subimage/miplevel | The subimage and MIP level to read. |
| force | If true, will force an immediate full read into ImageBuf-owned local pixel memory (yielding a LOCALPIXELS storage buffer). Otherwise, it is up to the implementation whether to immediately read or have the image backed by an ImageCache (storage IMAGECACHE.) |
| convert | If set to a specific type (notUNKNOWN), the ImageBuf memory will be allocated for that type specifically and converted upon read. |
| progress_callback/progress_callback_data | If progress_callback is non-NULL, the underlying read, if expensive, may make several calls to progress_callback(progress_callback_data, portion_done) which allows you to implement some sort of progress meter. Note that if the ImageBuf is backed by an ImageCache, the progress callback will never be called, since no actual file I/O will occur at this time (ImageCache will load tiles or scanlines on demand, as individual pixel values are needed). |
true upon success, or false if the read failed (in which case, you should be able to retrieve an error message via geterror()). Definition at line 520 of file imagebuf.h.
| string_view ProgressCallback void* ImageBuf::progress_callback_data |
Read the particular subimage and MIP level of the image. Generally, this will skip the expensive read if the file has already been read into the ImageBuf (at the specified subimage and MIP level). It will clear and re-allocate memory if the previously allocated space was not appropriate for the size or data type of the image being read.
In general, read() will try not to do any I/O at the time of the read() call, but rather to have the ImageBuf "backed" by an ImageCache, which will do the file I/O on demand, as pixel values are needed, and in that case the ImageBuf doesn't actually allocate memory for the pixels (the data lives in the ImageCache). However, there are several conditions for which the ImageCache will be bypassed, the ImageBuf will allocate "local" memory, and the disk file will be read directly into allocated buffer at the time of the read() call: (a) if the force parameter is true; (b) if the convert parameter requests a data format conversion to a type that is not the native file type and also is not one of the internal types supported by the ImageCache (specifically, float and UINT8); (c) if the ImageBuf already has local pixel memory allocated, or "wraps" an application buffer.
Note that read() is not strictly necessary. If you are happy with the filename, subimage and MIP level specified by the ImageBuf constructor (or the last call to reset()), and you want the storage to be backed by the ImageCache (including storing the pixels in whatever data format that implies), then the file contents will be automatically read the first time you make any other ImageBuf API call that requires the spec or pixel values. The only reason to call read() yourself is if you are changing the filename, subimage, or MIP level, or if you want to use force = true or a specific convert value to force data format conversion.
| subimage/miplevel | The subimage and MIP level to read. |
| force | If true, will force an immediate full read into ImageBuf-owned local pixel memory (yielding a LOCALPIXELS storage buffer). Otherwise, it is up to the implementation whether to immediately read or have the image backed by an ImageCache (storage IMAGECACHE.) |
| convert | If set to a specific type (notUNKNOWN), the ImageBuf memory will be allocated for that type specifically and converted upon read. |
| progress_callback/progress_callback_data | If progress_callback is non-NULL, the underlying read, if expensive, may make several calls to progress_callback(progress_callback_data, portion_done) which allows you to implement some sort of progress meter. Note that if the ImageBuf is backed by an ImageCache, the progress callback will never be called, since no actual file I/O will occur at this time (ImageCache will load tiles or scanlines on demand, as individual pixel values are needed). |
true upon success, or false if the read failed (in which case, you should be able to retrieve an error message via geterror()). Definition at line 521 of file imagebuf.h.
1.8.6