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