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