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