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