///////////////////////////////////////////////////////////////////////////

//

// 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