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