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