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
 

Macros

#define OPENIMAGEIO_IMAGEIO_H
 

Typedefs

typedef ptrdiff_t stride_t
 
typedef unsigned long long imagesize_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)
 Union of two regions, the smallest region containing both. More...
 
constexpr ROI roi_intersection (const ROI &A, const ROI &B)
 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)
 
bool attribute (string_view name, float val)
 
bool attribute (string_view name, string_view val)
 
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, char **val)
 
bool getattribute (string_view name, std::string &val)
 
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 convert_types (TypeDesc src_type, const void *src, TypeDesc dst_type, void *dst, int n)
 
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 alpha_channel, int z_channel=-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 alpha_channel, int z_channel, 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 fmtdebug (const char *fmt, const T1 &v1, const Args &...args)
 debug output with fmt/stdformat conventions. More...
 
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 44 of file imageio.h.

Typedef Documentation

Definition at line 106 of file imageio.h.

Definition at line 107 of file imageio.h.

typedef unsigned long long imagesize_t

Type we use to express how many pixels (or bytes) constitute an image, tile, or scanline. Needs to be large enough to handle very big images (which we presume could be > 4GB).

Definition at line 85 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 101 of file imageio.h.

typedef ptrdiff_t stride_t

Type we use for stride lengths. This is only used to designate pixel, scanline, tile, or image plane sizes in user-allocated memory, so it doesn't need to represent sizes larger than can be malloced, therefore ptrdiff_t seemed right.

Definition at line 69 of file imageio.h.

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

Definition at line 1840 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 
)

Set a global attribute controlling OpenImageIO. Return true if the name and type were recognized and the attribute was set.

Documented attributes: int threads How many threads to use for operations that can be sped by spawning threads (default=0, meaning to use the full available hardware concurrency detected). int exr_threads The size of the internal OpenEXR thread pool. The default is to use the full available hardware concurrency detected. Default is 0 meaning to use full available hardware concurrency detected, -1 means to disable usage of the OpenEXR thread pool and execute everything in the caller thread. string plugin_searchpath Colon-separated list of directories to search for dynamically-loaded format plugins. int read_chunk The number of scanlines that will be attempted to read at once for read_image calls (default: 256). int debug When nonzero, various debug messages may be printed. The default is 0 for release builds, >=1 for DEBUG builds, but also may be overridden by the OPENIMAGEIO_DEBUG env variable. int log_times When nonzero, various internals will record how much total time they spend in execution. If the value is >= 2, these times will be printed upon exit. Thd default is 0, but will be initialized to the value of the OPENIMAGEIO_LOG_TIMES environment variable, if it exists. 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.

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

Definition at line 1632 of file imageio.h.

bool attribute ( string_view  name,
float  val 
)
inline

Definition at line 1635 of file imageio.h.

bool attribute ( string_view  name,
string_view  val 
)
inline

Definition at line 1638 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  alpha_channel,
int  z_channel = -1 
)
inline

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

Definition at line 1753 of file imageio.h.

OIIO_API bool convert_types ( TypeDesc  src_type,
const void src,
TypeDesc  dst_type,
void dst,
int  n 
)

Helper function: convert contiguous arbitrary data between two arbitrary 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.

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 1866 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 1858 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 
)

debug output with fmt/stdformat conventions.

Definition at line 1851 of file imageio.h.

float get_float_attribute ( string_view  name,
float  defaultval = 0 
)
inline

Definition at line 1708 of file imageio.h.

int get_int_attribute ( string_view  name,
int  defaultval = 0 
)
inline

Definition at line 1704 of file imageio.h.

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

Definition at line 1712 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 attribute() call, getattribute() can also retrieve the following read-only attributes: string "format_list" Comma-separated list of all format names supported or for which plugins could be found. string "input_format_list" Comma-separated list of all format names supported or for which plugins could be found that can read images. string "output_format_list" Comma-separated list of all format names supported or for which plugins could be found that can write images. string "extension_list" For each format, the format name followed by a colon, followed by 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 an external expendent library, the format name followed by a colon, followed by the name of the library. Semicolons separate the lists for formats. For example, "jpeg:jpeg-turbo 1.5.1;png:libpng 1.6.29;gif:gif_lib 5.1.4" string "timing_report" A string containing the report of all the log_times. string "oiio:simd" Comma-separated list of the SIMD-related capabilities enabled when the OIIO library was built. For example, "sse2,sse3,ssse3,sse41,sse42,avx" string "hw:simd" Comma-separated list of the SIMD-related capabilities detected at runtime at the time of the query (which may not match the support compiled into the library). int "resident_memory_used_MB" Approximate process memory used (resident) by the application, in MB. This might be helpful in debugging.

bool getattribute ( string_view  name,
int val 
)
inline

Definition at line 1688 of file imageio.h.

bool getattribute ( string_view  name,
float &  val 
)
inline

Definition at line 1691 of file imageio.h.

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

Definition at line 1694 of file imageio.h.

bool getattribute ( string_view  name,
std::string val 
)
inline

Definition at line 1697 of file imageio.h.

OIIO_API std::string geterror ( )

Special geterror() called after ImageInput::create or ImageOutput::create, since if create fails, there's no object on which call obj->geterror(). This function returns the last error for this particular thread; separate threads will not clobber each other's global error messages.

OIIO_API int openimageio_version ( )

Retrieve the version of OpenImageIO for the library. This is so plugins can query 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  alpha_channel,
int  z_channel,
int  nthreads = 0 
)
inline

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

Definition at line 1777 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.

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

Intersection of two regions.

Definition at line 211 of file imageio.h.

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

Union of two regions, the smallest region containing both.

Definition at line 201 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 92 of file imageio.h.