1 /////////////////////////////////////////////////////////////////////////// 2 // 3 // Copyright (c) 2004, Industrial Light & Magic, a division of Lucas 4 // Digital Ltd. LLC 5 // 6 // All rights reserved. 7 // 8 // Redistribution and use in source and binary forms, with or without 9 // modification, are permitted provided that the following conditions are 10 // met: 11 // * Redistributions of source code must retain the above copyright 12 // notice, this list of conditions and the following disclaimer. 13 // * Redistributions in binary form must reproduce the above 14 // copyright notice, this list of conditions and the following disclaimer 15 // in the documentation and/or other materials provided with the 16 // distribution. 17 // * Neither the name of Industrial Light & Magic nor the names of 18 // its contributors may be used to endorse or promote products derived 19 // from this software without specific prior written permission. 20 // 21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 // 33 /////////////////////////////////////////////////////////////////////////// 34 35 36 #ifndef INCLUDED_IMF_TILED_INPUT_FILE_H 37 #define INCLUDED_IMF_TILED_INPUT_FILE_H 38 39 //----------------------------------------------------------------------------- 40 // 41 // class TiledInputFile 42 // 43 //----------------------------------------------------------------------------- 44 45 #include <ImfHeader.h> 46 #include <ImfFrameBuffer.h> 47 #include "ImathBox.h" 48 #include <ImfTileDescription.h> 49 #include <ImfThreading.h> 50 51 namespace Imf { 52 53 54 class TiledInputFile 55 { 56 public: 57 58 //-------------------------------------------------------------------- 59 // A constructor that opens the file with the specified name, and 60 // reads the file header. The constructor throws an Iex::ArgExc 61 // exception if the file is not tiled. 62 // The numThreads parameter specifies how many worker threads this 63 // file will try to keep busy when decompressing individual tiles. 64 // Destroying TiledInputFile objects constructed with this constructor 65 // automatically closes the corresponding files. 66 //-------------------------------------------------------------------- 67 68 TiledInputFile (const char fileName[], 69 int numThreads = globalThreadCount ()); 70 71 72 // ---------------------------------------------------------- 73 // A constructor that attaches the new TiledInputFile object 74 // to a file that has already been opened. 75 // Destroying TiledInputFile objects constructed with this 76 // constructor does not automatically close the corresponding 77 // files. 78 // ---------------------------------------------------------- 79 80 TiledInputFile (IStream &is, int numThreads = globalThreadCount ()); 81 82 83 //----------- 84 // Destructor 85 //----------- 86 87 virtual ~TiledInputFile (); 88 89 90 //------------------------ 91 // Access to the file name 92 //------------------------ 93 94 const char * fileName () const; 95 96 97 //-------------------------- 98 // Access to the file header 99 //-------------------------- 100 101 const Header & header () const; 102 103 104 //---------------------------------- 105 // Access to the file format version 106 //---------------------------------- 107 108 int version () const; 109 110 111 //----------------------------------------------------------- 112 // Set the current frame buffer -- copies the FrameBuffer 113 // object into the TiledInputFile object. 114 // 115 // The current frame buffer is the destination for the pixel 116 // data read from the file. The current frame buffer must be 117 // set at least once before readTile() is called. 118 // The current frame buffer can be changed after each call 119 // to readTile(). 120 //----------------------------------------------------------- 121 122 void setFrameBuffer (const FrameBuffer &frameBuffer); 123 124 125 //----------------------------------- 126 // Access to the current frame buffer 127 //----------------------------------- 128 129 const FrameBuffer & frameBuffer () const; 130 131 132 //------------------------------------------------------------ 133 // Check if the file is complete: 134 // 135 // isComplete() returns true if all pixels in the data window 136 // (in all levels) are present in the input file, or false if 137 // any pixels are missing. (Another program may still be busy 138 // writing the file, or file writing may have been aborted 139 // prematurely.) 140 //------------------------------------------------------------ 141 142 bool isComplete () const; 143 144 145 //-------------------------------------------------- 146 // Utility functions: 147 //-------------------------------------------------- 148 149 //--------------------------------------------------------- 150 // Multiresolution mode and tile size: 151 // The following functions return the xSize, ySize and mode 152 // fields of the file header's TileDescriptionAttribute. 153 //--------------------------------------------------------- 154 155 unsigned int tileXSize () const; 156 unsigned int tileYSize () const; 157 LevelMode levelMode () const; 158 LevelRoundingMode levelRoundingMode () const; 159 160 161 //-------------------------------------------------------------------- 162 // Number of levels: 163 // 164 // numXLevels() returns the file's number of levels in x direction. 165 // 166 // if levelMode() == ONE_LEVEL: 167 // return value is: 1 168 // 169 // if levelMode() == MIPMAP_LEVELS: 170 // return value is: rfunc (log (max (w, h)) / log (2)) + 1 171 // 172 // if levelMode() == RIPMAP_LEVELS: 173 // return value is: rfunc (log (w) / log (2)) + 1 174 // 175 // where 176 // w is the width of the image's data window, max.x - min.x + 1, 177 // y is the height of the image's data window, max.y - min.y + 1, 178 // and rfunc(x) is either floor(x), or ceil(x), depending on 179 // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP. 180 // 181 // numYLevels() returns the file's number of levels in y direction. 182 // 183 // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS: 184 // return value is the same as for numXLevels() 185 // 186 // if levelMode() == RIPMAP_LEVELS: 187 // return value is: rfunc (log (h) / log (2)) + 1 188 // 189 // 190 // numLevels() is a convenience function for use with 191 // MIPMAP_LEVELS files. 192 // 193 // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS: 194 // return value is the same as for numXLevels() 195 // 196 // if levelMode() == RIPMAP_LEVELS: 197 // an Iex::LogicExc exception is thrown 198 // 199 // isValidLevel(lx, ly) returns true if the file contains 200 // a level with level number (lx, ly), false if not. 201 // 202 //-------------------------------------------------------------------- 203 204 int numLevels () const; 205 int numXLevels () const; 206 int numYLevels () const; 207 bool isValidLevel (int lx, int ly) const; 208 209 210 //---------------------------------------------------------- 211 // Dimensions of a level: 212 // 213 // levelWidth(lx) returns the width of a level with level 214 // number (lx, *), where * is any number. 215 // 216 // return value is: 217 // max (1, rfunc (w / pow (2, lx))) 218 // 219 // 220 // levelHeight(ly) returns the height of a level with level 221 // number (*, ly), where * is any number. 222 // 223 // return value is: 224 // max (1, rfunc (h / pow (2, ly))) 225 // 226 //---------------------------------------------------------- 227 228 int levelWidth (int lx) const; 229 int levelHeight (int ly) const; 230 231 232 //-------------------------------------------------------------- 233 // Number of tiles: 234 // 235 // numXTiles(lx) returns the number of tiles in x direction 236 // that cover a level with level number (lx, *), where * is 237 // any number. 238 // 239 // return value is: 240 // (levelWidth(lx) + tileXSize() - 1) / tileXSize() 241 // 242 // 243 // numYTiles(ly) returns the number of tiles in y direction 244 // that cover a level with level number (*, ly), where * is 245 // any number. 246 // 247 // return value is: 248 // (levelHeight(ly) + tileXSize() - 1) / tileXSize() 249 // 250 //-------------------------------------------------------------- 251 252 int numXTiles (int lx = 0) const; 253 int numYTiles (int ly = 0) const; 254 255 256 //--------------------------------------------------------------- 257 // Level pixel ranges: 258 // 259 // dataWindowForLevel(lx, ly) returns a 2-dimensional region of 260 // valid pixel coordinates for a level with level number (lx, ly) 261 // 262 // return value is a Box2i with min value: 263 // (dataWindow.min.x, dataWindow.min.y) 264 // 265 // and max value: 266 // (dataWindow.min.x + levelWidth(lx) - 1, 267 // dataWindow.min.y + levelHeight(ly) - 1) 268 // 269 // dataWindowForLevel(level) is a convenience function used 270 // for ONE_LEVEL and MIPMAP_LEVELS files. It returns 271 // dataWindowForLevel(level, level). 272 // 273 //--------------------------------------------------------------- 274 275 Imath::Box2i dataWindowForLevel (int l = 0) const; 276 Imath::Box2i dataWindowForLevel (int lx, int ly) const; 277 278 279 //------------------------------------------------------------------- 280 // Tile pixel ranges: 281 // 282 // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional 283 // region of valid pixel coordinates for a tile with tile coordinates 284 // (dx,dy) and level number (lx, ly). 285 // 286 // return value is a Box2i with min value: 287 // (dataWindow.min.x + dx * tileXSize(), 288 // dataWindow.min.y + dy * tileYSize()) 289 // 290 // and max value: 291 // (dataWindow.min.x + (dx + 1) * tileXSize() - 1, 292 // dataWindow.min.y + (dy + 1) * tileYSize() - 1) 293 // 294 // dataWindowForTile(dx, dy, level) is a convenience function 295 // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns 296 // dataWindowForTile(dx, dy, level, level). 297 // 298 //------------------------------------------------------------------- 299 300 Imath::Box2i dataWindowForTile (int dx, int dy, int l = 0) const; 301 302 Imath::Box2i dataWindowForTile (int dx, int dy, 303 int lx, int ly) const; 304 305 //------------------------------------------------------------ 306 // Read pixel data: 307 // 308 // readTile(dx, dy, lx, ly) reads the tile with tile 309 // coordinates (dx, dy), and level number (lx, ly), 310 // and stores it in the current frame buffer. 311 // 312 // dx must lie in the interval [0, numXTiles(lx)-1] 313 // dy must lie in the interval [0, numYTiles(ly)-1] 314 // 315 // lx must lie in the interval [0, numXLevels()-1] 316 // ly must lie in the inverval [0, numYLevels()-1] 317 // 318 // readTile(dx, dy, level) is a convenience function used 319 // for ONE_LEVEL and MIPMAP_LEVELS files. It calls 320 // readTile(dx, dy, level, level). 321 // 322 // The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow 323 // reading multiple tiles at once. If multi-threading is used 324 // the multiple tiles are read concurrently. 325 // 326 // Pixels that are outside the pixel coordinate range for the 327 // tile's level, are never accessed by readTile(). 328 // 329 // Attempting to access a tile that is not present in the file 330 // throws an InputExc exception. 331 // 332 //------------------------------------------------------------ 333 334 void readTile (int dx, int dy, int l = 0); 335 void readTile (int dx, int dy, int lx, int ly); 336 337 void readTiles (int dx1, int dx2, int dy1, int dy2, 338 int lx, int ly); 339 340 void readTiles (int dx1, int dx2, int dy1, int dy2, 341 int l = 0); 342 343 344 //-------------------------------------------------- 345 // Read a tile of raw pixel data from the file, 346 // without uncompressing it (this function is 347 // used to implement TiledOutputFile::copyPixels()). 348 //-------------------------------------------------- 349 350 void rawTileData (int &dx, int &dy, 351 int &lx, int &ly, 352 const char *&pixelData, 353 int &pixelDataSize); 354 355 struct Data; 356 357 private: 358 359 friend class InputFile; 360 361 TiledInputFile (const TiledInputFile &); // not implemented 362 TiledInputFile & operator = (const TiledInputFile &); // not implemented 363 364 TiledInputFile (const Header &header, IStream *is, int version, 365 int numThreads); 366 367 void initialize (); 368 369 bool isValidTile (int dx, int dy, 370 int lx, int ly) const; 371 372 size_t bytesPerLineForTile (int dx, int dy, 373 int lx, int ly) const; 374 375 Data * _data; 376 }; 377 378 379 } // namespace Imf 380 381 #endif 382
