375 lines
13 KiB
C
375 lines
13 KiB
C
|
///////////////////////////////////////////////////////////////////////////
|
||
|
|
//
|
||
|
|
// Copyright (c) 2014, Industrial Light & Magic, a division of Lucas
|
||
|
|
// Digital Ltd. LLC
|
||
|
|
//
|
||
|
|
// All rights reserved.
|
||
|
|
//
|
||
|
|
// Redistribution and use in source and binary forms, with or without
|
||
|
|
// modification, are permitted provided that the following conditions are
|
||
|
|
// met:
|
||
|
|
// * Redistributions of source code must retain the above copyright
|
||
|
|
// notice, this list of conditions and the following disclaimer.
|
||
|
|
// * Redistributions in binary form must reproduce the above
|
||
|
|
// copyright notice, this list of conditions and the following disclaimer
|
||
|
|
// in the documentation and/or other materials provided with the
|
||
|
|
// distribution.
|
||
|
|
// * Neither the name of Industrial Light & Magic nor the names of
|
||
|
|
// its contributors may be used to endorse or promote products derived
|
||
|
|
// from this software without specific prior written permission.
|
||
|
|
//
|
||
|
|
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||
|
|
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||
|
|
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
||
|
|
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||
|
|
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||
|
|
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||
|
|
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||
|
|
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||
|
|
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||
|
|
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||
|
|
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
//
|
||
|
|
///////////////////////////////////////////////////////////////////////////
|
||
|
|
|
||
|
|
#ifndef INCLUDED_IMF_IMAGE_H
|
||
|
|
#define INCLUDED_IMF_IMAGE_H
|
||
|
|
|
||
|
|
//----------------------------------------------------------------------------
|
||
|
|
//
|
||
|
|
// class Image -- an in-memory data structure that can hold an arbitrary
|
||
|
|
// OpenEXR image, flat or deep, with one or multiple resolution levels,
|
||
|
|
// and with an arbitrary set of channels.
|
||
|
|
//
|
||
|
|
// An image is a container for a set of image levels, and an image level
|
||
|
|
// is a container for a set of image channels. An image channel contains
|
||
|
|
// an array of pixel values of type half, float or unsigned int.
|
||
|
|
//
|
||
|
|
// For example:
|
||
|
|
//
|
||
|
|
// image --+-- level 0 --+-- channel "R" --- pixel data
|
||
|
|
// | |
|
||
|
|
// | +-- channel "G" --- pixel data
|
||
|
|
// | |
|
||
|
|
// | +-- channel "B" --- pixel data
|
||
|
|
// |
|
||
|
|
// +-- level 1 --+-- channel "R" --- pixel data
|
||
|
|
// | |
|
||
|
|
// | +-- channel "G" --- pixel data
|
||
|
|
// | |
|
||
|
|
// | +-- channel "B" --- pixel data
|
||
|
|
// |
|
||
|
|
// +-- level 2 --+-- channel "R" --- pixel data
|
||
|
|
// |
|
||
|
|
// +-- channel "G" --- pixel data
|
||
|
|
// |
|
||
|
|
// +-- channel "B" --- pixel data
|
||
|
|
//
|
||
|
|
// An image has a level mode, which can be ONE_LEVEL, MIPMAP_LEVELS or
|
||
|
|
// RIPMAP_LEVELS, and a level rounding mode, which can be ROUND_UP or
|
||
|
|
// ROUND_DOWN. Together, the level mode and the level rounding mode
|
||
|
|
// determine how many levels an image contains, and how large the data
|
||
|
|
// window for each level is. All levels in an image have the same set
|
||
|
|
// of channels.
|
||
|
|
//
|
||
|
|
// An image channel has a name (e.g. "R", "Z", or "xVelocity"), a type
|
||
|
|
// (HALF, FLOAT or UINT) and x and y sampling rates. A channel stores
|
||
|
|
// samples for a pixel if the pixel is inside the data window of the
|
||
|
|
// level to which the channel belongs, and the x and y coordinates of
|
||
|
|
// the pixel are divisible by the x and y sampling rates of the channel.
|
||
|
|
//
|
||
|
|
// An image can be either flat or deep. In a flat image each channel
|
||
|
|
// in each level stores at most one value per pixel. In a deep image
|
||
|
|
// each channel in each level stores an arbitrary number of values per
|
||
|
|
// pixel. As an exception, each level of a deep image has a sample count
|
||
|
|
// channel with a single value per pixel; this value determines how many
|
||
|
|
// values each of the other channels in the same level has at the same
|
||
|
|
// pixel location.
|
||
|
|
//
|
||
|
|
// The classes Image, ImageLevel and ImageChannel are abstract base
|
||
|
|
// classes. Two sets of concrete classes, one for flat and one for
|
||
|
|
// deep images, are derived from the base classes.
|
||
|
|
//
|
||
|
|
//----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
#include "ImfImageLevel.h"
|
||
|
|
#include <ImfTileDescription.h>
|
||
|
|
#include <ImfArray.h>
|
||
|
|
#include "ImfExport.h"
|
||
|
|
|
||
|
|
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
|
||
|
|
|
||
|
|
class Channel;
|
||
|
|
|
||
|
|
|
||
|
|
class IMF_EXPORT Image
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
|
||
|
|
//
|
||
|
|
// Constructor and destructor
|
||
|
|
//
|
||
|
|
|
||
|
|
Image ();
|
||
|
|
virtual ~Image ();
|
||
|
|
|
||
|
|
|
||
|
|
//
|
||
|
|
// Access to the image's level mode and level rounding mode.
|
||
|
|
//
|
||
|
|
|
||
|
|
LevelMode levelMode() const;
|
||
|
|
LevelRoundingMode levelRoundingMode() const;
|
||
|
|
|
||
|
|
|
||
|
|
//
|
||
|
|
// Number of levels:
|
||
|
|
//
|
||
|
|
// numXLevels() returns the image's number of levels in the x direction.
|
||
|
|
//
|
||
|
|
// if levelMode() == ONE_LEVEL:
|
||
|
|
// return value is: 1
|
||
|
|
//
|
||
|
|
// if levelMode() == MIPMAP_LEVELS:
|
||
|
|
// return value is: rfunc (log (max (w, h)) / log (2)) + 1
|
||
|
|
//
|
||
|
|
// if levelMode() == RIPMAP_LEVELS:
|
||
|
|
// return value is: rfunc (log (w) / log (2)) + 1
|
||
|
|
//
|
||
|
|
// where
|
||
|
|
// w is the width of the image's data window, max.x - min.x + 1,
|
||
|
|
// h is the height of the image's data window, max.y - min.y + 1,
|
||
|
|
// and rfunc(x) is either floor(x), or ceil(x), depending on
|
||
|
|
// whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
|
||
|
|
//
|
||
|
|
// numYLevels() returns the image's number of levels in the y direction.
|
||
|
|
//
|
||
|
|
// if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
|
||
|
|
// return value is the same as for numXLevels()
|
||
|
|
//
|
||
|
|
// if levelMode() == RIPMAP_LEVELS:
|
||
|
|
// return value is: rfunc (log (h) / log (2)) + 1
|
||
|
|
//
|
||
|
|
//
|
||
|
|
// numLevels() is a convenience function for use with MIPMAP_LEVELS images.
|
||
|
|
//
|
||
|
|
// if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
|
||
|
|
// return value is the same as for numXLevels()
|
||
|
|
//
|
||
|
|
// if levelMode() == RIPMAP_LEVELS:
|
||
|
|
// a LogicExc exception is thrown
|
||
|
|
//
|
||
|
|
|
||
|
|
int numLevels() const;
|
||
|
|
int numXLevels() const;
|
||
|
|
int numYLevels() const;
|
||
|
|
|
||
|
|
|
||
|
|
//
|
||
|
|
// Per-level data windows
|
||
|
|
//
|
||
|
|
// dataWindow() returns the data window for the image; this is the
|
||
|
|
// same as the data window for the level with level number (0, 0).
|
||
|
|
//
|
||
|
|
// dataWindowForLevel(lx, ly) returns the data window for level x,
|
||
|
|
// that is, the window for which the image level with level number
|
||
|
|
// (lx, ly) has allocated pixel storage.
|
||
|
|
//
|
||
|
|
// return value is a Box2i with min value:
|
||
|
|
// (dataWindow().min.x,
|
||
|
|
// dataWindow().min.y)
|
||
|
|
//
|
||
|
|
// and max value:
|
||
|
|
// (dataWindow().min.x + levelWidth(lx) - 1,
|
||
|
|
// dataWindow().min.y + levelHeight(ly) - 1)
|
||
|
|
//
|
||
|
|
// dataWindowForLevel(l) is a convenience function used for ONE_LEVEL
|
||
|
|
// and MIPMAP_LEVELS files. It returns dataWindowForLevel(l,l)).
|
||
|
|
//
|
||
|
|
|
||
|
|
const IMATH_NAMESPACE::Box2i & dataWindow() const;
|
||
|
|
const IMATH_NAMESPACE::Box2i & dataWindowForLevel(int l) const;
|
||
|
|
const IMATH_NAMESPACE::Box2i & dataWindowForLevel(int lx, int ly) const;
|
||
|
|
|
||
|
|
|
||
|
|
//
|
||
|
|
// Size of a level:
|
||
|
|
//
|
||
|
|
// levelWidth(lx) returns the width of a level with level
|
||
|
|
// number (lx, *), where * is any number.
|
||
|
|
//
|
||
|
|
// return value is:
|
||
|
|
// max (1, rfunc (w / pow (2, lx)))
|
||
|
|
//
|
||
|
|
//
|
||
|
|
// levelHeight(ly) returns the height of a level with level
|
||
|
|
// number (*, ly), where * is any number.
|
||
|
|
//
|
||
|
|
// return value is:
|
||
|
|
// max (1, rfunc (h / pow (2, ly)))
|
||
|
|
//
|
||
|
|
|
||
|
|
int levelWidth (int lx) const;
|
||
|
|
int levelHeight (int ly) const;
|
||
|
|
|
||
|
|
|
||
|
|
//
|
||
|
|
// Resize the image:
|
||
|
|
//
|
||
|
|
// resize(dw,lm,lrm) sets the data window of the image to dw,
|
||
|
|
// sets the level mode to lm and the level rounding mode to lrm,
|
||
|
|
// and allocates new storage for image levels and image channels.
|
||
|
|
// The set of channels in the image does not change.
|
||
|
|
//
|
||
|
|
// The contents of the image are lost; pixel data are not preserved
|
||
|
|
// across the resize operation. If resizing fails, then the image
|
||
|
|
// will be left with an empty data window and no image levels.
|
||
|
|
//
|
||
|
|
// resize(dw) is the same as resize(dw,levelMode(),levelRoundingMode())
|
||
|
|
//
|
||
|
|
|
||
|
|
void resize(const IMATH_NAMESPACE::Box2i &dataWindow);
|
||
|
|
|
||
|
|
virtual void resize(const IMATH_NAMESPACE::Box2i &dataWindow,
|
||
|
|
LevelMode levelMode,
|
||
|
|
LevelRoundingMode levelRoundingMode);
|
||
|
|
|
||
|
|
//
|
||
|
|
// Shift the pixels and the data window of an image:
|
||
|
|
//
|
||
|
|
// shiftPixels(dx,dy) shifts the image by dx pixels horizontally and
|
||
|
|
// dy pixels vertically. A pixel at location (x,y) moves to position
|
||
|
|
// (x+dx, y+dy). The data window of the image is shifted along with
|
||
|
|
// the pixels. No pixel data are lost.
|
||
|
|
//
|
||
|
|
// The horizontal and vertical shift distances must be multiples of
|
||
|
|
// the x and y sampling rates of all image channels. If they are not,
|
||
|
|
// shiftPixels() throws an ArgExc exception.
|
||
|
|
//
|
||
|
|
|
||
|
|
void shiftPixels(int dx, int dy);
|
||
|
|
|
||
|
|
|
||
|
|
//
|
||
|
|
// Insert a new channel into the image.
|
||
|
|
//
|
||
|
|
// The arguments to this function are the same as for adding a
|
||
|
|
// a channel to an OpenEXR file: channel name, x and y sampling
|
||
|
|
// rates, and a "perceptually approximately linear" flag.
|
||
|
|
//
|
||
|
|
// If the image already contains a channel with the same name
|
||
|
|
// as the new name then the existing channel is deleted before
|
||
|
|
// the new channel is added.
|
||
|
|
//
|
||
|
|
|
||
|
|
void insertChannel (const std::string &name,
|
||
|
|
PixelType type,
|
||
|
|
int xSampling = 1,
|
||
|
|
int ySampling = 1,
|
||
|
|
bool pLinear = false);
|
||
|
|
|
||
|
|
void insertChannel (const std::string &name,
|
||
|
|
const Channel &channel);
|
||
|
|
|
||
|
|
//
|
||
|
|
// Erase channels from an image:
|
||
|
|
//
|
||
|
|
// eraseChannel(n) erases the channel with name n.
|
||
|
|
// clearChannels() erases all channels.
|
||
|
|
//
|
||
|
|
|
||
|
|
void eraseChannel(const std::string &name);
|
||
|
|
void clearChannels();
|
||
|
|
|
||
|
|
|
||
|
|
//
|
||
|
|
// Rename an image channel:
|
||
|
|
//
|
||
|
|
// renameChannel(nOld,nNew) changes the name of the image channel
|
||
|
|
// with name nOld to nNew.
|
||
|
|
//
|
||
|
|
// If the image already contains a channel called nNew, or if the
|
||
|
|
// image does not contain a channel called nOld, then renameChannel()
|
||
|
|
// throws an ArgExc exception.
|
||
|
|
//
|
||
|
|
// In the (unlikely) event that renaming the image channel causes
|
||
|
|
// the program to run out of memory, renameChannel() erases the
|
||
|
|
// channel that is being renamed, and throws an exception.
|
||
|
|
//
|
||
|
|
|
||
|
|
void renameChannel(const std::string &oldName,
|
||
|
|
const std::string &newName);
|
||
|
|
|
||
|
|
//
|
||
|
|
// Rename multiple image channels at the same time:
|
||
|
|
//
|
||
|
|
// Given a map, m, from old to new channel names, renameChannels(m)
|
||
|
|
// assigns new names to the channels in the image. If m has an entry
|
||
|
|
// for a channel named c, then the channel will be renamed to m[c].
|
||
|
|
// If m has no entry for c, then the channel keeps its old name.
|
||
|
|
//
|
||
|
|
// If the same name would be assigned to more than one channel, then
|
||
|
|
// renameChannels() does not rename any channels but throws an ArgExc
|
||
|
|
// exception instead.
|
||
|
|
//
|
||
|
|
// In the (unlikely) event that renaming the image channel causes the
|
||
|
|
// program to run out of memory, renameChannels() erases all channels
|
||
|
|
// in the image and throws an exception.
|
||
|
|
//
|
||
|
|
|
||
|
|
void renameChannels(const RenamingMap &oldToNewNames);
|
||
|
|
|
||
|
|
|
||
|
|
//
|
||
|
|
// Accessing image levels by level number.
|
||
|
|
//
|
||
|
|
// level(lx,ly) returns a reference to the image level
|
||
|
|
// with level number (lx,ly).
|
||
|
|
//
|
||
|
|
// level(l) returns level(l,l).
|
||
|
|
//
|
||
|
|
|
||
|
|
virtual ImageLevel & level (int l = 0);
|
||
|
|
virtual const ImageLevel & level (int l = 0) const;
|
||
|
|
|
||
|
|
virtual ImageLevel & level (int lx, int ly);
|
||
|
|
virtual const ImageLevel & level (int lx, int ly) const;
|
||
|
|
|
||
|
|
|
||
|
|
protected:
|
||
|
|
|
||
|
|
virtual ImageLevel *
|
||
|
|
newLevel (int lx, int ly, const IMATH_NAMESPACE::Box2i &dataWindow) = 0;
|
||
|
|
|
||
|
|
private:
|
||
|
|
|
||
|
|
bool levelNumberIsValid (int lx, int ly) const;
|
||
|
|
void clearLevels ();
|
||
|
|
|
||
|
|
struct ChannelInfo
|
||
|
|
{
|
||
|
|
ChannelInfo (PixelType type = HALF,
|
||
|
|
int xSampling = 1,
|
||
|
|
int ySampling = 1,
|
||
|
|
bool pLinear = false);
|
||
|
|
|
||
|
|
PixelType type;
|
||
|
|
int xSampling;
|
||
|
|
int ySampling;
|
||
|
|
bool pLinear;
|
||
|
|
};
|
||
|
|
|
||
|
|
typedef std::map <std::string, ChannelInfo> ChannelMap;
|
||
|
|
|
||
|
|
IMATH_NAMESPACE::Box2i _dataWindow;
|
||
|
|
LevelMode _levelMode;
|
||
|
|
LevelRoundingMode _levelRoundingMode;
|
||
|
|
ChannelMap _channels;
|
||
|
|
Array2D<ImageLevel *> _levels;
|
||
|
|
};
|
||
|
|
|
||
|
|
|
||
|
|
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
|
||
|
|
|
||
|
|
#endif
|