+++ /dev/null
-///////////////////////////////////////////////////////////////////////////
-//
-// 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_OUTPUT_FILE_H
-#define INCLUDED_IMF_TILED_OUTPUT_FILE_H
-
-//-----------------------------------------------------------------------------
-//
-// class TiledOutputFile
-//
-//-----------------------------------------------------------------------------
-
-#include <ImfHeader.h>
-#include <ImfFrameBuffer.h>
-#include "ImathBox.h"
-#include <ImfTileDescription.h>
-#include <ImfThreading.h>
-
-namespace Imf {
-
-class TiledInputFile;
-class InputFile;
-struct PreviewRgba;
-
-
-class TiledOutputFile
-{
- public:
-
- //-------------------------------------------------------------------
- // A constructor that opens the file with the specified name, and
- // writes the file header. The file header is also copied into the
- // TiledOutputFile object, and can later be accessed via the header()
- // method.
- //
- // Destroying TiledOutputFile constructed with this constructor
- // automatically closes the corresponding files.
- //
- // The header must contain a TileDescriptionAttribute called "tiles".
- //
- // The x and y subsampling factors for all image channels must be 1;
- // subsampling is not supported.
- //
- // Tiles can be written to the file in arbitrary order. The line
- // order attribute can be used to cause the tiles to be sorted in
- // the file. When the file is read later, reading the tiles in the
- // same order as they are in the file tends to be significantly
- // faster than reading the tiles in random order (see writeTile,
- // below).
- //-------------------------------------------------------------------
-
- TiledOutputFile (const char fileName[],
- const Header &header,
- int numThreads = globalThreadCount ());
-
-
- // ----------------------------------------------------------------
- // A constructor that attaches the new TiledOutputFile object to
- // a file that has already been opened. Destroying TiledOutputFile
- // objects constructed with this constructor does not automatically
- // close the corresponding files.
- // ----------------------------------------------------------------
-
- TiledOutputFile (OStream &os,
- const Header &header,
- int numThreads = globalThreadCount ());
-
-
- //-----------------------------------------------------
- // Destructor
- //
- // Destroying a TiledOutputFile object before all tiles
- // have been written results in an incomplete file.
- //-----------------------------------------------------
-
- virtual ~TiledOutputFile ();
-
-
- //------------------------
- // Access to the file name
- //------------------------
-
- const char * fileName () const;
-
-
- //--------------------------
- // Access to the file header
- //--------------------------
-
- const Header & header () const;
-
-
- //-------------------------------------------------------
- // Set the current frame buffer -- copies the FrameBuffer
- // object into the TiledOutputFile object.
- //
- // The current frame buffer is the source of the pixel
- // data written to the file. The current frame buffer
- // must be set at least once before writeTile() is
- // called. The current frame buffer can be changed
- // after each call to writeTile().
- //-------------------------------------------------------
-
- void setFrameBuffer (const FrameBuffer &frameBuffer);
-
-
- //-----------------------------------
- // Access to the current frame buffer
- //-----------------------------------
-
- const FrameBuffer & frameBuffer () 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;
-
- //------------------------------------------------------------------
- // Write pixel data:
- //
- // writeTile(dx, dy, lx, ly) writes the tile with tile
- // coordinates (dx, dy), and level number (lx, ly) to
- // the file.
- //
- // 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]
- //
- // writeTile(dx, dy, level) is a convenience function
- // used for ONE_LEVEL and MIPMAP_LEVEL files. It calls
- // writeTile(dx, dy, level, level).
- //
- // The two writeTiles(dx1, dx2, dy1, dy2, ...) functions allow
- // writing multiple tiles at once. If multi-threading is used
- // multiple tiles are written concurrently. The tile coordinates,
- // dx1, dx2 and dy1, dy2, specify inclusive ranges of tile
- // coordinates. It is valid for dx1 < dx2 or dy1 < dy2; the
- // tiles are always written in the order specified by the line
- // order attribute. Hence, it is not possible to specify an
- // "invalid" or empty tile range.
- //
- // Pixels that are outside the pixel coordinate range for the tile's
- // level, are never accessed by writeTile().
- //
- // Each tile in the file must be written exactly once.
- //
- // The file's line order attribute determines the order of the tiles
- // in the file:
- //
- // INCREASING_Y In the file, the tiles for each level are stored
- // in a contiguous block. The levels are ordered
- // like this:
- //
- // (0, 0) (1, 0) ... (nx-1, 0)
- // (0, 1) (1, 1) ... (nx-1, 1)
- // ...
- // (0,ny-1) (1,ny-1) ... (nx-1,ny-1)
- //
- // where nx = numXLevels(), and ny = numYLevels().
- // In an individual level, (lx, ly), the tiles
- // are stored in the following order:
- //
- // (0, 0) (1, 0) ... (tx-1, 0)
- // (0, 1) (1, 1) ... (tx-1, 1)
- // ...
- // (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
- //
- // where tx = numXTiles(lx),
- // and ty = numYTiles(ly).
- //
- // DECREASING_Y As for INCREASING_Y, the tiles for each level
- // are stored in a contiguous block. The levels
- // are ordered the same way as for INCREASING_Y,
- // but within an individual level, the tiles
- // are stored in this order:
- //
- // (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
- // ...
- // (0, 1) (1, 1) ... (tx-1, 1)
- // (0, 0) (1, 0) ... (tx-1, 0)
- //
- //
- // RANDOM_Y The order of the calls to writeTile() determines
- // the order of the tiles in the file.
- //
- //------------------------------------------------------------------
-
- void writeTile (int dx, int dy, int l = 0);
- void writeTile (int dx, int dy, int lx, int ly);
-
- void writeTiles (int dx1, int dx2, int dy1, int dy2,
- int lx, int ly);
-
- void writeTiles (int dx1, int dx2, int dy1, int dy2,
- int l = 0);
-
-
- //------------------------------------------------------------------
- // Shortcut to copy all pixels from a TiledInputFile into this file,
- // without uncompressing and then recompressing the pixel data.
- // This file's header must be compatible with the TiledInputFile's
- // header: The two header's "dataWindow", "compression",
- // "lineOrder", "channels", and "tiles" attributes must be the same.
- //------------------------------------------------------------------
-
- void copyPixels (TiledInputFile &in);
-
-
- //------------------------------------------------------------------
- // Shortcut to copy all pixels from an InputFile into this file,
- // without uncompressing and then recompressing the pixel data.
- // This file's header must be compatible with the InputFile's
- // header: The two header's "dataWindow", "compression",
- // "lineOrder", "channels", and "tiles" attributes must be the same.
- //
- // To use this function, the InputFile must be tiled.
- //------------------------------------------------------------------
-
- void copyPixels (InputFile &in);
-
-
- //--------------------------------------------------------------
- // Updating the preview image:
- //
- // updatePreviewImage() supplies a new set of pixels for the
- // preview image attribute in the file's header. If the header
- // does not contain a preview image, updatePreviewImage() throws
- // an Iex::LogicExc.
- //
- // Note: updatePreviewImage() is necessary because images are
- // often stored in a file incrementally, a few tiles at a time,
- // while the image is being generated. Since the preview image
- // is an attribute in the file's header, it gets stored in the
- // file as soon as the file is opened, but we may not know what
- // the preview image should look like until we have written the
- // last tile of the main image.
- //
- //--------------------------------------------------------------
-
- void updatePreviewImage (const PreviewRgba newPixels[]);
-
-
- //-------------------------------------------------------------
- // Break a tile -- for testing and debugging only:
- //
- // breakTile(dx,dy,lx,ly,p,n,c) introduces an error into the
- // output file by writing n copies of character c, starting
- // p bytes from the beginning of the tile with tile coordinates
- // (dx, dy) and level number (lx, ly).
- //
- // Warning: Calling this function usually results in a broken
- // image file. The file or parts of it may not be readable,
- // or the file may contain bad data.
- //
- //-------------------------------------------------------------
-
- void breakTile (int dx, int dy,
- int lx, int ly,
- int offset,
- int length,
- char c);
- struct Data;
-
- private:
-
- TiledOutputFile (const TiledOutputFile &); // not implemented
- TiledOutputFile & operator = (const TiledOutputFile &); // not implemented
-
- void initialize (const Header &header);
-
- 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