|
HDK
|
#include <cmath>#include <limits>#include <string>#include <vector>#include <OpenImageIO/span.h>#include <OpenImageIO/export.h>#include <OpenImageIO/oiioversion.h>#include <OpenImageIO/paramlist.h>#include <OpenImageIO/platform.h>#include <OpenImageIO/strutil.h>#include <OpenImageIO/thread.h>#include <OpenImageIO/typedesc.h>
Include dependency graph for imageio.h: This graph shows which files directly or indirectly include this file:Go to the source code of this file.
Classes | |
| struct | ROI |
| class | ImageSpec |
| class | ImageInput |
| class | ImageOutput |
Namespaces | |
| Filesystem | |
| Platform-independent utilities for manipulating file names, files, directories, and other file system miscellany. | |
Macros | |
| #define | OPENIMAGEIO_IMAGEIO_H |
Typedefs | |
| using | stride_t = int64_t |
| using | imagesize_t = uint64_t |
| typedef bool(* | ProgressCallback )(void *opaque_data, float portion_done) |
| typedef ParamValue | ImageIOParameter |
| typedef ParamValueList | ImageIOParameterList |
| typedef bool(* | wrap_impl )(int &coord, int origin, int width) |
Functions | |
| constexpr ROI | roi_union (const ROI &A, const ROI &B) noexcept |
| Union of two regions, the smallest region containing both. More... | |
| constexpr ROI | roi_intersection (const ROI &A, const ROI &B) noexcept |
| Intersection of two regions. More... | |
| OIIO_API int | openimageio_version () |
| OIIO_API bool | has_error () |
| Is there a pending global error message waiting to be retrieved? More... | |
| OIIO_API std::string | geterror (bool clear=true) |
| OIIO_API bool | attribute (string_view name, TypeDesc type, const void *val) |
| bool | attribute (string_view name, int val) |
| Shortcut attribute() for setting a single integer. More... | |
| bool | attribute (string_view name, float val) |
| Shortcut attribute() for setting a single float. More... | |
| bool | attribute (string_view name, string_view val) |
| Shortcut attribute() for setting a single string. More... | |
| OIIO_API bool | getattribute (string_view name, TypeDesc type, void *val) |
| bool | getattribute (string_view name, int &val) |
| bool | getattribute (string_view name, float &val) |
| bool | getattribute (string_view name, std::string &val) |
| bool | getattribute (string_view name, char **val) |
Shortcut getattribute() for retrieving a single string as a char*. More... | |
| int | get_int_attribute (string_view name, int defaultval=0) |
| float | get_float_attribute (string_view name, float defaultval=0) |
| string_view | get_string_attribute (string_view name, string_view defaultval=string_view()) |
| 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) |
| OIIO_API bool | is_imageio_format_name (string_view name) |
Is name one of the known format names? More... | |
| std::map< std::string, std::vector< std::string > > | get_extension_map () |
| OIIO_API bool | convert_pixel_values (TypeDesc src_type, const void *src, TypeDesc dst_type, void *dst, int n=1) |
| bool | convert_types (TypeDesc src_type, const void *src, TypeDesc dst_type, void *dst, int n=1) |
| DEPRECATED(2.1): old name. More... | |
| 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) |
| 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, int, int=-1) |
| DEPRECATED(2.0) – the alpha_channel, z_channel were never used. More... | |
| 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) |
| 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, int, int nthreads=0) |
| DEPRECATED(2.0) – the alpha_channel, z_channel were never used. More... | |
| 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) |
| 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 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) |
| OIIO_API bool | wrap_black (int &coord, int origin, int width) |
| OIIO_API bool | wrap_clamp (int &coord, int origin, int width) |
| OIIO_API bool | wrap_periodic (int &coord, int origin, int width) |
| OIIO_API bool | wrap_periodic_pow2 (int &coord, int origin, int width) |
| OIIO_API bool | wrap_mirror (int &coord, int origin, int width) |
| OIIO_API void | debug (string_view str) |
| template<typename T1 , typename... Args> | |
| void | debugfmt (const char *fmt, const T1 &v1, const Args &...args) |
debug output with std::format conventions. More... | |
| template<typename T1 , typename... Args> | |
| void | fmtdebug (const char *fmt, const T1 &v1, const Args &...args) |
| template<typename T1 , typename... Args> | |
| void | debugf (const char *fmt, const T1 &v1, const Args &...args) |
| debug output with printf conventions. More... | |
| template<typename T1 , typename... Args> | |
| OIIO_FORMAT_DEPRECATED void | debug (const char *fmt, const T1 &v1, const Args &...args) |
| OIIO_API void | _ImageIO_force_link () |
Variables | |
| const stride_t | AutoStride = std::numeric_limits<stride_t>::min() |
Provides a simple API that abstracts the reading and writing of images. Subclasses, which may be found in DSO/DLL's, implement particular formats.
Definition in file imageio.h.
| typedef ParamValue ImageIOParameter |
| typedef ParamValueList ImageIOParameterList |
| using imagesize_t = uint64_t |
Pointer to a function called periodically by read_image and write_image. This can be used to implement progress feedback, etc. It takes an opaque data pointer (passed to read_image/write_image) and a float giving the portion of work done so far. It returns a bool, which if 'true' will STOP the read or write.
| using stride_t = int64_t |
| 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 |
||
| ) |
Add random [-ditheramplitude,ditheramplitude] dither to the color channels of the image. Dither will not be added to the alpha or z channel. The image origin and dither seed values allow a reproducible (or variable) dither pattern. If the strides are set to AutoStride, they will be assumed to be contiguous floats in data of the given dimensions.
| OIIO_API bool attribute | ( | string_view | name, |
| TypeDesc | type, | ||
| const void * | val | ||
| ) |
OIIO::attribute() sets a global attribute (i.e., a property or option) of OpenImageIO. The name designates the name of the attribute, type describes the type of data, and val is a pointer to memory containing the new value for the attribute.
If the name is known, valid attribute that matches the type specified, the attribute will be set to the new value and attribute() will return true. If name is not recognized, or if the types do not match (e.g., type is TypeFloat but the named attribute is a string), the attribute will not be modified, and attribute() will return false.
The following are the recognized attributes:
string options
This catch-all is simply a comma-separated list of name=value settings of named options, which will be parsed and individually set. For example,
OIIO::attribute ("options", "threads=4,log_times=1");
Note that if an option takes a string value that must itself contain a comma, it is permissible to enclose the value in either 'single' or "double" quotes.
int threads
How many threads to use for operations that can be sped up by being multithreaded. (Examples: simultaneous format conversions of multiple scanlines read together, or many ImageBufAlgo operations.) The default is 0, meaning to use the full available hardware concurrency detected.
Situations where the main application logic is essentially single threaded (i.e., one top-level call into OIIO at a time) should leave this at the default value, or some reasonable number of cores, thus allowing lots of threads to fill the cores when OIIO has big tasks to complete. But situations where you have many threads at the application level, each of which is expected to be making separate OIIO calls simultaneously, should set this to 1, thus having each calling thread do its own work inside of OIIO rather than spawning new threads with a high overall "fan out."
int exr_threads
Sets the internal OpenEXR thread pool size. The default is to use as many threads as the amount of hardware concurrency detected. Note that this is separate from the OIIO "threads" attribute.
string font_searchpath
Colon-separated (or semicolon-separated) list of directories to search if fonts are needed. (Such as for ImageBufAlgo::render_text().)
string plugin_searchpath
Colon-separated (or semicolon-separated) list of directories to search for dynamically-loaded format plugins.
int try_all_readers
When nonzero (the default), a call to ImageInput::create() or ImageInput::open() that does not succeed in opening the file with the format reader implied by the file extension will try all available format readers to see if one of them can open the file. If this is zero, the only reader that will be tried is the one implied by the file extension.
int read_chunk
When performing a read_image(), this is the number of scanlines it will attempt to read at a time (some formats are more efficient when reading and decoding multiple scanlines). The default is 256. The special value of 0 indicates that it should try to read the whole image if possible.
float[] missingcolor, string missingcolor
This attribute may either be an array of float values, or a string containing a comma-separated list of the values. Setting this option globally is equivalent to always passing an ImageInput open-with-configuration hint "oiio:missingcolor" with the value.
When set, it gives some ImageInput readers the option of ignoring any missing tiles or scanlines in the file, and instead of treating the read failure of an individual tile as a full error, will interpret is as an intentionally missing tile and proceed by simply filling in the missing pixels with the color specified. If the first element is negative, it will use the absolute value, but draw alternating diagonal stripes of the color. For example,
float missing[4] = { -1.0, 0.0, 0.0, 0.0 }; // striped red
OIIO::attribute ("missingcolor", TypeDesc("float[4]"), &missing);
Note that only some file formats support files with missing tiles or scanlines, and this is only taken as a hint. Please see chap-bundledplugins_ for details on which formats accept a "missingcolor" configuration hint.
int debug
When nonzero, various debug messages may be printed. The default is 0 for release builds, 1 for DEBUG builds (values > 1 are for OIIO developers to print even more debugging information), This attribute but also may be overridden by the OPENIMAGEIO_DEBUG environment variable.
int tiff:half
When nonzero, allows TIFF to write half pixel data. N.B. Most apps may not read these correctly, but OIIO will. That's why the default is not to support it.
int openexr:core
When nonzero, use the new "OpenEXR core C library" when available, for OpenEXR >= 3.1. This is experimental, and currently defaults to 0.
int limits:channels (1024)
When nonzero, the maximum number of color channels in an image. Image files whose headers indicate they have more channels might be assumed to be corrupted or malicious files. In situations when more channels are expected to be encountered, the application should raise this limit. The default is 1024 channels.
int limits:imagesize_MB (32768)
When nonzero, the maximum size in MB of the uncompressed pixel data of a single 2D image. Images whose headers indicate that they are larger than this might be assumed to be corrupted or malicious files. The default is 32768 (32 GB of uncompressed pixel data – equivalent to 64k x 64k x 4 channel x half). In situations when images larger than this are expected to be encountered, you should raise this limit.
int log_times
When the "log_times" attribute is nonzero, ImageBufAlgo functions are instrumented to record the number of times they were called and the total amount of time spent executing them. It can be overridden by environment variable OPENIMAGEIO_LOG_TIMES. The totals will be recorded and can be retrieved as a string by using OIIO::getattribute("timing_report", ...). Additionally, if the value is 2 or more, the timing report will be printed to stdout upon application exit (not advised in contexts where it isn't ok to print to the terminal via stdout, such as GUI apps or libraries).
When enabled, there is a slight runtime performance cost due to checking the time at the start and end of each of those function calls, and the locking and recording of the data structure that holds the log information. When the log_times attribute is disabled, there is no additional performance cost.
|
inline |
Shortcut attribute() for setting a single integer.
|
inline |
Shortcut attribute() for setting a single float.
|
inline |
Shortcut attribute() for setting a single string.
| 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 | ||
| ) |
Helper routine for data conversion: Convert an image of nchannels x width x height x depth from src to dst. The src and dst may have different data formats and layouts. Clever use of this function can not only exchange data among different formats (e.g., half to 8-bit unsigned), but also can copy selective channels, copy subimages, etc. If you're lazy, it's ok to pass AutoStride for any of the stride values, and they will be auto-computed assuming contiguous data. Return true if ok, false if it didn't know how to do the conversion.
| OIIO_API bool convert_pixel_values | ( | TypeDesc | src_type, |
| const void * | src, | ||
| TypeDesc | dst_type, | ||
| void * | dst, | ||
| int | n = 1 |
||
| ) |
Helper function: convert contiguous data between two arbitrary pixel data types (specified by TypeDesc's). Return true if ok, false if it didn't know how to do the conversion. If dst_type is UNKNOWN, it will be assumed to be the same as src_type.
The conversion is of normalized (pixel-like) values – for example 'UINT8' 255 will convert to float 1.0 and vice versa, not float 255.0. If you want a straight C-like data cast convertion (e.g., uint8 255 -> float 255.0), then you should prefer the un-normalized convert_type() utility function found in typedesc.h.
| 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 | ||
| ) |
Helper routine for data conversion: Copy an image of nchannels x width x height x depth from src to dst. The src and dst may have different data layouts, but must have the same data type. Clever use of this function can change layouts or strides, copy selective channels, copy subimages, etc. If you're lazy, it's ok to pass AutoStride for any of the stride values, and they will be auto-computed assuming contiguous data. Return true if ok, false if it didn't know how to do the conversion.
| OIIO_API void debug | ( | string_view | str | ) |
debug(format, ...) prints debugging message when attribute "debug" is nonzero, which it is by default for DEBUG compiles or when the environment variable OPENIMAGEIO_DEBUG is set. This is preferred to raw output to stderr for debugging statements.
| OIIO_FORMAT_DEPRECATED void debug | ( | const char * | fmt, |
| const T1 & | v1, | ||
| const Args &... | args | ||
| ) |
| 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 | ||
| ) |
Register the input and output 'create' routines and list of file extensions for a particular format.
|
inline |
|
inline |
Shortcut getattribute() for retrieving a single float, with a supplied default value that will be returned if the attribute is not found or could not legally be converted to a float.
|
inline |
Shortcut getattribute() for retrieving a single integer, with a supplied default value that will be returned if the attribute is not found or could not legally be converted to an int.
|
inline |
Shortcut getattribute() for retrieving a single string, with a supplied default value that will be returned if the attribute is not found.
| OIIO_API bool getattribute | ( | string_view | name, |
| TypeDesc | type, | ||
| void * | val | ||
| ) |
Get the named global attribute of OpenImageIO, store it in *val. Return true if found and it was compatible with the type specified, otherwise return false and do not modify the contents of *val. It is up to the caller to ensure that val points to the right kind and size of storage for the given type.
In addition to being able to retrieve all the attributes that are documented as settable by the OIIO::attribute() call, getattribute() can also retrieve the following read-only attributes:
string format_liststring input_format_liststring output_format_list
A comma-separated list of all the names of, respectively, all supported image formats, all formats accepted as inputs, and all formats accepted as outputs.
string extension_list
For each format, the format name, followed by a colon, followed by a comma-separated list of all extensions that are presumed to be used for that format. Semicolons separate the lists for formats. For example,
"tiff:tif;jpeg:jpg,jpeg;openexr:exr"
string library_list
For each format that uses a dependent library, the format name, followed by a colon, followed by the name and version of the dependency. Semicolons separate the lists for formats. For example,
"tiff:LIBTIFF 4.0.4;gif:gif_lib 4.2.3;openexr:OpenEXR 2.2.0"
string hw:simdstring oiio:simd (read-only)
A comma-separated list of hardware CPU features for SIMD (and some other things). The "oiio:simd" attribute is similarly a list of which features this build of OIIO was compiled to support.
This was added in OpenImageIO 1.8.
float resident_memory_used_MB
This read-only attribute can be used for debugging purposes to report the approximate process memory used (resident) by the application, in MB.
string timing_report
Retrieving this attribute returns the timing report generated by the log_timing attribute (if it was enabled). The report is sorted alphabetically and for each named instrumentation region, prints the number of times it executed, the total runtime, and the average per call, like this:
IBA::computePixelStats 2 2.69ms (avg 1.34ms) IBA::make_texture 1 74.05ms (avg 74.05ms) IBA::mul 8 2.42ms (avg 0.30ms) IBA::over 10 23.82ms (avg 2.38ms) IBA::resize 20 0.24s (avg 12.18ms) IBA::zero 8 0.66ms (avg 0.08ms)
|
inline |
Shortcut getattribute() for retrieving a single integer. The value is placed in val, and the function returns true if the attribute was found and was legally convertible to an int.
|
inline |
Shortcut getattribute() for retrieving a single float. The value is placed in val, and the function returns true if the attribute was found and was legally convertible to a float.
|
inline |
Shortcut getattribute() for retrieving a single string as a std::string. The value is placed in val, and the function returns true if the attribute was found.
|
inline |
Shortcut getattribute() for retrieving a single string as a char*.
| OIIO_API std::string geterror | ( | bool | clear = true | ) |
Returns any error string describing what went wrong if ImageInput::create() or ImageOutput::create() failed (since in such cases, the ImageInput or ImageOutput itself does not exist to have its own geterror() function called). This function returns the last error for this particular thread, and clear the pending error message unless clear is false; separate threads will not clobber each other's global error messages.
| OIIO_API bool has_error | ( | ) |
Is there a pending global error message waiting to be retrieved?
| OIIO_API bool is_imageio_format_name | ( | string_view | name | ) |
Is name one of the known format names?
Returns a numeric value for the version of OpenImageIO, 10000 for each major version, 100 for each minor version, 1 for each patch. For example, OpenImageIO 1.2.3 would return a value of 10203. One example of how this is useful is for plugins to query the version to be sure they are linked against an adequate version of the library.
| 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 |
||
| ) |
A version of convert_image that will break up big jobs into multiple threads.
|
inline |
| 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 |
||
| ) |
Convert unassociated to associated alpha by premultiplying all color (non-alpha, non-z) channels by alpha. The nchannels, width, height, and depth parameters describe the "shape" of the image data (along with optional stride overrides). The chbegin/chend describe which range of channels to actually premultiply.
1.8.6