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