OpenImageIO
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Typedefs | Functions | Variables
imageio.h File Reference
#include <vector>
#include <string>
#include <limits>
#include <cmath>
#include "export.h"
#include "typedesc.h"
#include "paramlist.h"
#include "version.h"

Go to the source code of this file.

Classes

class  ImageSpec
 
struct  DeepData
 Structure to hold "deep" data – multiple samples per pixel. More...
 
class  ImageInput
 
class  ImageOutput
 

Typedefs

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

OIIO_API int openimageio_version ()
 
OIIO_API std::string geterror ()
 
OIIO_API bool attribute (const std::string &name, TypeDesc type, const void *val)
 
bool attribute (const std::string &name, int val)
 
bool attribute (const std::string &name, float val)
 
bool attribute (const std::string &name, const char *val)
 
bool attribute (const std::string &name, const std::string &val)
 
OIIO_API bool getattribute (const std::string &name, TypeDesc type, void *val)
 
bool getattribute (const std::string &name, int &val)
 
bool getattribute (const std::string &name, float &val)
 
bool getattribute (const std::string &name, char **val)
 
bool getattribute (const std::string &name, std::string &val)
 
OIIO_API int quantize (float value, int quant_black, int quant_white, int quant_min, int quant_max)
 
OIIO_API bool convert_types (TypeDesc src_type, const void *src, TypeDesc dst_type, void *dst, int n)
 
OIIO_API bool convert_types (TypeDesc src_type, const void *src, TypeDesc dst_type, void *dst, int n, int alpha_channel, int z_channel=-1)
 
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, int alpha_channel=-1, int z_channel=-1)
 
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 alpha_channel=-1, int z_channel=-1, int nthreads=0)
 
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 decode_exif (const void *exif, int length, ImageSpec &spec)
 
OIIO_API void encode_exif (const ImageSpec &spec, std::vector< char > &blob)
 
OIIO_API bool decode_iptc_iim (const void *iptc, int length, ImageSpec &spec)
 
OIIO_API void encode_iptc_iim (const ImageSpec &spec, std::vector< char > &iptc)
 
OIIO_API bool decode_xmp (const std::string &xml, ImageSpec &spec)
 
OIIO_API std::string encode_xmp (const ImageSpec &spec, bool minimal=false)
 
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 _ImageIO_force_link ()
 

Variables

 OIIO_NAMESPACE_ENTER
 
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.

Typedef Documentation

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

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.

Function Documentation

OIIO_API bool attribute ( const std::string &  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=1; note that 0 means "as many threads as cores"). string plugin_searchpath Colon-separated list of directories to search for dynamically-loaded format plugins. string format_list (for 'getattribute' only, cannot set) Comma-separated list of all format names supported or for which plugins could be found. string extension_list (for 'getattribute' only, cannot set) 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"

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,
int  alpha_channel = -1,
int  z_channel = -1 
)

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_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 UNKNWON, it will be assumed to be the same as src_type.

OIIO_API bool convert_types ( TypeDesc  src_type,
const void *  src,
TypeDesc  dst_type,
void *  dst,
int  n,
int  alpha_channel,
int  z_channel = -1 
)

DEPRECATED – for some reason we had a convert_types that took alpha_channel and z_channel parameters, but never did anything with them.

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 bool decode_exif ( const void *  exif,
int  length,
ImageSpec spec 
)

Decode a raw Exif data block and save all the metadata in an ImageSpec. Return true if all is ok, false if the exif block was somehow malformed. The binary data pointed to by 'exif' should start with a TIFF directory header.

OIIO_API bool decode_iptc_iim ( const void *  iptc,
int  length,
ImageSpec spec 
)

Add metadata to spec based on raw IPTC (International Press Telecommunications Council) metadata in the form of an IIM (Information Interchange Model). Return true if all is ok, false if the iptc block was somehow malformed. This is a utility function to make it easy for multiple format plugins to support embedding IPTC metadata without having to duplicate functionality within each plugin. Note that IIM is actually considered obsolete and is replaced by an XML scheme called XMP.

OIIO_API bool decode_xmp ( const std::string &  xml,
ImageSpec spec 
)

Add metadata to spec based on XMP data in an XML block. Return true if all is ok, false if the xml was somehow malformed. This is a utility function to make it easy for multiple format plugins to support embedding XMP metadata without having to duplicate functionality within each plugin.

OIIO_API void encode_exif ( const ImageSpec spec,
std::vector< char > &  blob 
)

Construct an Exif data block from the ImageSpec, appending the Exif data as a big blob to the char vector.

OIIO_API void encode_iptc_iim ( const ImageSpec spec,
std::vector< char > &  iptc 
)

Find all the IPTC-amenable metadata in spec and assemble it into an IIM data block in iptc. This is a utility function to make it easy for multiple format plugins to support embedding IPTC metadata without having to duplicate functionality within each plugin. Note that IIM is actually considered obsolete and is replaced by an XML scheme called XMP.

OIIO_API std::string encode_xmp ( const ImageSpec spec,
bool  minimal = false 
)

Find all the relavant metadata (IPTC, Exif, etc.) in spec and assemble it into an XMP XML string. This is a utility function to make it easy for multiple format plugins to support embedding XMP metadata without having to duplicate functionality within each plugin. If 'minimal' is true, then don't encode things that would be part of ordinary TIFF or exif tags.

OIIO_API bool getattribute ( const std::string &  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.

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  alpha_channel = -1,
int  z_channel = -1,
int  nthreads = 0 
)

A version of convert_image that will break up big jobs into multiple threads.

OIIO_API int quantize ( float  value,
int  quant_black,
int  quant_white,
int  quant_min,
int  quant_max 
)

Helper routine: quantize a value to an integer given the quantization parameters.

Variable Documentation

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

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

OIIO_NAMESPACE_ENTER
Initial value:
{
typedef ptrdiff_t stride_t