HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImfDeepTiledInputPart.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 IMFDEEPTILEDINPUTPART_H_
37 #define IMFDEEPTILEDINPUTPART_H_
38 
39 #include "ImfDeepTiledInputFile.h"
40 #include "ImfNamespace.h"
41 #include "ImfForward.h"
42 #include "ImfExport.h"
43 
45 
47 {
48  public:
49 
50  DeepTiledInputPart(MultiPartInputFile& multiPartFile, int partNumber);
51 
52  //------------------------
53  // Access to the file name
54  //------------------------
55 
56  const char * fileName () const;
57 
58 
59  //--------------------------
60  // Access to the file header
61  //--------------------------
62 
63  const Header & header () const;
64 
65 
66  //----------------------------------
67  // Access to the file format version
68  //----------------------------------
69 
70  int version () const;
71 
72 
73  //-----------------------------------------------------------
74  // Set the current frame buffer -- copies the FrameBuffer
75  // object into the TiledInputFile object.
76  //
77  // The current frame buffer is the destination for the pixel
78  // data read from the file. The current frame buffer must be
79  // set at least once before readTile() is called.
80  // The current frame buffer can be changed after each call
81  // to readTile().
82  //-----------------------------------------------------------
83 
84  void setFrameBuffer (const DeepFrameBuffer &frameBuffer);
85 
86 
87  //-----------------------------------
88  // Access to the current frame buffer
89  //-----------------------------------
90 
91  const DeepFrameBuffer & frameBuffer () const;
92 
93 
94  //------------------------------------------------------------
95  // Check if the file is complete:
96  //
97  // isComplete() returns true if all pixels in the data window
98  // (in all levels) are present in the input file, or false if
99  // any pixels are missing. (Another program may still be busy
100  // writing the file, or file writing may have been aborted
101  // prematurely.)
102  //------------------------------------------------------------
103 
104  bool isComplete () const;
105 
106 
107  //--------------------------------------------------
108  // Utility functions:
109  //--------------------------------------------------
110 
111  //---------------------------------------------------------
112  // Multiresolution mode and tile size:
113  // The following functions return the xSize, ySize and mode
114  // fields of the file header's TileDescriptionAttribute.
115  //---------------------------------------------------------
116 
117  unsigned int tileXSize () const;
118  unsigned int tileYSize () const;
119  LevelMode levelMode () const;
120  LevelRoundingMode levelRoundingMode () const;
121 
122 
123  //--------------------------------------------------------------------
124  // Number of levels:
125  //
126  // numXLevels() returns the file's number of levels in x direction.
127  //
128  // if levelMode() == ONE_LEVEL:
129  // return value is: 1
130  //
131  // if levelMode() == MIPMAP_LEVELS:
132  // return value is: rfunc (log (max (w, h)) / log (2)) + 1
133  //
134  // if levelMode() == RIPMAP_LEVELS:
135  // return value is: rfunc (log (w) / log (2)) + 1
136  //
137  // where
138  // w is the width of the image's data window, max.x - min.x + 1,
139  // y is the height of the image's data window, max.y - min.y + 1,
140  // and rfunc(x) is either floor(x), or ceil(x), depending on
141  // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
142  //
143  // numYLevels() returns the file's number of levels in y direction.
144  //
145  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
146  // return value is the same as for numXLevels()
147  //
148  // if levelMode() == RIPMAP_LEVELS:
149  // return value is: rfunc (log (h) / log (2)) + 1
150  //
151  //
152  // numLevels() is a convenience function for use with
153  // MIPMAP_LEVELS files.
154  //
155  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
156  // return value is the same as for numXLevels()
157  //
158  // if levelMode() == RIPMAP_LEVELS:
159  // an IEX_NAMESPACE::LogicExc exception is thrown
160  //
161  // isValidLevel(lx, ly) returns true if the file contains
162  // a level with level number (lx, ly), false if not.
163  //
164  //--------------------------------------------------------------------
165 
166  int numLevels () const;
167  int numXLevels () const;
168  int numYLevels () const;
169  bool isValidLevel (int lx, int ly) const;
170 
171 
172  //----------------------------------------------------------
173  // Dimensions of a level:
174  //
175  // levelWidth(lx) returns the width of a level with level
176  // number (lx, *), where * is any number.
177  //
178  // return value is:
179  // max (1, rfunc (w / pow (2, lx)))
180  //
181  //
182  // levelHeight(ly) returns the height of a level with level
183  // number (*, ly), where * is any number.
184  //
185  // return value is:
186  // max (1, rfunc (h / pow (2, ly)))
187  //
188  //----------------------------------------------------------
189 
190  int levelWidth (int lx) const;
191  int levelHeight (int ly) const;
192 
193 
194  //--------------------------------------------------------------
195  // Number of tiles:
196  //
197  // numXTiles(lx) returns the number of tiles in x direction
198  // that cover a level with level number (lx, *), where * is
199  // any number.
200  //
201  // return value is:
202  // (levelWidth(lx) + tileXSize() - 1) / tileXSize()
203  //
204  //
205  // numYTiles(ly) returns the number of tiles in y direction
206  // that cover a level with level number (*, ly), where * is
207  // any number.
208  //
209  // return value is:
210  // (levelHeight(ly) + tileXSize() - 1) / tileXSize()
211  //
212  //--------------------------------------------------------------
213 
214  int numXTiles (int lx = 0) const;
215  int numYTiles (int ly = 0) const;
216 
217 
218  //---------------------------------------------------------------
219  // Level pixel ranges:
220  //
221  // dataWindowForLevel(lx, ly) returns a 2-dimensional region of
222  // valid pixel coordinates for a level with level number (lx, ly)
223  //
224  // return value is a Box2i with min value:
225  // (dataWindow.min.x, dataWindow.min.y)
226  //
227  // and max value:
228  // (dataWindow.min.x + levelWidth(lx) - 1,
229  // dataWindow.min.y + levelHeight(ly) - 1)
230  //
231  // dataWindowForLevel(level) is a convenience function used
232  // for ONE_LEVEL and MIPMAP_LEVELS files. It returns
233  // dataWindowForLevel(level, level).
234  //
235  //---------------------------------------------------------------
236 
237  IMATH_NAMESPACE::Box2i dataWindowForLevel (int l = 0) const;
238  IMATH_NAMESPACE::Box2i dataWindowForLevel (int lx, int ly) const;
239 
240 
241  //-------------------------------------------------------------------
242  // Tile pixel ranges:
243  //
244  // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
245  // region of valid pixel coordinates for a tile with tile coordinates
246  // (dx,dy) and level number (lx, ly).
247  //
248  // return value is a Box2i with min value:
249  // (dataWindow.min.x + dx * tileXSize(),
250  // dataWindow.min.y + dy * tileYSize())
251  //
252  // and max value:
253  // (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
254  // dataWindow.min.y + (dy + 1) * tileYSize() - 1)
255  //
256  // dataWindowForTile(dx, dy, level) is a convenience function
257  // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns
258  // dataWindowForTile(dx, dy, level, level).
259  //
260  //-------------------------------------------------------------------
261 
262  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy, int l = 0) const;
263 
264  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy,
265  int lx, int ly) const;
266 
267  //------------------------------------------------------------
268  // Read pixel data:
269  //
270  // readTile(dx, dy, lx, ly) reads the tile with tile
271  // coordinates (dx, dy), and level number (lx, ly),
272  // and stores it in the current frame buffer.
273  //
274  // dx must lie in the interval [0, numXTiles(lx)-1]
275  // dy must lie in the interval [0, numYTiles(ly)-1]
276  //
277  // lx must lie in the interval [0, numXLevels()-1]
278  // ly must lie in the inverval [0, numYLevels()-1]
279  //
280  // readTile(dx, dy, level) is a convenience function used
281  // for ONE_LEVEL and MIPMAP_LEVELS files. It calls
282  // readTile(dx, dy, level, level).
283  //
284  // The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow
285  // reading multiple tiles at once. If multi-threading is used
286  // the multiple tiles are read concurrently.
287  //
288  // Pixels that are outside the pixel coordinate range for the
289  // tile's level, are never accessed by readTile().
290  //
291  // Attempting to access a tile that is not present in the file
292  // throws an InputExc exception.
293  //
294  //------------------------------------------------------------
295 
296  void readTile (int dx, int dy, int l = 0);
297  void readTile (int dx, int dy, int lx, int ly);
298 
299  void readTiles (int dx1, int dx2, int dy1, int dy2,
300  int lx, int ly);
301 
302  void readTiles (int dx1, int dx2, int dy1, int dy2,
303  int l = 0);
304 
305 
306  //--------------------------------------------------
307  // Read a tile of raw pixel data from the file,
308  // without uncompressing it (this function is
309  // used to implement TiledOutputFile::copyPixels()).
310  //--------------------------------------------------
311 
312  void rawTileData (int &dx, int &dy,
313  int &lx, int &ly,
314  char *data,
315  Int64 &dataSize
316  ) const;
317 
318  //------------------------------------------------------------------
319  // Read pixel sample counts into a slice in the frame buffer.
320  //
321  // readPixelSampleCount(dx, dy, lx, ly) reads the sample counts
322  // for tile (dx, dy) in level (lx, ly).
323  //
324  // readPixelSampleCount(dx, dy, l) calls
325  // readPixelSampleCount(dx, dy, lx = l, ly = l)
326  //
327  // dx must lie in the interval [0, numXTiles(lx)-1]
328  // dy must lie in the interval [0, numYTiles(ly)-1]
329  //
330  // lx must lie in the interval [0, numXLevels()-1]
331  // ly must lie in the inverval [0, numYLevels()-1]
332  //
333  // readPixelSampleCounts(dx1, dx2, dy1, dy2, lx, ly) reads all
334  // the sample counts for tiles within range
335  // [(min(dx1, dx2), min(dy1, dy2))...(max(dx1, dx2), max(dy1, dy2)],
336  // and on level (lx, ly)
337  //
338  // readPixelSampleCounts(dx1, dx2, dy1, dy2, l) calls
339  // readPixelSampleCounts(dx1, dx2, dy1, dy2, lx = l, ly = l).
340  //------------------------------------------------------------------
341 
342  void readPixelSampleCount (int dx, int dy, int l = 0);
343  void readPixelSampleCount (int dx, int dy, int lx, int ly);
344 
345  void readPixelSampleCounts (int dx1, int dx2,
346  int dy1, int dy2,
347  int lx, int ly);
348 
349  void readPixelSampleCounts (int dx1, int dx2,
350  int dy1, int dy2,
351  int l = 0);
352 
353  private:
354  DeepTiledInputFile* file;
355 
357 };
358 
360 
361 
362 #endif /* IMFDEEPTILEDINPUTPART_H_ */
#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
GLboolean * data
Definition: glcorearb.h:130
void copyPixels(DeepTiledInputFile &in)
GT_API const UT_StringHolder version
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
Definition: ImfNamespace.h:108