HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImfDeepTiledInputFile.h
Go to the documentation of this file.
1 //
2 // SPDX-License-Identifier: BSD-3-Clause
3 // Copyright (c) Contributors to the OpenEXR Project.
4 //
5 
6 #ifndef INCLUDED_IMF_DEEP_TILED_INPUT_FILE_H
7 #define INCLUDED_IMF_DEEP_TILED_INPUT_FILE_H
8 
9 //-----------------------------------------------------------------------------
10 //
11 // class DeepTiledInputFile
12 //
13 //-----------------------------------------------------------------------------
14 
15 #include "ImfForward.h"
16 
17 #include "ImfThreading.h"
18 #include "ImfGenericInputFile.h"
19 
20 #include "ImfTileDescription.h"
21 
22 #include <cstdint>
23 #include <ImathBox.h>
24 
26 
28 {
29  public:
30 
31  //--------------------------------------------------------------------
32  // A constructor that opens the file with the specified name, and
33  // reads the file header. The constructor throws an IEX_NAMESPACE::ArgExc
34  // exception if the file is not tiled.
35  // The numThreads parameter specifies how many worker threads this
36  // file will try to keep busy when decompressing individual tiles.
37  // Destroying TiledInputFile objects constructed with this constructor
38  // automatically closes the corresponding files.
39  //--------------------------------------------------------------------
40 
42  DeepTiledInputFile (const char fileName[],
43  int numThreads = globalThreadCount ());
44 
45 
46  // ----------------------------------------------------------
47  // A constructor that attaches the new TiledInputFile object
48  // to a file that has already been opened.
49  // Destroying TiledInputFile objects constructed with this
50  // constructor does not automatically close the corresponding
51  // files.
52  // ----------------------------------------------------------
53 
56 
57 
58  //-----------
59  // Destructor
60  //-----------
61 
63  virtual ~DeepTiledInputFile ();
64 
65 
66  //------------------------
67  // Access to the file name
68  //------------------------
69 
71  const char * fileName () const;
72 
73 
74  //--------------------------
75  // Access to the file header
76  //--------------------------
77 
79  const Header & header () const;
80 
81 
82  //----------------------------------
83  // Access to the file format version
84  //----------------------------------
85 
87  int version () const;
88 
89 
90  //-----------------------------------------------------------
91  // Set the current frame buffer -- copies the FrameBuffer
92  // object into the TiledInputFile object.
93  //
94  // The current frame buffer is the destination for the pixel
95  // data read from the file. The current frame buffer must be
96  // set at least once before readTile() is called.
97  // The current frame buffer can be changed after each call
98  // to readTile().
99  //-----------------------------------------------------------
100 
101  IMF_EXPORT
102  void setFrameBuffer (const DeepFrameBuffer &frameBuffer);
103 
104 
105  //-----------------------------------
106  // Access to the current frame buffer
107  //-----------------------------------
108 
109  IMF_EXPORT
110  const DeepFrameBuffer & frameBuffer () const;
111 
112 
113  //------------------------------------------------------------
114  // Check if the file is complete:
115  //
116  // isComplete() returns true if all pixels in the data window
117  // (in all levels) are present in the input file, or false if
118  // any pixels are missing. (Another program may still be busy
119  // writing the file, or file writing may have been aborted
120  // prematurely.)
121  //------------------------------------------------------------
122 
123  IMF_EXPORT
124  bool isComplete () const;
125 
126 
127  //--------------------------------------------------
128  // Utility functions:
129  //--------------------------------------------------
130 
131  //---------------------------------------------------------
132  // Multiresolution mode and tile size:
133  // The following functions return the xSize, ySize and mode
134  // fields of the file header's TileDescriptionAttribute.
135  //---------------------------------------------------------
136 
137  IMF_EXPORT
138  unsigned int tileXSize () const;
139  IMF_EXPORT
140  unsigned int tileYSize () const;
141  IMF_EXPORT
142  LevelMode levelMode () const;
143  IMF_EXPORT
144  LevelRoundingMode levelRoundingMode () const;
145 
146 
147  //--------------------------------------------------------------------
148  // Number of levels:
149  //
150  // numXLevels() returns the file's number of levels in x direction.
151  //
152  // if levelMode() == ONE_LEVEL:
153  // return value is: 1
154  //
155  // if levelMode() == MIPMAP_LEVELS:
156  // return value is: rfunc (log (max (w, h)) / log (2)) + 1
157  //
158  // if levelMode() == RIPMAP_LEVELS:
159  // return value is: rfunc (log (w) / log (2)) + 1
160  //
161  // where
162  // w is the width of the image's data window, max.x - min.x + 1,
163  // y is the height of the image's data window, max.y - min.y + 1,
164  // and rfunc(x) is either floor(x), or ceil(x), depending on
165  // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
166  //
167  // numYLevels() returns the file's number of levels in y direction.
168  //
169  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
170  // return value is the same as for numXLevels()
171  //
172  // if levelMode() == RIPMAP_LEVELS:
173  // return value is: rfunc (log (h) / log (2)) + 1
174  //
175  //
176  // numLevels() is a convenience function for use with
177  // MIPMAP_LEVELS files.
178  //
179  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
180  // return value is the same as for numXLevels()
181  //
182  // if levelMode() == RIPMAP_LEVELS:
183  // an IEX_NAMESPACE::LogicExc exception is thrown
184  //
185  // isValidLevel(lx, ly) returns true if the file contains
186  // a level with level number (lx, ly), false if not.
187  //
188  // totalTiles() returns the total number of tiles in the image
189  //
190  //--------------------------------------------------------------------
191 
192  IMF_EXPORT
193  int numLevels () const;
194  IMF_EXPORT
195  int numXLevels () const;
196  IMF_EXPORT
197  int numYLevels () const;
198  IMF_EXPORT
199  bool isValidLevel (int lx, int ly) const;
200  IMF_EXPORT
201  size_t totalTiles() const;
202 
203  //----------------------------------------------------------
204  // Dimensions of a level:
205  //
206  // levelWidth(lx) returns the width of a level with level
207  // number (lx, *), where * is any number.
208  //
209  // return value is:
210  // max (1, rfunc (w / pow (2, lx)))
211  //
212  //
213  // levelHeight(ly) returns the height of a level with level
214  // number (*, ly), where * is any number.
215  //
216  // return value is:
217  // max (1, rfunc (h / pow (2, ly)))
218  //
219  //----------------------------------------------------------
220 
221  IMF_EXPORT
222  int levelWidth (int lx) const;
223  IMF_EXPORT
224  int levelHeight (int ly) const;
225 
226 
227  //--------------------------------------------------------------
228  // Number of tiles:
229  //
230  // numXTiles(lx) returns the number of tiles in x direction
231  // that cover a level with level number (lx, *), where * is
232  // any number.
233  //
234  // return value is:
235  // (levelWidth(lx) + tileXSize() - 1) / tileXSize()
236  //
237  //
238  // numYTiles(ly) returns the number of tiles in y direction
239  // that cover a level with level number (*, ly), where * is
240  // any number.
241  //
242  // return value is:
243  // (levelHeight(ly) + tileXSize() - 1) / tileXSize()
244  //
245  //--------------------------------------------------------------
246 
247  IMF_EXPORT
248  int numXTiles (int lx = 0) const;
249  IMF_EXPORT
250  int numYTiles (int ly = 0) const;
251 
252 
253  //---------------------------------------------------------------
254  // Level pixel ranges:
255  //
256  // dataWindowForLevel(lx, ly) returns a 2-dimensional region of
257  // valid pixel coordinates for a level with level number (lx, ly)
258  //
259  // return value is a Box2i with min value:
260  // (dataWindow.min.x, dataWindow.min.y)
261  //
262  // and max value:
263  // (dataWindow.min.x + levelWidth(lx) - 1,
264  // dataWindow.min.y + levelHeight(ly) - 1)
265  //
266  // dataWindowForLevel(level) is a convenience function used
267  // for ONE_LEVEL and MIPMAP_LEVELS files. It returns
268  // dataWindowForLevel(level, level).
269  //
270  //---------------------------------------------------------------
271 
272  IMF_EXPORT
273  IMATH_NAMESPACE::Box2i dataWindowForLevel (int l = 0) const;
274  IMF_EXPORT
275  IMATH_NAMESPACE::Box2i dataWindowForLevel (int lx, int ly) const;
276 
277 
278  //-------------------------------------------------------------------
279  // Tile pixel ranges:
280  //
281  // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
282  // region of valid pixel coordinates for a tile with tile coordinates
283  // (dx,dy) and level number (lx, ly).
284  //
285  // return value is a Box2i with min value:
286  // (dataWindow.min.x + dx * tileXSize(),
287  // dataWindow.min.y + dy * tileYSize())
288  //
289  // and max value:
290  // (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
291  // dataWindow.min.y + (dy + 1) * tileYSize() - 1)
292  //
293  // dataWindowForTile(dx, dy, level) is a convenience function
294  // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns
295  // dataWindowForTile(dx, dy, level, level).
296  //
297  //-------------------------------------------------------------------
298 
299  IMF_EXPORT
300  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy, int l = 0) const;
301 
302  IMF_EXPORT
303  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy,
304  int lx, int ly) const;
305 
306  //------------------------------------------------------------
307  // Read pixel data:
308  //
309  // readTile(dx, dy, lx, ly) reads the tile with tile
310  // coordinates (dx, dy), and level number (lx, ly),
311  // and stores it in the current frame buffer.
312  //
313  // dx must lie in the interval [0, numXTiles(lx)-1]
314  // dy must lie in the interval [0, numYTiles(ly)-1]
315  //
316  // lx must lie in the interval [0, numXLevels()-1]
317  // ly must lie in the interval [0, numYLevels()-1]
318  //
319  // readTile(dx, dy, level) is a convenience function used
320  // for ONE_LEVEL and MIPMAP_LEVELS files. It calls
321  // readTile(dx, dy, level, level).
322  //
323  // The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow
324  // reading multiple tiles at once. If multi-threading is used
325  // the multiple tiles are read concurrently.
326  //
327  // Pixels that are outside the pixel coordinate range for the
328  // tile's level, are never accessed by readTile().
329  //
330  // Attempting to access a tile that is not present in the file
331  // throws an InputExc exception.
332  //
333  //------------------------------------------------------------
334 
335  IMF_EXPORT
336  void readTile (int dx, int dy, int l = 0);
337  IMF_EXPORT
338  void readTile (int dx, int dy, int lx, int ly);
339 
340  IMF_EXPORT
341  void readTiles (int dx1, int dx2, int dy1, int dy2,
342  int lx, int ly);
343 
344  IMF_EXPORT
345  void readTiles (int dx1, int dx2, int dy1, int dy2,
346  int l = 0);
347 
348 
349  //--------------------------------------------------
350  // Read a tile of raw pixel data from the file,
351  // without uncompressing it (this function is
352  // used to implement TiledOutputFile::copyPixels()).
353  //--------------------------------------------------
354 
355  IMF_EXPORT
356  void rawTileData (int &dx, int &dy,
357  int &lx, int &ly,
358  char *pixelData,
359  uint64_t &dataSize) const;
360 
361  //------------------------------------------------------------------
362  // Read pixel sample counts into a slice in the frame buffer.
363  //
364  // readPixelSampleCount(dx, dy, lx, ly) reads the sample counts
365  // for tile (dx, dy) in level (lx, ly).
366  //
367  // readPixelSampleCount(dx, dy, l) calls
368  // readPixelSampleCount(dx, dy, lx = l, ly = l)
369  //
370  // dx must lie in the interval [0, numXTiles(lx)-1]
371  // dy must lie in the interval [0, numYTiles(ly)-1]
372  //
373  // lx must lie in the interval [0, numXLevels()-1]
374  // ly must lie in the interval [0, numYLevels()-1]
375  //
376  // readPixelSampleCounts(dx1, dx2, dy1, dy2, lx, ly) reads all
377  // the sample counts for tiles within range
378  // [(min(dx1, dx2), min(dy1, dy2))...(max(dx1, dx2), max(dy1, dy2)],
379  // and on level (lx, ly)
380  //
381  // readPixelSampleCounts(dx1, dx2, dy1, dy2, l) calls
382  // readPixelSampleCounts(dx1, dx2, dy1, dy2, lx = l, ly = l).
383  //------------------------------------------------------------------
384 
385  IMF_EXPORT
386  void readPixelSampleCount (int dx, int dy, int l = 0);
387  IMF_EXPORT
388  void readPixelSampleCount (int dx, int dy, int lx, int ly);
389 
390  IMF_EXPORT
391  void readPixelSampleCounts (int dx1, int dx2,
392  int dy1, int dy2,
393  int lx, int ly);
394 
395  IMF_EXPORT
396  void readPixelSampleCounts (int dx1, int dx2,
397  int dy1, int dy2,
398  int l = 0);
399 
400  struct Data;
401 
402 
403 
404  private:
405 
406  friend class InputFile;
407  friend class MultiPartInputFile;
408 
409  DeepTiledInputFile (InputPartData* part);
410 
411  DeepTiledInputFile (const DeepTiledInputFile &) = delete;
412  DeepTiledInputFile & operator = (const DeepTiledInputFile &) = delete;
413  DeepTiledInputFile (DeepTiledInputFile &&) = delete;
414  DeepTiledInputFile & operator = (DeepTiledInputFile &&) = delete;
415 
416  DeepTiledInputFile (const Header &header, OPENEXR_IMF_INTERNAL_NAMESPACE::IStream *is, int version,
417  int numThreads);
418 
419  void initialize ();
420  void multiPartInitialize(InputPartData* part);
421  void compatibilityInitialize(OPENEXR_IMF_INTERNAL_NAMESPACE::IStream& is);
422 
423  bool isValidTile (int dx, int dy,
424  int lx, int ly) const;
425 
426  size_t bytesPerLineForTile (int dx, int dy,
427  int lx, int ly) const;
428 
429 
430  void getTileOrder(int dx[],int dy[],int lx[],int ly[]) const;
431 
432 
433  Data * _data;
434 
435 
436  // needed for copyPixels
437  friend class DeepTiledOutputFile;
438 };
439 
441 
442 #endif
class IMF_EXPORT_TYPE DeepTiledInputFile
Definition: ImfForward.h:41
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
Definition: ImfNamespace.h:80
enum IMF_EXPORT_ENUM LevelRoundingMode
Box< V2i > Box2i
2D box of base type int.
Definition: ImathBox.h:143
#define IMF_EXPORT
Definition: ImfExport.h:54
OPENVDB_API void initialize()
Global registration of native Grid, Transform, Metadata and Point attribute types. Also initializes blosc (if enabled).
Definition: logging.h:294
GT_API const UT_StringHolder version
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER IMF_EXPORT int globalThreadCount()
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
Definition: ImfNamespace.h:79
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER enum IMF_EXPORT_ENUM LevelMode
struct IMF_HIDDEN Data
#define IMF_EXPORT_TYPE
Definition: ImfExport.h:57
class IMF_EXPORT_TYPE IStream
Definition: ImfForward.h:89