1 // 2 // SPDX-License-Identifier: BSD-3-Clause 3 // Copyright (c) Contributors to the OpenEXR Project. 4 // 5 6 #ifndef IMFDEEPTILEDINPUTPART_H_ 7 #define IMFDEEPTILEDINPUTPART_H_ 8 9 #include "ImfForward.h" 10 11 #include "ImfTileDescription.h" 12 13 #include <ImathBox.h> 14 15 OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER 16 17 class IMF_EXPORT_TYPE DeepTiledInputPart 18 { 19 public: 20 21 IMF_EXPORT 22 DeepTiledInputPart(MultiPartInputFile& multiPartFile, int partNumber); 23 24 //------------------------ 25 // Access to the file name 26 //------------------------ 27 28 IMF_EXPORT 29 const char * fileName () const; 30 31 32 //-------------------------- 33 // Access to the file header 34 //-------------------------- 35 36 IMF_EXPORT 37 const Header & header () const; 38 39 40 //---------------------------------- 41 // Access to the file format version 42 //---------------------------------- 43 44 IMF_EXPORT 45 int version () const; 46 47 48 //----------------------------------------------------------- 49 // Set the current frame buffer -- copies the FrameBuffer 50 // object into the TiledInputFile object. 51 // 52 // The current frame buffer is the destination for the pixel 53 // data read from the file. The current frame buffer must be 54 // set at least once before readTile() is called. 55 // The current frame buffer can be changed after each call 56 // to readTile(). 57 //----------------------------------------------------------- 58 59 IMF_EXPORT 60 void setFrameBuffer (const DeepFrameBuffer &frameBuffer); 61 62 63 //----------------------------------- 64 // Access to the current frame buffer 65 //----------------------------------- 66 67 IMF_EXPORT 68 const DeepFrameBuffer & frameBuffer () const; 69 70 71 //------------------------------------------------------------ 72 // Check if the file is complete: 73 // 74 // isComplete() returns true if all pixels in the data window 75 // (in all levels) are present in the input file, or false if 76 // any pixels are missing. (Another program may still be busy 77 // writing the file, or file writing may have been aborted 78 // prematurely.) 79 //------------------------------------------------------------ 80 81 IMF_EXPORT 82 bool isComplete () const; 83 84 85 //-------------------------------------------------- 86 // Utility functions: 87 //-------------------------------------------------- 88 89 //--------------------------------------------------------- 90 // Multiresolution mode and tile size: 91 // The following functions return the xSize, ySize and mode 92 // fields of the file header's TileDescriptionAttribute. 93 //--------------------------------------------------------- 94 95 IMF_EXPORT 96 unsigned int tileXSize () const; 97 IMF_EXPORT 98 unsigned int tileYSize () const; 99 IMF_EXPORT 100 LevelMode levelMode () const; 101 IMF_EXPORT 102 LevelRoundingMode levelRoundingMode () const; 103 104 105 //-------------------------------------------------------------------- 106 // Number of levels: 107 // 108 // numXLevels() returns the file's number of levels in x direction. 109 // 110 // if levelMode() == ONE_LEVEL: 111 // return value is: 1 112 // 113 // if levelMode() == MIPMAP_LEVELS: 114 // return value is: rfunc (log (max (w, h)) / log (2)) + 1 115 // 116 // if levelMode() == RIPMAP_LEVELS: 117 // return value is: rfunc (log (w) / log (2)) + 1 118 // 119 // where 120 // w is the width of the image's data window, max.x - min.x + 1, 121 // y is the height of the image's data window, max.y - min.y + 1, 122 // and rfunc(x) is either floor(x), or ceil(x), depending on 123 // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP. 124 // 125 // numYLevels() returns the file's number of levels in y direction. 126 // 127 // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS: 128 // return value is the same as for numXLevels() 129 // 130 // if levelMode() == RIPMAP_LEVELS: 131 // return value is: rfunc (log (h) / log (2)) + 1 132 // 133 // 134 // numLevels() is a convenience function for use with 135 // MIPMAP_LEVELS files. 136 // 137 // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS: 138 // return value is the same as for numXLevels() 139 // 140 // if levelMode() == RIPMAP_LEVELS: 141 // an IEX_NAMESPACE::LogicExc exception is thrown 142 // 143 // isValidLevel(lx, ly) returns true if the file contains 144 // a level with level number (lx, ly), false if not. 145 // 146 //-------------------------------------------------------------------- 147 148 IMF_EXPORT 149 int numLevels () const; 150 IMF_EXPORT 151 int numXLevels () const; 152 IMF_EXPORT 153 int numYLevels () const; 154 IMF_EXPORT 155 bool isValidLevel (int lx, int ly) const; 156 157 158 //---------------------------------------------------------- 159 // Dimensions of a level: 160 // 161 // levelWidth(lx) returns the width of a level with level 162 // number (lx, *), where * is any number. 163 // 164 // return value is: 165 // max (1, rfunc (w / pow (2, lx))) 166 // 167 // 168 // levelHeight(ly) returns the height of a level with level 169 // number (*, ly), where * is any number. 170 // 171 // return value is: 172 // max (1, rfunc (h / pow (2, ly))) 173 // 174 //---------------------------------------------------------- 175 176 IMF_EXPORT 177 int levelWidth (int lx) const; 178 IMF_EXPORT 179 int levelHeight (int ly) const; 180 181 182 //-------------------------------------------------------------- 183 // Number of tiles: 184 // 185 // numXTiles(lx) returns the number of tiles in x direction 186 // that cover a level with level number (lx, *), where * is 187 // any number. 188 // 189 // return value is: 190 // (levelWidth(lx) + tileXSize() - 1) / tileXSize() 191 // 192 // 193 // numYTiles(ly) returns the number of tiles in y direction 194 // that cover a level with level number (*, ly), where * is 195 // any number. 196 // 197 // return value is: 198 // (levelHeight(ly) + tileXSize() - 1) / tileXSize() 199 // 200 //-------------------------------------------------------------- 201 202 IMF_EXPORT 203 int numXTiles (int lx = 0) const; 204 IMF_EXPORT 205 int numYTiles (int ly = 0) const; 206 207 208 //--------------------------------------------------------------- 209 // Level pixel ranges: 210 // 211 // dataWindowForLevel(lx, ly) returns a 2-dimensional region of 212 // valid pixel coordinates for a level with level number (lx, ly) 213 // 214 // return value is a Box2i with min value: 215 // (dataWindow.min.x, dataWindow.min.y) 216 // 217 // and max value: 218 // (dataWindow.min.x + levelWidth(lx) - 1, 219 // dataWindow.min.y + levelHeight(ly) - 1) 220 // 221 // dataWindowForLevel(level) is a convenience function used 222 // for ONE_LEVEL and MIPMAP_LEVELS files. It returns 223 // dataWindowForLevel(level, level). 224 // 225 //--------------------------------------------------------------- 226 227 IMF_EXPORT 228 IMATH_NAMESPACE::Box2i dataWindowForLevel (int l = 0) const; 229 IMF_EXPORT 230 IMATH_NAMESPACE::Box2i dataWindowForLevel (int lx, int ly) const; 231 232 233 //------------------------------------------------------------------- 234 // Tile pixel ranges: 235 // 236 // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional 237 // region of valid pixel coordinates for a tile with tile coordinates 238 // (dx,dy) and level number (lx, ly). 239 // 240 // return value is a Box2i with min value: 241 // (dataWindow.min.x + dx * tileXSize(), 242 // dataWindow.min.y + dy * tileYSize()) 243 // 244 // and max value: 245 // (dataWindow.min.x + (dx + 1) * tileXSize() - 1, 246 // dataWindow.min.y + (dy + 1) * tileYSize() - 1) 247 // 248 // dataWindowForTile(dx, dy, level) is a convenience function 249 // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns 250 // dataWindowForTile(dx, dy, level, level). 251 // 252 //------------------------------------------------------------------- 253 254 IMF_EXPORT 255 IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy, int l = 0) const; 256 257 IMF_EXPORT 258 IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy, 259 int lx, int ly) const; 260 261 //------------------------------------------------------------ 262 // Read pixel data: 263 // 264 // readTile(dx, dy, lx, ly) reads the tile with tile 265 // coordinates (dx, dy), and level number (lx, ly), 266 // and stores it in the current frame buffer. 267 // 268 // dx must lie in the interval [0, numXTiles(lx)-1] 269 // dy must lie in the interval [0, numYTiles(ly)-1] 270 // 271 // lx must lie in the interval [0, numXLevels()-1] 272 // ly must lie in the inverval [0, numYLevels()-1] 273 // 274 // readTile(dx, dy, level) is a convenience function used 275 // for ONE_LEVEL and MIPMAP_LEVELS files. It calls 276 // readTile(dx, dy, level, level). 277 // 278 // The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow 279 // reading multiple tiles at once. If multi-threading is used 280 // the multiple tiles are read concurrently. 281 // 282 // Pixels that are outside the pixel coordinate range for the 283 // tile's level, are never accessed by readTile(). 284 // 285 // Attempting to access a tile that is not present in the file 286 // throws an InputExc exception. 287 // 288 //------------------------------------------------------------ 289 290 IMF_EXPORT 291 void readTile (int dx, int dy, int l = 0); 292 IMF_EXPORT 293 void readTile (int dx, int dy, int lx, int ly); 294 295 IMF_EXPORT 296 void readTiles (int dx1, int dx2, int dy1, int dy2, 297 int lx, int ly); 298 299 IMF_EXPORT 300 void readTiles (int dx1, int dx2, int dy1, int dy2, 301 int l = 0); 302 303 304 //-------------------------------------------------- 305 // Read a tile of raw pixel data from the file, 306 // without uncompressing it (this function is 307 // used to implement TiledOutputFile::copyPixels()). 308 //-------------------------------------------------- 309 310 IMF_EXPORT 311 void rawTileData (int &dx, int &dy, 312 int &lx, int &ly, 313 char *data, 314 uint64_t &dataSize 315 ) const; 316 317 //------------------------------------------------------------------ 318 // Read pixel sample counts into a slice in the frame buffer. 319 // 320 // readPixelSampleCount(dx, dy, lx, ly) reads the sample counts 321 // for tile (dx, dy) in level (lx, ly). 322 // 323 // readPixelSampleCount(dx, dy, l) calls 324 // readPixelSampleCount(dx, dy, lx = l, ly = l) 325 // 326 // dx must lie in the interval [0, numXTiles(lx)-1] 327 // dy must lie in the interval [0, numYTiles(ly)-1] 328 // 329 // lx must lie in the interval [0, numXLevels()-1] 330 // ly must lie in the inverval [0, numYLevels()-1] 331 // 332 // readPixelSampleCounts(dx1, dx2, dy1, dy2, lx, ly) reads all 333 // the sample counts for tiles within range 334 // [(min(dx1, dx2), min(dy1, dy2))...(max(dx1, dx2), max(dy1, dy2)], 335 // and on level (lx, ly) 336 // 337 // readPixelSampleCounts(dx1, dx2, dy1, dy2, l) calls 338 // readPixelSampleCounts(dx1, dx2, dy1, dy2, lx = l, ly = l). 339 //------------------------------------------------------------------ 340 341 IMF_EXPORT 342 void readPixelSampleCount (int dx, int dy, int l = 0); 343 IMF_EXPORT 344 void readPixelSampleCount (int dx, int dy, int lx, int ly); 345 346 IMF_EXPORT 347 void readPixelSampleCounts (int dx1, int dx2, 348 int dy1, int dy2, 349 int lx, int ly); 350 351 IMF_EXPORT 352 void readPixelSampleCounts (int dx1, int dx2, 353 int dy1, int dy2, 354 int l = 0); 355 356 private: 357 DeepTiledInputFile* file; 358 359 friend class DeepTiledOutputFile; 360 }; 361 362 OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT 363 364 365 #endif /* IMFDEEPTILEDINPUTPART_H_ */ 366