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