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