HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
imageio.h File Reference
#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 std::string geterror ()
 
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...
 
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>
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()
 

Detailed Description

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.

Macro Definition Documentation

#define OPENIMAGEIO_IMAGEIO_H

Definition at line 18 of file imageio.h.

Typedef Documentation

Definition at line 69 of file imageio.h.

Definition at line 70 of file imageio.h.

using imagesize_t = uint64_t

Type we use to express how many pixels (or bytes) constitute an image, tile, or scanline.

Definition at line 51 of file imageio.h.

typedef bool(* ProgressCallback)(void *opaque_data, float portion_done)

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.

Definition at line 64 of file imageio.h.

using stride_t = int64_t

Type we use for stride lengths between pixels, scanlines, or image planes.

Definition at line 47 of file imageio.h.

typedef bool(* wrap_impl)(int &coord, int origin, int width)

Definition at line 2735 of file imageio.h.

Function Documentation

OIIO_API void _ImageIO_force_link ( )
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 [-theramplitude,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 an 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 plugin_searchpath

    Colon-separated list of directories to search for dynamically-loaded format plugins.

  • 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 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. If the value of log_times is 2 or more when the application terminates, the timing report will be printed to stdout upon exit.

    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.

    The report of totals can be retrieved as the value of the "timing_report" attribute, using OIIO:get_attribute() call.

Examples:
field3d/f3d_io.C.
bool attribute ( string_view  name,
int  val 
)
inline

Shortcut attribute() for setting a single integer.

Definition at line 2464 of file imageio.h.

bool attribute ( string_view  name,
float  val 
)
inline

Shortcut attribute() for setting a single float.

Definition at line 2468 of file imageio.h.

bool attribute ( string_view  name,
string_view  val 
)
inline

Shortcut attribute() for setting a single string.

Definition at line 2472 of file imageio.h.

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.

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 
)
inline

DEPRECATED(2.0) – the alpha_channel, z_channel were never used.

Definition at line 2645 of file imageio.h.

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.

bool convert_types ( TypeDesc  src_type,
const void src,
TypeDesc  dst_type,
void dst,
int  n = 1 
)
inline

DEPRECATED(2.1): old name.

Definition at line 2622 of file imageio.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.

template<typename T1 , typename... Args>
void debug ( const char *  fmt,
const T1 &  v1,
const Args &...  args 
)

debug output with the same conventions as Strutil::format. Beware, this will change one day!

Definition at line 2769 of file imageio.h.

template<typename T1 , typename... Args>
void debugf ( const char *  fmt,
const T1 &  v1,
const Args &...  args 
)

debug output with printf conventions.

Definition at line 2761 of file imageio.h.

template<typename T1 , typename... Args>
void debugfmt ( const char *  fmt,
const T1 &  v1,
const Args &...  args 
)

debug output with std::format conventions.

Definition at line 2746 of file imageio.h.

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.

template<typename T1 , typename... Args>
void fmtdebug ( const char *  fmt,
const T1 &  v1,
const Args &...  args 
)

Definition at line 2754 of file imageio.h.

float get_float_attribute ( string_view  name,
float  defaultval = 0 
)
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.

Definition at line 2583 of file imageio.h.

int get_int_attribute ( string_view  name,
int  defaultval = 0 
)
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.

Definition at line 2576 of file imageio.h.

string_view get_string_attribute ( string_view  name,
string_view  defaultval = string_view() 
)
inline

Shortcut getattribute() for retrieving a single string, with a supplied default value that will be returned if the attribute is not found.

Definition at line 2589 of file imageio.h.

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_list
  • string input_format_list
  • string 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 "timing_report" A string containing the report of all the log_times.
  • string hw:simd
  • string 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)
bool getattribute ( string_view  name,
int val 
)
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.

Definition at line 2550 of file imageio.h.

bool getattribute ( string_view  name,
float &  val 
)
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.

Definition at line 2556 of file imageio.h.

bool getattribute ( string_view  name,
std::string val 
)
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.

Definition at line 2562 of file imageio.h.

bool getattribute ( string_view  name,
char **  val 
)
inline

Shortcut getattribute() for retrieving a single string as a char*.

Definition at line 2570 of file imageio.h.

OIIO_API std::string geterror ( )

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; separate threads will not clobber each other's global error messages.

OIIO_API bool is_imageio_format_name ( string_view  name)

Is name one of the known format names?

OIIO_API int openimageio_version ( )

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.

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 
)
inline

DEPRECATED(2.0) – the alpha_channel, z_channel were never used.

Definition at line 2669 of file imageio.h.

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.

constexpr ROI roi_intersection ( const ROI A,
const ROI B 
)
inlinenoexcept

Intersection of two regions.

Definition at line 197 of file imageio.h.

constexpr ROI roi_union ( const ROI A,
const ROI B 
)
inlinenoexcept

Union of two regions, the smallest region containing both.

Definition at line 187 of file imageio.h.

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_mirror ( 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 
)

Variable Documentation

const stride_t AutoStride = std::numeric_limits<stride_t>::min()

Special value to indicate a stride length that should be auto-computed.

Definition at line 55 of file imageio.h.