All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Image_or_Const Class Reference

#include <imagebufalgo.h>


struct  None

Public Member Functions

 Image_or_Const (None)
 Image_or_Const (const ImageBuf &img)
 Image_or_Const (const ImageBuf *img)
 Image_or_Const (cspan< float > val)
 Image_or_Const (const float &val)
 Image_or_Const (const std::vector< float > &val)
 Image_or_Const (const float *v, size_t s)
 Image_or_Const (const float *v, int s)
bool is_img () const
bool is_val () const
bool is_empty () const
const ImageBufimg () const
const ImageBufimgptr () const
cspan< float > val () const
void swap (Image_or_Const &other)

Detailed Description

Some generalities about ImageBufAlgo functions: (READ ME!)

This section explains the general rules common to all ImageBufAlgo functions. Only exceptions to these rules will be explained in the subsequent listings of all the individual ImageBufAlgo functions.

Return values and error messages

Most ImageBufAlgo functions that produce image data come in two forms:

  1. Return an ImageBuf.

    The return value is a new ImageBuf containing the result image. In this case, an entirely new image will be created to hold the result. In case of error, the result image returned can have any error conditions checked with has_error() and geterror().

    // Method 1: Return an image result
    ImageBuf fg ("fg.exr"), bg ("bg.exr");
    ImageBuf dst = ImageBufAlgo::over (fg, bg);
    if (dst.has_error())
        std::cout << "error: " << dst.geterror() << "\n";
  2. Pass a destination ImageBuf reference as the first parameter.

    The function is passed a destination ImageBuf where the results will be stored, and the return value is a bool that is true if the function succeeds or false if the function fails. Upon failure, the destination ImageBuf (the one that is being altered) will have an error message set.

    // Method 2: Write into an existing image
    ImageBuf fg ("fg.exr"), bg ("bg.exr");
    ImageBuf dst;   // will be the output image
    bool ok = ImageBufAlgo::over (dst, fg, bg);
    if (! ok)
        std::cout << "error: " << dst.geterror() << "\n";

The first option (return an ImageBuf) is a more compact and intuitive notation that is natural for most simple uses. But the second option (pass an ImageBuf& referring to an existing destination) offers additional flexibility, including more careful control over allocations, the ability to partially overwrite regions of an existing image, and the ability for the destination image to also be one of the input images (for example, add(A,A,B) adds B into existing image A, with no third image allocated at all).

Region of interest

Most ImageBufAlgo functions take an optional ROI parameter that restricts the operation to a range in x, y, z, and channels. The default ROI (also known as `ROIAll()) means no region restriction.

For ImageBufAlgo functions that write into a destination ImageBuf parameter and it is already initialized (i.e. allocated with a particular size and data type), the operation will be performed on the pixels in the destination that overlap the ROI, leaving pixels in the destination which are outside the ROI unaltered.

For ImageBufAlgo functions that return an ImageBuf directly, or their dst parameter that is an uninitialized ImageBuf, the ROI (if set) determines the size of the result image. If the ROI is the default All, the result image size will be the union of the pixel data windows of the input images and have a data type determind by the data types of the input images.

Most ImageBufAlgo functions also respect the chbegin and chend members of the ROI, thus restricting the channel range on which the operation is performed. The default ROI constructor sets up the ROI to specify that the operation should be performed on all channels of the input image(s).

Constant and per-channel values

Many ImageBufAlgo functions take per-channel constant-valued arguments (for example, a fill color). These parameters are passed as cspan<float>. These are generally expected to have length equal to the number of channels. But you may also pass a single float which will be used as the value for all channels. (More generally, what is happening is that the last value supplied is replicated for any missing channel.)

Some ImageBufAlgo functions have parameters of type Image_or_Const, which may take either an ImageBuf reference, or a per-channel constant, or a single constant to be used for all channels.


All ImageBufAlgo functions take an optional nthreads parameter that signifies the maximum number of threads to use to parallelize the operation. The default value for nthreads is 0, which signifies that the number of thread should be the OIIO global default set by OIIO::attribute(), which itself defaults to be the detected level of hardware concurrency (number of cores available).

Generally you can ignore this parameter (or pass 0), meaning to use all the cores available in order to perform the computation as quickly as possible. The main reason to explicitly pass a different number (generally 1) is if the application is multithreaded at a high level, and the thread calling the ImageBufAlgo function just wants to continue doing the computation without spawning additional threads, which might tend to crowd out the other application threads.Image_or_Const: Parameter-passing helper that is a non-owning reference to either an ImageBuf&, ImageBuf*, per-channel float constant, or a single float constant. This lets us tame the combinatorics of functions where each of several input parameters may be either images or constant values.

Definition at line 180 of file imagebufalgo.h.

Constructor & Destructor Documentation

Image_or_Const::Image_or_Const ( None  )

Definition at line 183 of file imagebufalgo.h.

Image_or_Const::Image_or_Const ( const ImageBuf img)

Definition at line 184 of file imagebufalgo.h.

Image_or_Const::Image_or_Const ( const ImageBuf img)

Definition at line 185 of file imagebufalgo.h.

Image_or_Const::Image_or_Const ( cspan< float >  val)

Definition at line 186 of file imagebufalgo.h.

Image_or_Const::Image_or_Const ( const float &  val)

Definition at line 187 of file imagebufalgo.h.

Image_or_Const::Image_or_Const ( const std::vector< float > &  val)

Definition at line 188 of file imagebufalgo.h.

Image_or_Const::Image_or_Const ( const float *  v,
size_t  s 

Definition at line 189 of file imagebufalgo.h.

Image_or_Const::Image_or_Const ( const float *  v,
int  s 

Definition at line 190 of file imagebufalgo.h.

Member Function Documentation

const ImageBuf& Image_or_Const::img ( ) const

Definition at line 195 of file imagebufalgo.h.

const ImageBuf* Image_or_Const::imgptr ( ) const

Definition at line 196 of file imagebufalgo.h.

bool Image_or_Const::is_empty ( ) const

Definition at line 194 of file imagebufalgo.h.

bool Image_or_Const::is_img ( ) const

Definition at line 192 of file imagebufalgo.h.

bool Image_or_Const::is_val ( ) const

Definition at line 193 of file imagebufalgo.h.

void Image_or_Const::swap ( Image_or_Const other)

Definition at line 199 of file imagebufalgo.h.

cspan<float> Image_or_Const::val ( ) const

Definition at line 197 of file imagebufalgo.h.

The documentation for this class was generated from the following file: