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 //
3 // Copyright (c) 2011, Industrial Light & Magic, a division of Lucas
4 // Digital Ltd. LLC
5 //
6 // All rights reserved.
7 //
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
10 // met:
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
16 // distribution.
17 // * Neither the name of Industrial Light & Magic nor the names of
18 // its contributors may be used to endorse or promote products derived
19 // from this software without specific prior written permission.
20 //
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 //
33 ///////////////////////////////////////////////////////////////////////////
34 
35 
36 #ifndef INCLUDED_IMF_DEEP_TILED_INPUT_FILE_H
37 #define INCLUDED_IMF_DEEP_TILED_INPUT_FILE_H
38 
39 //-----------------------------------------------------------------------------
40 //
41 // class DeepTiledInputFile
42 //
43 //-----------------------------------------------------------------------------
44 
45 #include "ImfHeader.h"
46 #include "ImfFrameBuffer.h"
47 #include "ImathBox.h"
48 #include "ImfTileDescription.h"
49 #include "ImfThreading.h"
50 #include "ImfGenericInputFile.h"
51 #include "ImfDeepFrameBuffer.h"
52 #include "ImfDeepTiledOutputFile.h"
53 #include "ImfForward.h"
54 #include "ImfNamespace.h"
55 #include "ImfExport.h"
56 
58 
60 {
61  public:
62 
63  //--------------------------------------------------------------------
64  // A constructor that opens the file with the specified name, and
65  // reads the file header. The constructor throws an IEX_NAMESPACE::ArgExc
66  // exception if the file is not tiled.
67  // The numThreads parameter specifies how many worker threads this
68  // file will try to keep busy when decompressing individual tiles.
69  // Destroying TiledInputFile objects constructed with this constructor
70  // automatically closes the corresponding files.
71  //--------------------------------------------------------------------
72 
73  DeepTiledInputFile (const char fileName[],
74  int numThreads = globalThreadCount ());
75 
76 
77  // ----------------------------------------------------------
78  // A constructor that attaches the new TiledInputFile object
79  // to a file that has already been opened.
80  // Destroying TiledInputFile objects constructed with this
81  // constructor does not automatically close the corresponding
82  // files.
83  // ----------------------------------------------------------
84 
85  DeepTiledInputFile (OPENEXR_IMF_INTERNAL_NAMESPACE::IStream &is, int numThreads = globalThreadCount ());
86 
87 
88  //-----------
89  // Destructor
90  //-----------
91 
92  virtual ~DeepTiledInputFile ();
93 
94 
95  //------------------------
96  // Access to the file name
97  //------------------------
98 
99  const char * fileName () const;
100 
101 
102  //--------------------------
103  // Access to the file header
104  //--------------------------
105 
106  const Header & header () const;
107 
108 
109  //----------------------------------
110  // Access to the file format version
111  //----------------------------------
112 
113  int version () const;
114 
115 
116  //-----------------------------------------------------------
117  // Set the current frame buffer -- copies the FrameBuffer
118  // object into the TiledInputFile object.
119  //
120  // The current frame buffer is the destination for the pixel
121  // data read from the file. The current frame buffer must be
122  // set at least once before readTile() is called.
123  // The current frame buffer can be changed after each call
124  // to readTile().
125  //-----------------------------------------------------------
126 
127  void setFrameBuffer (const DeepFrameBuffer &frameBuffer);
128 
129 
130  //-----------------------------------
131  // Access to the current frame buffer
132  //-----------------------------------
133 
134  const DeepFrameBuffer & frameBuffer () const;
135 
136 
137  //------------------------------------------------------------
138  // Check if the file is complete:
139  //
140  // isComplete() returns true if all pixels in the data window
141  // (in all levels) are present in the input file, or false if
142  // any pixels are missing. (Another program may still be busy
143  // writing the file, or file writing may have been aborted
144  // prematurely.)
145  //------------------------------------------------------------
146 
147  bool isComplete () const;
148 
149 
150  //--------------------------------------------------
151  // Utility functions:
152  //--------------------------------------------------
153 
154  //---------------------------------------------------------
155  // Multiresolution mode and tile size:
156  // The following functions return the xSize, ySize and mode
157  // fields of the file header's TileDescriptionAttribute.
158  //---------------------------------------------------------
159 
160  unsigned int tileXSize () const;
161  unsigned int tileYSize () const;
162  LevelMode levelMode () const;
163  LevelRoundingMode levelRoundingMode () const;
164 
165 
166  //--------------------------------------------------------------------
167  // Number of levels:
168  //
169  // numXLevels() returns the file's number of levels in x direction.
170  //
171  // if levelMode() == ONE_LEVEL:
172  // return value is: 1
173  //
174  // if levelMode() == MIPMAP_LEVELS:
175  // return value is: rfunc (log (max (w, h)) / log (2)) + 1
176  //
177  // if levelMode() == RIPMAP_LEVELS:
178  // return value is: rfunc (log (w) / log (2)) + 1
179  //
180  // where
181  // w is the width of the image's data window, max.x - min.x + 1,
182  // y is the height of the image's data window, max.y - min.y + 1,
183  // and rfunc(x) is either floor(x), or ceil(x), depending on
184  // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
185  //
186  // numYLevels() returns the file's number of levels in y direction.
187  //
188  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
189  // return value is the same as for numXLevels()
190  //
191  // if levelMode() == RIPMAP_LEVELS:
192  // return value is: rfunc (log (h) / log (2)) + 1
193  //
194  //
195  // numLevels() is a convenience function for use with
196  // MIPMAP_LEVELS files.
197  //
198  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
199  // return value is the same as for numXLevels()
200  //
201  // if levelMode() == RIPMAP_LEVELS:
202  // an IEX_NAMESPACE::LogicExc exception is thrown
203  //
204  // isValidLevel(lx, ly) returns true if the file contains
205  // a level with level number (lx, ly), false if not.
206  //
207  // totalTiles() returns the total number of tiles in the image
208  //
209  //--------------------------------------------------------------------
210 
211  int numLevels () const;
212  int numXLevels () const;
213  int numYLevels () const;
214  bool isValidLevel (int lx, int ly) const;
215  size_t totalTiles() const;
216 
217  //----------------------------------------------------------
218  // Dimensions of a level:
219  //
220  // levelWidth(lx) returns the width of a level with level
221  // number (lx, *), where * is any number.
222  //
223  // return value is:
224  // max (1, rfunc (w / pow (2, lx)))
225  //
226  //
227  // levelHeight(ly) returns the height of a level with level
228  // number (*, ly), where * is any number.
229  //
230  // return value is:
231  // max (1, rfunc (h / pow (2, ly)))
232  //
233  //----------------------------------------------------------
234 
235  int levelWidth (int lx) const;
236  int levelHeight (int ly) const;
237 
238 
239  //--------------------------------------------------------------
240  // Number of tiles:
241  //
242  // numXTiles(lx) returns the number of tiles in x direction
243  // that cover a level with level number (lx, *), where * is
244  // any number.
245  //
246  // return value is:
247  // (levelWidth(lx) + tileXSize() - 1) / tileXSize()
248  //
249  //
250  // numYTiles(ly) returns the number of tiles in y direction
251  // that cover a level with level number (*, ly), where * is
252  // any number.
253  //
254  // return value is:
255  // (levelHeight(ly) + tileXSize() - 1) / tileXSize()
256  //
257  //--------------------------------------------------------------
258 
259  int numXTiles (int lx = 0) const;
260  int numYTiles (int ly = 0) const;
261 
262 
263  //---------------------------------------------------------------
264  // Level pixel ranges:
265  //
266  // dataWindowForLevel(lx, ly) returns a 2-dimensional region of
267  // valid pixel coordinates for a level with level number (lx, ly)
268  //
269  // return value is a Box2i with min value:
270  // (dataWindow.min.x, dataWindow.min.y)
271  //
272  // and max value:
273  // (dataWindow.min.x + levelWidth(lx) - 1,
274  // dataWindow.min.y + levelHeight(ly) - 1)
275  //
276  // dataWindowForLevel(level) is a convenience function used
277  // for ONE_LEVEL and MIPMAP_LEVELS files. It returns
278  // dataWindowForLevel(level, level).
279  //
280  //---------------------------------------------------------------
281 
282  IMATH_NAMESPACE::Box2i dataWindowForLevel (int l = 0) const;
283  IMATH_NAMESPACE::Box2i dataWindowForLevel (int lx, int ly) const;
284 
285 
286  //-------------------------------------------------------------------
287  // Tile pixel ranges:
288  //
289  // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
290  // region of valid pixel coordinates for a tile with tile coordinates
291  // (dx,dy) and level number (lx, ly).
292  //
293  // return value is a Box2i with min value:
294  // (dataWindow.min.x + dx * tileXSize(),
295  // dataWindow.min.y + dy * tileYSize())
296  //
297  // and max value:
298  // (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
299  // dataWindow.min.y + (dy + 1) * tileYSize() - 1)
300  //
301  // dataWindowForTile(dx, dy, level) is a convenience function
302  // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns
303  // dataWindowForTile(dx, dy, level, level).
304  //
305  //-------------------------------------------------------------------
306 
307  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy, int l = 0) const;
308 
309  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy,
310  int lx, int ly) const;
311 
312  //------------------------------------------------------------
313  // Read pixel data:
314  //
315  // readTile(dx, dy, lx, ly) reads the tile with tile
316  // coordinates (dx, dy), and level number (lx, ly),
317  // and stores it in the current frame buffer.
318  //
319  // dx must lie in the interval [0, numXTiles(lx)-1]
320  // dy must lie in the interval [0, numYTiles(ly)-1]
321  //
322  // lx must lie in the interval [0, numXLevels()-1]
323  // ly must lie in the inverval [0, numYLevels()-1]
324  //
325  // readTile(dx, dy, level) is a convenience function used
326  // for ONE_LEVEL and MIPMAP_LEVELS files. It calls
327  // readTile(dx, dy, level, level).
328  //
329  // The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow
330  // reading multiple tiles at once. If multi-threading is used
331  // the multiple tiles are read concurrently.
332  //
333  // Pixels that are outside the pixel coordinate range for the
334  // tile's level, are never accessed by readTile().
335  //
336  // Attempting to access a tile that is not present in the file
337  // throws an InputExc exception.
338  //
339  //------------------------------------------------------------
340 
341  void readTile (int dx, int dy, int l = 0);
342  void readTile (int dx, int dy, int lx, int ly);
343 
344  void readTiles (int dx1, int dx2, int dy1, int dy2,
345  int lx, int ly);
346 
347  void readTiles (int dx1, int dx2, int dy1, int dy2,
348  int l = 0);
349 
350 
351  //--------------------------------------------------
352  // Read a tile of raw pixel data from the file,
353  // without uncompressing it (this function is
354  // used to implement TiledOutputFile::copyPixels()).
355  //--------------------------------------------------
356 
357  void rawTileData (int &dx, int &dy,
358  int &lx, int &ly,
359  char *pixelData,
360  Int64 &dataSize) const;
361 
362  //------------------------------------------------------------------
363  // Read pixel sample counts into a slice in the frame buffer.
364  //
365  // readPixelSampleCount(dx, dy, lx, ly) reads the sample counts
366  // for tile (dx, dy) in level (lx, ly).
367  //
368  // readPixelSampleCount(dx, dy, l) calls
369  // readPixelSampleCount(dx, dy, lx = l, ly = l)
370  //
371  // dx must lie in the interval [0, numXTiles(lx)-1]
372  // dy must lie in the interval [0, numYTiles(ly)-1]
373  //
374  // lx must lie in the interval [0, numXLevels()-1]
375  // ly must lie in the inverval [0, numYLevels()-1]
376  //
377  // readPixelSampleCounts(dx1, dx2, dy1, dy2, lx, ly) reads all
378  // the sample counts for tiles within range
379  // [(min(dx1, dx2), min(dy1, dy2))...(max(dx1, dx2), max(dy1, dy2)],
380  // and on level (lx, ly)
381  //
382  // readPixelSampleCounts(dx1, dx2, dy1, dy2, l) calls
383  // readPixelSampleCounts(dx1, dx2, dy1, dy2, lx = l, ly = l).
384  //------------------------------------------------------------------
385 
386  void readPixelSampleCount (int dx, int dy, int l = 0);
387  void readPixelSampleCount (int dx, int dy, int lx, int ly);
388 
389  void readPixelSampleCounts (int dx1, int dx2,
390  int dy1, int dy2,
391  int lx, int ly);
392 
393  void readPixelSampleCounts (int dx1, int dx2,
394  int dy1, int dy2,
395  int l = 0);
396 
397  struct Data;
398 
399 
400 
401  private:
402 
403  friend class InputFile;
404  friend class MultiPartInputFile;
405 
406  DeepTiledInputFile (InputPartData* part);
407 
408  DeepTiledInputFile (const DeepTiledInputFile &); // not implemented
409  DeepTiledInputFile & operator = (const DeepTiledInputFile &); // not implemented
410 
411  DeepTiledInputFile (const Header &header, OPENEXR_IMF_INTERNAL_NAMESPACE::IStream *is, int version,
412  int numThreads);
413 
414  void initialize ();
415  void multiPartInitialize(InputPartData* part);
416  void compatibilityInitialize(OPENEXR_IMF_INTERNAL_NAMESPACE::IStream& is);
417 
418  bool isValidTile (int dx, int dy,
419  int lx, int ly) const;
420 
421  size_t bytesPerLineForTile (int dx, int dy,
422  int lx, int ly) const;
423 
424 
425  void getTileOrder(int dx[],int dy[],int lx[],int ly[]) const;
426 
427 
428  Data * _data;
429 
430 
431  // needed for copyPixels
433 };
434 
436 
437 #endif
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
Definition: ImfNamespace.h:109
Box< V2i > Box2i
Definition: ImathBox.h:133
IMATH_INTERNAL_NAMESPACE_HEADER_ENTER typedef long long unsigned int Int64
Definition: ImathInt64.h:56
LevelRoundingMode
#define IMF_EXPORT
Definition: ImfExport.h:59
OPENVDB_API void initialize()
Global registration of basic types.
Definition: logging.h:318
void copyPixels(DeepTiledInputFile &in)
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:108