PBRT
/home/felix/UBC/projects/AdaptiveLightfieldSampling/pbrt_v2/src/3rdparty/openexr-1.7.0/ImfTiledInputFile.h
00001 
00002 //
00003 // Copyright (c) 2004, Industrial Light & Magic, a division of Lucas
00004 // Digital Ltd. LLC
00005 // 
00006 // All rights reserved.
00007 // 
00008 // Redistribution and use in source and binary forms, with or without
00009 // modification, are permitted provided that the following conditions are
00010 // met:
00011 // *       Redistributions of source code must retain the above copyright
00012 // notice, this list of conditions and the following disclaimer.
00013 // *       Redistributions in binary form must reproduce the above
00014 // copyright notice, this list of conditions and the following disclaimer
00015 // in the documentation and/or other materials provided with the
00016 // distribution.
00017 // *       Neither the name of Industrial Light & Magic nor the names of
00018 // its contributors may be used to endorse or promote products derived
00019 // from this software without specific prior written permission. 
00020 // 
00021 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00022 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00023 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00024 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
00025 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00026 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00027 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
00028 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
00029 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00030 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00031 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00032 //
00034 
00035 
00036 #ifndef INCLUDED_IMF_TILED_INPUT_FILE_H
00037 #define INCLUDED_IMF_TILED_INPUT_FILE_H
00038 
00039 //-----------------------------------------------------------------------------
00040 //
00041 //      class TiledInputFile
00042 //
00043 //-----------------------------------------------------------------------------
00044 
00045 #include <ImfHeader.h>
00046 #include <ImfFrameBuffer.h>
00047 #include "ImathBox.h"
00048 #include <ImfTileDescription.h>
00049 #include <ImfThreading.h>
00050 
00051 namespace Imf {
00052 
00053 
00054 class TiledInputFile
00055 {
00056   public:
00057 
00058     //--------------------------------------------------------------------
00059     // A constructor that opens the file with the specified name, and
00060     // reads the file header.  The constructor throws an Iex::ArgExc
00061     // exception if the file is not tiled.
00062     // The numThreads parameter specifies how many worker threads this
00063     // file will try to keep busy when decompressing individual tiles.
00064     // Destroying TiledInputFile objects constructed with this constructor
00065     // automatically closes the corresponding files.
00066     //--------------------------------------------------------------------
00067 
00068     TiledInputFile (const char fileName[],
00069                     int numThreads = globalThreadCount ());
00070 
00071     
00072     // ----------------------------------------------------------
00073     // A constructor that attaches the new TiledInputFile object
00074     // to a file that has already been opened.  
00075     // Destroying TiledInputFile objects constructed with this
00076     // constructor does not automatically close the corresponding
00077     // files.
00078     // ----------------------------------------------------------
00079 
00080     TiledInputFile (IStream &is, int numThreads = globalThreadCount ());
00081 
00082 
00083     //-----------
00084     // Destructor
00085     //-----------
00086 
00087     virtual ~TiledInputFile ();
00088 
00089 
00090     //------------------------
00091     // Access to the file name
00092     //------------------------
00093 
00094     const char *        fileName () const;
00095 
00096 
00097     //--------------------------
00098     // Access to the file header
00099     //--------------------------
00100 
00101     const Header &      header () const;
00102 
00103 
00104     //----------------------------------
00105     // Access to the file format version
00106     //----------------------------------
00107 
00108     int                 version () const;
00109 
00110 
00111     //-----------------------------------------------------------
00112     // Set the current frame buffer -- copies the FrameBuffer
00113     // object into the TiledInputFile object.
00114     //
00115     // The current frame buffer is the destination for the pixel
00116     // data read from the file.  The current frame buffer must be
00117     // set at least once before readTile() is called.
00118     // The current frame buffer can be changed after each call
00119     // to readTile().
00120     //-----------------------------------------------------------
00121 
00122     void                setFrameBuffer (const FrameBuffer &frameBuffer);
00123 
00124 
00125     //-----------------------------------
00126     // Access to the current frame buffer
00127     //-----------------------------------
00128 
00129     const FrameBuffer & frameBuffer () const;
00130 
00131 
00132     //------------------------------------------------------------
00133     // Check if the file is complete:
00134     //
00135     // isComplete() returns true if all pixels in the data window
00136     // (in all levels) are present in the input file, or false if
00137     // any pixels are missing.  (Another program may still be busy
00138     // writing the file, or file writing may have been aborted
00139     // prematurely.)
00140     //------------------------------------------------------------
00141 
00142     bool                isComplete () const;
00143 
00144 
00145     //--------------------------------------------------
00146     // Utility functions:
00147     //--------------------------------------------------
00148 
00149     //---------------------------------------------------------
00150     // Multiresolution mode and tile size:
00151     // The following functions return the xSize, ySize and mode
00152     // fields of the file header's TileDescriptionAttribute.
00153     //---------------------------------------------------------
00154 
00155     unsigned int        tileXSize () const;
00156     unsigned int        tileYSize () const;
00157     LevelMode           levelMode () const;
00158     LevelRoundingMode   levelRoundingMode () const;
00159 
00160 
00161     //--------------------------------------------------------------------
00162     // Number of levels:
00163     //
00164     // numXLevels() returns the file's number of levels in x direction.
00165     //
00166     //  if levelMode() == ONE_LEVEL:
00167     //      return value is: 1
00168     //
00169     //  if levelMode() == MIPMAP_LEVELS:
00170     //      return value is: rfunc (log (max (w, h)) / log (2)) + 1
00171     //
00172     //  if levelMode() == RIPMAP_LEVELS:
00173     //      return value is: rfunc (log (w) / log (2)) + 1
00174     //
00175     //  where
00176     //      w is the width of the image's data window,  max.x - min.x + 1,
00177     //      y is the height of the image's data window, max.y - min.y + 1,
00178     //      and rfunc(x) is either floor(x), or ceil(x), depending on
00179     //      whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
00180     //
00181     // numYLevels() returns the file's number of levels in y direction.
00182     //
00183     //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
00184     //      return value is the same as for numXLevels()
00185     //
00186     //  if levelMode() == RIPMAP_LEVELS:
00187     //      return value is: rfunc (log (h) / log (2)) + 1
00188     //
00189     //
00190     // numLevels() is a convenience function for use with
00191     // MIPMAP_LEVELS files.
00192     //
00193     //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
00194     //      return value is the same as for numXLevels()
00195     //
00196     //  if levelMode() == RIPMAP_LEVELS:
00197     //      an Iex::LogicExc exception is thrown
00198     //
00199     // isValidLevel(lx, ly) returns true if the file contains 
00200     // a level with level number (lx, ly), false if not.
00201     //
00202     //--------------------------------------------------------------------
00203 
00204     int                 numLevels () const;
00205     int                 numXLevels () const;
00206     int                 numYLevels () const;
00207     bool                isValidLevel (int lx, int ly) const;
00208 
00209 
00210     //----------------------------------------------------------
00211     // Dimensions of a level:
00212     //
00213     // levelWidth(lx) returns the width of a level with level
00214     // number (lx, *), where * is any number.
00215     //
00216     //  return value is:
00217     //      max (1, rfunc (w / pow (2, lx)))
00218     //
00219     //
00220     // levelHeight(ly) returns the height of a level with level
00221     // number (*, ly), where * is any number.
00222     //
00223     //  return value is:
00224     //      max (1, rfunc (h / pow (2, ly)))
00225     //
00226     //----------------------------------------------------------
00227 
00228     int                 levelWidth  (int lx) const;
00229     int                 levelHeight (int ly) const;
00230 
00231 
00232     //--------------------------------------------------------------
00233     // Number of tiles:
00234     //
00235     // numXTiles(lx) returns the number of tiles in x direction
00236     // that cover a level with level number (lx, *), where * is
00237     // any number.
00238     //
00239     //  return value is:
00240     //      (levelWidth(lx) + tileXSize() - 1) / tileXSize()
00241     //
00242     //
00243     // numYTiles(ly) returns the number of tiles in y direction
00244     // that cover a level with level number (*, ly), where * is
00245     // any number.
00246     //
00247     //  return value is:
00248     //      (levelHeight(ly) + tileXSize() - 1) / tileXSize()
00249     //
00250     //--------------------------------------------------------------
00251 
00252     int                 numXTiles (int lx = 0) const;
00253     int                 numYTiles (int ly = 0) const;
00254 
00255 
00256     //---------------------------------------------------------------
00257     // Level pixel ranges:
00258     //
00259     // dataWindowForLevel(lx, ly) returns a 2-dimensional region of
00260     // valid pixel coordinates for a level with level number (lx, ly)
00261     //
00262     //  return value is a Box2i with min value:
00263     //      (dataWindow.min.x, dataWindow.min.y)
00264     //
00265     //  and max value:
00266     //      (dataWindow.min.x + levelWidth(lx) - 1,
00267     //       dataWindow.min.y + levelHeight(ly) - 1)
00268     //
00269     // dataWindowForLevel(level) is a convenience function used
00270     // for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
00271     // dataWindowForLevel(level, level).
00272     //
00273     //---------------------------------------------------------------
00274 
00275     Imath::Box2i        dataWindowForLevel (int l = 0) const;
00276     Imath::Box2i        dataWindowForLevel (int lx, int ly) const;
00277 
00278 
00279     //-------------------------------------------------------------------
00280     // Tile pixel ranges:
00281     //
00282     // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
00283     // region of valid pixel coordinates for a tile with tile coordinates
00284     // (dx,dy) and level number (lx, ly).
00285     //
00286     //  return value is a Box2i with min value:
00287     //      (dataWindow.min.x + dx * tileXSize(),
00288     //       dataWindow.min.y + dy * tileYSize())
00289     //
00290     //  and max value:
00291     //      (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
00292     //       dataWindow.min.y + (dy + 1) * tileYSize() - 1)
00293     //
00294     // dataWindowForTile(dx, dy, level) is a convenience function
00295     // used for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
00296     // dataWindowForTile(dx, dy, level, level).
00297     //
00298     //-------------------------------------------------------------------
00299 
00300     Imath::Box2i        dataWindowForTile (int dx, int dy, int l = 0) const;
00301 
00302     Imath::Box2i        dataWindowForTile (int dx, int dy,
00303                                            int lx, int ly) const;
00304 
00305     //------------------------------------------------------------
00306     // Read pixel data:
00307     //
00308     // readTile(dx, dy, lx, ly) reads the tile with tile
00309     // coordinates (dx, dy), and level number (lx, ly),
00310     // and stores it in the current frame buffer.
00311     //
00312     //   dx must lie in the interval [0, numXTiles(lx)-1]
00313     //   dy must lie in the interval [0, numYTiles(ly)-1]
00314     //
00315     //   lx must lie in the interval [0, numXLevels()-1]
00316     //   ly must lie in the inverval [0, numYLevels()-1]
00317     //
00318     // readTile(dx, dy, level) is a convenience function used
00319     // for ONE_LEVEL and MIPMAP_LEVELS files.  It calls
00320     // readTile(dx, dy, level, level).
00321     //
00322     // The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow
00323     // reading multiple tiles at once.  If multi-threading is used
00324     // the multiple tiles are read concurrently.
00325     //
00326     // Pixels that are outside the pixel coordinate range for the
00327     // tile's level, are never accessed by readTile().
00328     //
00329     // Attempting to access a tile that is not present in the file
00330     // throws an InputExc exception.
00331     //
00332     //------------------------------------------------------------
00333 
00334     void                readTile  (int dx, int dy, int l = 0);
00335     void                readTile  (int dx, int dy, int lx, int ly);
00336 
00337     void                readTiles (int dx1, int dx2, int dy1, int dy2,
00338                                    int lx, int ly);
00339 
00340     void                readTiles (int dx1, int dx2, int dy1, int dy2,
00341                                    int l = 0);
00342 
00343 
00344     //--------------------------------------------------
00345     // Read a tile of raw pixel data from the file,
00346     // without uncompressing it (this function is
00347     // used to implement TiledOutputFile::copyPixels()).
00348     //--------------------------------------------------
00349 
00350     void                rawTileData (int &dx, int &dy,
00351                                      int &lx, int &ly,
00352                                      const char *&pixelData,
00353                                      int &pixelDataSize);
00354 
00355     struct Data;
00356 
00357   private:
00358 
00359     friend class InputFile;
00360 
00361     TiledInputFile (const TiledInputFile &);              // not implemented
00362     TiledInputFile & operator = (const TiledInputFile &); // not implemented
00363 
00364     TiledInputFile (const Header &header, IStream *is, int version,
00365                     int numThreads);
00366 
00367     void                initialize ();
00368 
00369     bool                isValidTile (int dx, int dy,
00370                                      int lx, int ly) const;
00371 
00372     size_t              bytesPerLineForTile (int dx, int dy,
00373                                              int lx, int ly) const;
00374 
00375     Data *              _data;
00376 };
00377 
00378 
00379 } // namespace Imf
00380 
00381 #endif