PBRT
/home/felix/UBC/projects/AdaptiveLightfieldSampling/pbrt_v2/src/3rdparty/openexr-1.7.0/ImfTiledOutputFile.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_OUTPUT_FILE_H
00037 #define INCLUDED_IMF_TILED_OUTPUT_FILE_H
00038 
00039 //-----------------------------------------------------------------------------
00040 //
00041 //      class TiledOutputFile
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 class TiledInputFile;
00054 class InputFile;
00055 struct PreviewRgba;
00056 
00057 
00058 class TiledOutputFile
00059 {
00060   public:
00061 
00062     //-------------------------------------------------------------------
00063     // A constructor that opens the file with the specified name, and
00064     // writes the file header.  The file header is also copied into the
00065     // TiledOutputFile object, and can later be accessed via the header()
00066     // method.
00067     //
00068     // Destroying TiledOutputFile constructed with this constructor
00069     // automatically closes the corresponding files.
00070     //
00071     // The header must contain a TileDescriptionAttribute called "tiles".
00072     //
00073     // The x and y subsampling factors for all image channels must be 1;
00074     // subsampling is not supported.
00075     //
00076     // Tiles can be written to the file in arbitrary order.  The line
00077     // order attribute can be used to cause the tiles to be sorted in
00078     // the file.  When the file is read later, reading the tiles in the
00079     // same order as they are in the file tends to be significantly
00080     // faster than reading the tiles in random order (see writeTile,
00081     // below).
00082     //-------------------------------------------------------------------
00083     
00084     TiledOutputFile (const char fileName[],
00085                      const Header &header,
00086                      int numThreads = globalThreadCount ());
00087 
00088 
00089     // ----------------------------------------------------------------
00090     // A constructor that attaches the new TiledOutputFile object to
00091     // a file that has already been opened.  Destroying TiledOutputFile
00092     // objects constructed with this constructor does not automatically
00093     // close the corresponding files.
00094     // ----------------------------------------------------------------
00095 
00096     TiledOutputFile (OStream &os,
00097                      const Header &header,
00098                      int numThreads = globalThreadCount ());
00099 
00100 
00101     //-----------------------------------------------------
00102     // Destructor
00103     //
00104     // Destroying a TiledOutputFile object before all tiles
00105     // have been written results in an incomplete file.
00106     //-----------------------------------------------------
00107     
00108     virtual ~TiledOutputFile ();
00109 
00110 
00111     //------------------------
00112     // Access to the file name
00113     //------------------------
00114     
00115     const char *        fileName () const;
00116 
00117 
00118     //--------------------------
00119     // Access to the file header
00120     //--------------------------
00121     
00122     const Header &      header () const;
00123 
00124 
00125     //-------------------------------------------------------
00126     // Set the current frame buffer -- copies the FrameBuffer
00127     // object into the TiledOutputFile object.
00128     //
00129     // The current frame buffer is the source of the pixel
00130     // data written to the file.  The current frame buffer
00131     // must be set at least once before writeTile() is
00132     // called.  The current frame buffer can be changed
00133     // after each call to writeTile().
00134     //-------------------------------------------------------
00135     
00136     void                setFrameBuffer (const FrameBuffer &frameBuffer);
00137 
00138 
00139     //-----------------------------------
00140     // Access to the current frame buffer
00141     //-----------------------------------
00142     
00143     const FrameBuffer & frameBuffer () const;
00144 
00145 
00146     //-------------------
00147     // Utility functions:
00148     //-------------------
00149 
00150     //---------------------------------------------------------
00151     // Multiresolution mode and tile size:
00152     // The following functions return the xSize, ySize and mode
00153     // fields of the file header's TileDescriptionAttribute.
00154     //---------------------------------------------------------
00155 
00156     unsigned int        tileXSize () const;
00157     unsigned int        tileYSize () const;
00158     LevelMode           levelMode () const;
00159     LevelRoundingMode   levelRoundingMode () const;
00160 
00161 
00162     //--------------------------------------------------------------------
00163     // Number of levels:
00164     //
00165     // numXLevels() returns the file's number of levels in x direction.
00166     //
00167     //  if levelMode() == ONE_LEVEL:
00168     //      return value is: 1
00169     //
00170     //  if levelMode() == MIPMAP_LEVELS:
00171     //      return value is: rfunc (log (max (w, h)) / log (2)) + 1
00172     //
00173     //  if levelMode() == RIPMAP_LEVELS:
00174     //      return value is: rfunc (log (w) / log (2)) + 1
00175     //
00176     //  where
00177     //      w is the width of the image's data window,  max.x - min.x + 1,
00178     //      y is the height of the image's data window, max.y - min.y + 1,
00179     //      and rfunc(x) is either floor(x), or ceil(x), depending on
00180     //      whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
00181     //
00182     // numYLevels() returns the file's number of levels in y direction.
00183     //
00184     //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
00185     //      return value is the same as for numXLevels()
00186     //
00187     //  if levelMode() == RIPMAP_LEVELS:
00188     //      return value is: rfunc (log (h) / log (2)) + 1
00189     //
00190     //
00191     // numLevels() is a convenience function for use with MIPMAP_LEVELS
00192     // files.
00193     //
00194     //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
00195     //      return value is the same as for numXLevels()
00196     //
00197     //  if levelMode() == RIPMAP_LEVELS:
00198     //      an Iex::LogicExc exception is thrown
00199     //
00200     // isValidLevel(lx, ly) returns true if the file contains 
00201     // a level with level number (lx, ly), false if not.
00202     //
00203     //--------------------------------------------------------------------
00204 
00205     int                 numLevels () const;
00206     int                 numXLevels () const;
00207     int                 numYLevels () const;
00208     bool                isValidLevel (int lx, int ly) const;
00209 
00210 
00211     //---------------------------------------------------------
00212     // Dimensions of a level:
00213     //
00214     // levelWidth(lx) returns the width of a level with level
00215     // number (lx, *), where * is any number.
00216     //
00217     //  return value is:
00218     //      max (1, rfunc (w / pow (2, lx)))
00219     //
00220     //
00221     // levelHeight(ly) returns the height of a level with level
00222     // number (*, ly), where * is any number.
00223     //
00224     //  return value is:
00225     //      max (1, rfunc (h / pow (2, ly)))
00226     //
00227     //---------------------------------------------------------
00228 
00229     int                 levelWidth  (int lx) const;
00230     int                 levelHeight (int ly) const;
00231 
00232 
00233     //----------------------------------------------------------
00234     // Number of tiles:
00235     //
00236     // numXTiles(lx) returns the number of tiles in x direction
00237     // that cover a level with level number (lx, *), where * is
00238     // any number.
00239     //
00240     //  return value is:
00241     //      (levelWidth(lx) + tileXSize() - 1) / tileXSize()
00242     //
00243     //
00244     // numYTiles(ly) returns the number of tiles in y direction
00245     // that cover a level with level number (*, ly), where * is
00246     // any number.
00247     //
00248     //  return value is:
00249     //      (levelHeight(ly) + tileXSize() - 1) / tileXSize()
00250     //
00251     //----------------------------------------------------------
00252 
00253     int                 numXTiles (int lx = 0) const;
00254     int                 numYTiles (int ly = 0) const;
00255 
00256 
00257     //---------------------------------------------------------
00258     // Level pixel ranges:
00259     //
00260     // dataWindowForLevel(lx, ly) returns a 2-dimensional
00261     // region of valid pixel coordinates for a level with
00262     // level number (lx, ly)
00263     //
00264     //  return value is a Box2i with min value:
00265     //      (dataWindow.min.x, dataWindow.min.y)
00266     //
00267     //  and max value:
00268     //      (dataWindow.min.x + levelWidth(lx) - 1,
00269     //       dataWindow.min.y + levelHeight(ly) - 1)
00270     //
00271     // dataWindowForLevel(level) is a convenience function used
00272     // for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
00273     // dataWindowForLevel(level, level).
00274     //
00275     //---------------------------------------------------------
00276 
00277     Imath::Box2i        dataWindowForLevel (int l = 0) const;
00278     Imath::Box2i        dataWindowForLevel (int lx, int ly) const;
00279 
00280 
00281     //-------------------------------------------------------------------
00282     // Tile pixel ranges:
00283     //
00284     // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
00285     // region of valid pixel coordinates for a tile with tile coordinates
00286     // (dx,dy) and level number (lx, ly).
00287     //
00288     //  return value is a Box2i with min value:
00289     //      (dataWindow.min.x + dx * tileXSize(),
00290     //       dataWindow.min.y + dy * tileYSize())
00291     //
00292     //  and max value:
00293     //      (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
00294     //       dataWindow.min.y + (dy + 1) * tileYSize() - 1)
00295     //
00296     // dataWindowForTile(dx, dy, level) is a convenience function
00297     // used for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
00298     // dataWindowForTile(dx, dy, level, level).
00299     //
00300     //-------------------------------------------------------------------
00301 
00302     Imath::Box2i        dataWindowForTile (int dx, int dy,
00303                                            int l = 0) const;
00304 
00305     Imath::Box2i        dataWindowForTile (int dx, int dy,
00306                                            int lx, int ly) const;
00307 
00308     //------------------------------------------------------------------
00309     // Write pixel data:
00310     //
00311     // writeTile(dx, dy, lx, ly) writes the tile with tile
00312     // coordinates (dx, dy), and level number (lx, ly) to
00313     // the file.
00314     //
00315     //   dx must lie in the interval [0, numXTiles(lx) - 1]
00316     //   dy must lie in the interval [0, numYTiles(ly) - 1]
00317     //
00318     //   lx must lie in the interval [0, numXLevels() - 1]
00319     //   ly must lie in the inverval [0, numYLevels() - 1]
00320     //
00321     // writeTile(dx, dy, level) is a convenience function
00322     // used for ONE_LEVEL and MIPMAP_LEVEL files.  It calls
00323     // writeTile(dx, dy, level, level).
00324     //
00325     // The two writeTiles(dx1, dx2, dy1, dy2, ...) functions allow
00326     // writing multiple tiles at once.  If multi-threading is used
00327     // multiple tiles are written concurrently.  The tile coordinates,
00328     // dx1, dx2 and dy1, dy2, specify inclusive ranges of tile
00329     // coordinates.  It is valid for dx1 < dx2 or dy1 < dy2; the
00330     // tiles are always written in the order specified by the line
00331     // order attribute.  Hence, it is not possible to specify an
00332     // "invalid" or empty tile range.
00333     //
00334     // Pixels that are outside the pixel coordinate range for the tile's
00335     // level, are never accessed by writeTile().
00336     //
00337     // Each tile in the file must be written exactly once.
00338     //
00339     // The file's line order attribute determines the order of the tiles
00340     // in the file:
00341     //
00342     //   INCREASING_Y   In the file, the tiles for each level are stored
00343     //                  in a contiguous block.  The levels are ordered
00344     //                  like this:
00345     //
00346     //                      (0, 0)   (1, 0)   ... (nx-1, 0) 
00347     //                      (0, 1)   (1, 1)   ... (nx-1, 1) 
00348     //                       ...
00349     //                      (0,ny-1) (1,ny-1) ... (nx-1,ny-1) 
00350     //
00351     //                  where nx = numXLevels(), and ny = numYLevels().
00352     //                  In an individual level, (lx, ly), the tiles
00353     //                  are stored in the following order:
00354     //
00355     //                      (0, 0)   (1, 0)   ... (tx-1, 0)
00356     //                      (0, 1)   (1, 1)   ... (tx-1, 1)
00357     //                       ...
00358     //                      (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
00359     //
00360     //                  where tx = numXTiles(lx),
00361     //                  and   ty = numYTiles(ly).
00362     //
00363     //   DECREASING_Y   As for INCREASING_Y, the tiles for each level
00364     //                  are stored in a contiguous block.  The levels
00365     //                  are ordered the same way as for INCREASING_Y,
00366     //                  but within an individual level, the tiles
00367     //                  are stored in this order:
00368     //
00369     //                      (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
00370     //                       ...
00371     //                      (0, 1)   (1, 1)   ... (tx-1, 1)
00372     //                      (0, 0)   (1, 0)   ... (tx-1, 0)
00373     //
00374     //
00375     //   RANDOM_Y       The order of the calls to writeTile() determines
00376     //                  the order of the tiles in the file.
00377     //
00378     //------------------------------------------------------------------
00379 
00380     void                writeTile  (int dx, int dy, int l = 0);
00381     void                writeTile  (int dx, int dy, int lx, int ly);
00382 
00383     void                writeTiles (int dx1, int dx2, int dy1, int dy2,
00384                                     int lx, int ly);
00385 
00386     void                writeTiles (int dx1, int dx2, int dy1, int dy2,
00387                                     int l = 0);
00388 
00389 
00390     //------------------------------------------------------------------
00391     // Shortcut to copy all pixels from a TiledInputFile into this file,
00392     // without uncompressing and then recompressing the pixel data.
00393     // This file's header must be compatible with the TiledInputFile's
00394     // header:  The two header's "dataWindow", "compression",
00395     // "lineOrder", "channels", and "tiles" attributes must be the same.
00396     //------------------------------------------------------------------
00397     
00398     void                copyPixels (TiledInputFile &in);
00399     
00400 
00401     //------------------------------------------------------------------
00402     // Shortcut to copy all pixels from an InputFile into this file,
00403     // without uncompressing and then recompressing the pixel data.
00404     // This file's header must be compatible with the InputFile's
00405     // header:  The two header's "dataWindow", "compression",
00406     // "lineOrder", "channels", and "tiles" attributes must be the same.
00407     //
00408     // To use this function, the InputFile must be tiled.
00409     //------------------------------------------------------------------
00410     
00411     void                copyPixels (InputFile &in);
00412 
00413 
00414     //--------------------------------------------------------------
00415     // Updating the preview image:
00416     //
00417     // updatePreviewImage() supplies a new set of pixels for the
00418     // preview image attribute in the file's header.  If the header
00419     // does not contain a preview image, updatePreviewImage() throws
00420     // an Iex::LogicExc.
00421     //
00422     // Note: updatePreviewImage() is necessary because images are
00423     // often stored in a file incrementally, a few tiles at a time,
00424     // while the image is being generated.  Since the preview image
00425     // is an attribute in the file's header, it gets stored in the
00426     // file as soon as the file is opened, but we may not know what
00427     // the preview image should look like until we have written the
00428     // last tile of the main image.
00429     //
00430     //--------------------------------------------------------------
00431 
00432     void                updatePreviewImage (const PreviewRgba newPixels[]);
00433 
00434 
00435     //-------------------------------------------------------------
00436     // Break a tile -- for testing and debugging only:
00437     // 
00438     // breakTile(dx,dy,lx,ly,p,n,c) introduces an error into the
00439     // output file by writing n copies of character c, starting
00440     // p bytes from the beginning of the tile with tile coordinates
00441     // (dx, dy) and level number (lx, ly).
00442     //
00443     // Warning: Calling this function usually results in a broken
00444     // image file.  The file or parts of it may not be readable,
00445     // or the file may contain bad data.
00446     //
00447     //-------------------------------------------------------------
00448 
00449     void                breakTile  (int dx, int dy,
00450                                     int lx, int ly,
00451                                     int offset,
00452                                     int length,
00453                                     char c);
00454     struct Data;
00455 
00456   private:
00457 
00458     TiledOutputFile (const TiledOutputFile &);              // not implemented
00459     TiledOutputFile & operator = (const TiledOutputFile &); // not implemented
00460 
00461     void                initialize (const Header &header);
00462 
00463     bool                isValidTile (int dx, int dy,
00464                                      int lx, int ly) const;
00465 
00466     size_t              bytesPerLineForTile (int dx, int dy,
00467                                              int lx, int ly) const;
00468 
00469     Data *              _data;
00470 };
00471 
00472 
00473 } // namespace Imf
00474 
00475 #endif