Re: [Openexr-devel] Question about using exr PAI from C

[Florian Kainz]

Hi Konstantin,

Depending on what you mean by "3D image", OpenEXR may or
may not be what you want:

Stereo images are easy to support.  Just store two sets of
image channels, for example, R,G,B for the left-eye view
(and for compatibility with applications that are not
stereo-enabled), and Rright,Gright,Bright for the right-
eye view.  Additional data, such as the distance between
the eyes, go into custom attributes in the file header.

On the other hand, storing volumetric data is not directly
supported.  You'd have to resort to tricks such as storing
a 3D grid with Nx by Ny by Nz voxels as a 2D image vith
Nx by Ny*Nz pixels, and adding a custom attribute to tell
applications that the 2D image is really a 3D grid.

If you do decide to use OpenEXR for your project, then I
would recommend that you use the C++ API.  The C++ API is
described in our programming tutorial, available at this
URL: http://www.openexr.com/ReadingAndWritingImageFiles.pdf

The C API was written for situations where an OpenEXR driver
must be fitted into existing C software, and where compiling
the driver code with a C++ compiler is not an option.
The C API is rather limited compared to what C++ offers.

The entire C API is defined in header file ImfCRgbaFile.h.
The functions declared in this header are simply wrappers
about the corresponding C++ functions.  For example,

    ImfOutputFile *out = ...;
    ImfOutputSetFrameBuffer (out, base, xStride, yStride);
    ImfOutputWritePixels (out, numScanlines);

is equivalent to

    Imf::RgbaOutputFile out ...;
    out->setFrameBuffer (base, xStride, yStride);
    out->writePixels (numScanlines);

One difference between the C and C++ APIs is how errors
are reported.  The C API uses return values:

    ImfOutputFile *out = ...;

    if (!out ||
        !ImfOutputSetFrameBuffer (out, base, xStride, yStride) ||
        !ImfOutputWritePixels (out, numScanlines))
    {
        printf ("%s\n", ImfErrorMessage);
    }

The C++ API uses exceptions:

    try
    {
        ImfOutputFile *out = ...;
        ImfOutputSetFrameBuffer (out, base, xStride, yStride);
        ImfOutputWritePixels (out, numScanlines);
    }
    catch (std::exception &e)
    {
        printf ("%s\n", e.what());
    }

Hope this helps,

Florian


P.S.: I'd have to disagree with Chris Burns regarding OpenEXR's
ability to store custom data.  OpenEXR allows you to define your
own "attributes", which are OpenEXR's equivalent to TIFF "tags",
and you can store any number of image channels.