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