///////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2004, 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_TILED_INPUT_FILE_H
#define INCLUDED_IMF_TILED_INPUT_FILE_H
//-----------------------------------------------------------------------------
//
// class TiledInputFile
//
//-----------------------------------------------------------------------------
#include <ImfHeader.h>
#include <ImfFrameBuffer.h>
#include "ImathBox.h"
#include <ImfTileDescription.h>
#include <ImfThreading.h>
namespace Imf {
class TiledInputFile
{
public:
//--------------------------------------------------------------------
// A constructor that opens the file with the specified name, and
// reads the file header. The constructor throws an Iex::ArgExc
// exception if the file is not tiled.
// The numThreads parameter specifies how many worker threads this
// file will try to keep busy when decompressing individual tiles.
// Destroying TiledInputFile objects constructed with this constructor
// automatically closes the corresponding files.
//--------------------------------------------------------------------
TiledInputFile (const char fileName[],
int numThreads = globalThreadCount ());
// ----------------------------------------------------------
// A constructor that attaches the new TiledInputFile object
// to a file that has already been opened.
// Destroying TiledInputFile objects constructed with this
// constructor does not automatically close the corresponding
// files.
// ----------------------------------------------------------
TiledInputFile (IStream &is, int numThreads = globalThreadCount ());
//-----------
// Destructor
//-----------
virtual ~TiledInputFile ();
//------------------------
// Access to the file name
//------------------------
const char * fileName () const;
//--------------------------
// Access to the file header
//--------------------------
const Header & header () const;
//----------------------------------
// Access to the file format version
//----------------------------------
int version () const;
//-----------------------------------------------------------
// Set the current frame buffer -- copies the FrameBuffer
// object into the TiledInputFile object.
//
// The current frame buffer is the destination for the pixel
// data read from the file. The current frame buffer must be
// set at least once before readTile() is called.
// The current frame buffer can be changed after each call
// to readTile().
//-----------------------------------------------------------
void setFrameBuffer (const FrameBuffer &frameBuffer);
//-----------------------------------
// Access to the current frame buffer
//-----------------------------------
const FrameBuffer & frameBuffer () const;
//------------------------------------------------------------
// Check if the file is complete:
//
// isComplete() returns true if all pixels in the data window
// (in all levels) are present in the input file, or false if
// any pixels are missing. (Another program may still be busy
// writing the file, or file writing may have been aborted
// prematurely.)
//------------------------------------------------------------
bool isComplete () const;
//--------------------------------------------------
// Utility functions:
//--------------------------------------------------
//---------------------------------------------------------
// Multiresolution mode and tile size:
// The following functions return the xSize, ySize and mode
// fields of the file header's TileDescriptionAttribute.
//---------------------------------------------------------
unsigned int tileXSize () const;
unsigned int tileYSize () const;
LevelMode levelMode () const;
LevelRoundingMode levelRoundingMode () const;
//--------------------------------------------------------------------
// Number of levels:
//
// numXLevels() returns the file's number of levels in 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,
// y 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 file's number of levels in 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 files.
//
// if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
// return value is the same as for numXLevels()
//
// if levelMode() == RIPMAP_LEVELS:
// an Iex::LogicExc exception is thrown
//
// isValidLevel(lx, ly) returns true if the file contains
// a level with level number (lx, ly), false if not.
//
//--------------------------------------------------------------------
int numLevels () const;
int numXLevels () const;
int numYLevels () const;
bool isValidLevel (int lx, int ly) const;
//----------------------------------------------------------
// Dimensions 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;
//--------------------------------------------------------------
// Number of tiles:
//
// numXTiles(lx) returns the number of tiles in x direction
// that cover a level with level number (lx, *), where * is
// any number.
//
// return value is:
// (levelWidth(lx) + tileXSize() - 1) / tileXSize()
//
//
// numYTiles(ly) returns the number of tiles in y direction
// that cover a level with level number (*, ly), where * is
// any number.
//
// return value is:
// (levelHeight(ly) + tileXSize() - 1) / tileXSize()
//
//--------------------------------------------------------------
int numXTiles (int lx = 0) const;
int numYTiles (int ly = 0) const;
//---------------------------------------------------------------
// Level pixel ranges:
//
// dataWindowForLevel(lx, ly) returns a 2-dimensional region of
// valid pixel coordinates for a level with level number (lx, ly)
//
// 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(level) is a convenience function used
// for ONE_LEVEL and MIPMAP_LEVELS files. It returns
// dataWindowForLevel(level, level).
//
//---------------------------------------------------------------
Imath::Box2i dataWindowForLevel (int l = 0) const;
Imath::Box2i dataWindowForLevel (int lx, int ly) const;
//-------------------------------------------------------------------
// Tile pixel ranges:
//
// dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
// region of valid pixel coordinates for a tile with tile coordinates
// (dx,dy) and level number (lx, ly).
//
// return value is a Box2i with min value:
// (dataWindow.min.x + dx * tileXSize(),
// dataWindow.min.y + dy * tileYSize())
//
// and max value:
// (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
// dataWindow.min.y + (dy + 1) * tileYSize() - 1)
//
// dataWindowForTile(dx, dy, level) is a convenience function
// used for ONE_LEVEL and MIPMAP_LEVELS files. It returns
// dataWindowForTile(dx, dy, level, level).
//
//-------------------------------------------------------------------
Imath::Box2i dataWindowForTile (int dx, int dy, int l = 0) const;
Imath::Box2i dataWindowForTile (int dx, int dy,
int lx, int ly) const;
//------------------------------------------------------------
// Read pixel data:
//
// readTile(dx, dy, lx, ly) reads the tile with tile
// coordinates (dx, dy), and level number (lx, ly),
// and stores it in the current frame buffer.
//
// dx must lie in the interval [0, numXTiles(lx)-1]
// dy must lie in the interval [0, numYTiles(ly)-1]
//
// lx must lie in the interval [0, numXLevels()-1]
// ly must lie in the inverval [0, numYLevels()-1]
//
// readTile(dx, dy, level) is a convenience function used
// for ONE_LEVEL and MIPMAP_LEVELS files. It calls
// readTile(dx, dy, level, level).
//
// The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow
// reading multiple tiles at once. If multi-threading is used
// the multiple tiles are read concurrently.
//
// Pixels that are outside the pixel coordinate range for the
// tile's level, are never accessed by readTile().
//
// Attempting to access a tile that is not present in the file
// throws an InputExc exception.
//
//------------------------------------------------------------
void readTile (int dx, int dy, int l = 0);
void readTile (int dx, int dy, int lx, int ly);
void readTiles (int dx1, int dx2, int dy1, int dy2,
int lx, int ly);
void readTiles (int dx1, int dx2, int dy1, int dy2,
int l = 0);
//--------------------------------------------------
// Read a tile of raw pixel data from the file,
// without uncompressing it (this function is
// used to implement TiledOutputFile::copyPixels()).
//--------------------------------------------------
void rawTileData (int &dx, int &dy,
int &lx, int &ly,
const char *&pixelData,
int &pixelDataSize);
struct Data;
private:
friend class InputFile;
TiledInputFile (const TiledInputFile &); // not implemented
TiledInputFile & operator = (const TiledInputFile &); // not implemented
TiledInputFile (const Header &header, IStream *is, int version,
int numThreads);
void initialize ();
bool isValidTile (int dx, int dy,
int lx, int ly) const;
size_t bytesPerLineForTile (int dx, int dy,
int lx, int ly) const;
Data * _data;
};
} // namespace Imf
#endif