HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImfDeepTiledOutputFile.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 INCLUDED_IMF_DEEP_TILED_OUTPUT_FILE_H
7 #define INCLUDED_IMF_DEEP_TILED_OUTPUT_FILE_H
8 
9 //-----------------------------------------------------------------------------
10 //
11 // class DeepTiledOutputFile
12 //
13 //-----------------------------------------------------------------------------
14 
15 #include "ImfForward.h"
16 
17 #include "ImfThreading.h"
18 #include "ImfGenericOutputFile.h"
19 
20 #include "ImfTileDescription.h"
21 
22 #include <ImathBox.h>
23 
24 
26 
27 
29 {
30  public:
31 
32  //-------------------------------------------------------------------
33  // A constructor that opens the file with the specified name, and
34  // writes the file header. The file header is also copied into the
35  // TiledOutputFile object, and can later be accessed via the header()
36  // method.
37  //
38  // Destroying TiledOutputFile constructed with this constructor
39  // automatically closes the corresponding files.
40  //
41  // The header must contain a TileDescriptionAttribute called "tiles".
42  //
43  // The x and y subsampling factors for all image channels must be 1;
44  // subsampling is not supported.
45  //
46  // Tiles can be written to the file in arbitrary order. The line
47  // order attribute can be used to cause the tiles to be sorted in
48  // the file. When the file is read later, reading the tiles in the
49  // same order as they are in the file tends to be significantly
50  // faster than reading the tiles in random order (see writeTile,
51  // below).
52  //-------------------------------------------------------------------
53 
55  DeepTiledOutputFile (const char fileName[],
56  const Header &header,
57  int numThreads = globalThreadCount ());
58 
59 
60  // ----------------------------------------------------------------
61  // A constructor that attaches the new TiledOutputFile object to
62  // a file that has already been opened. Destroying TiledOutputFile
63  // objects constructed with this constructor does not automatically
64  // close the corresponding files.
65  // ----------------------------------------------------------------
66 
69  const Header &header,
70  int numThreads = globalThreadCount ());
71 
72 
73  //-----------------------------------------------------
74  // Destructor
75  //
76  // Destroying a TiledOutputFile object before all tiles
77  // have been written results in an incomplete file.
78  //-----------------------------------------------------
79 
81  virtual ~DeepTiledOutputFile ();
82 
83 
84  //------------------------
85  // Access to the file name
86  //------------------------
87 
89  const char * fileName () const;
90 
91 
92  //--------------------------
93  // Access to the file header
94  //--------------------------
95 
97  const Header & header () const;
98 
99 
100  //-------------------------------------------------------
101  // Set the current frame buffer -- copies the FrameBuffer
102  // object into the TiledOutputFile object.
103  //
104  // The current frame buffer is the source of the pixel
105  // data written to the file. The current frame buffer
106  // must be set at least once before writeTile() is
107  // called. The current frame buffer can be changed
108  // after each call to writeTile().
109  //-------------------------------------------------------
110 
111  IMF_EXPORT
112  void setFrameBuffer (const DeepFrameBuffer &frameBuffer);
113 
114 
115  //-----------------------------------
116  // Access to the current frame buffer
117  //-----------------------------------
118 
119  IMF_EXPORT
120  const DeepFrameBuffer & frameBuffer () const;
121 
122 
123  //-------------------
124  // Utility functions:
125  //-------------------
126 
127  //---------------------------------------------------------
128  // Multiresolution mode and tile size:
129  // The following functions return the xSize, ySize and mode
130  // fields of the file header's TileDescriptionAttribute.
131  //---------------------------------------------------------
132 
133  IMF_EXPORT
134  unsigned int tileXSize () const;
135  IMF_EXPORT
136  unsigned int tileYSize () const;
137  IMF_EXPORT
138  LevelMode levelMode () const;
139  IMF_EXPORT
140  LevelRoundingMode levelRoundingMode () const;
141 
142 
143  //--------------------------------------------------------------------
144  // Number of levels:
145  //
146  // numXLevels() returns the file's number of levels in x direction.
147  //
148  // if levelMode() == ONE_LEVEL:
149  // return value is: 1
150  //
151  // if levelMode() == MIPMAP_LEVELS:
152  // return value is: rfunc (log (max (w, h)) / log (2)) + 1
153  //
154  // if levelMode() == RIPMAP_LEVELS:
155  // return value is: rfunc (log (w) / log (2)) + 1
156  //
157  // where
158  // w is the width of the image's data window, max.x - min.x + 1,
159  // y is the height of the image's data window, max.y - min.y + 1,
160  // and rfunc(x) is either floor(x), or ceil(x), depending on
161  // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
162  //
163  // numYLevels() returns the file's number of levels in y direction.
164  //
165  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
166  // return value is the same as for numXLevels()
167  //
168  // if levelMode() == RIPMAP_LEVELS:
169  // return value is: rfunc (log (h) / log (2)) + 1
170  //
171  //
172  // numLevels() is a convenience function for use with MIPMAP_LEVELS
173  // files.
174  //
175  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
176  // return value is the same as for numXLevels()
177  //
178  // if levelMode() == RIPMAP_LEVELS:
179  // an IEX_NAMESPACE::LogicExc exception is thrown
180  //
181  // isValidLevel(lx, ly) returns true if the file contains
182  // a level with level number (lx, ly), false if not.
183  //
184  //--------------------------------------------------------------------
185 
186  IMF_EXPORT
187  int numLevels () const;
188  IMF_EXPORT
189  int numXLevels () const;
190  IMF_EXPORT
191  int numYLevels () const;
192  IMF_EXPORT
193  bool isValidLevel (int lx, int ly) const;
194 
195 
196  //---------------------------------------------------------
197  // Dimensions of a level:
198  //
199  // levelWidth(lx) returns the width of a level with level
200  // number (lx, *), where * is any number.
201  //
202  // return value is:
203  // max (1, rfunc (w / pow (2, lx)))
204  //
205  //
206  // levelHeight(ly) returns the height of a level with level
207  // number (*, ly), where * is any number.
208  //
209  // return value is:
210  // max (1, rfunc (h / pow (2, ly)))
211  //
212  //---------------------------------------------------------
213 
214  IMF_EXPORT
215  int levelWidth (int lx) const;
216  IMF_EXPORT
217  int levelHeight (int ly) const;
218 
219 
220  //----------------------------------------------------------
221  // Number of tiles:
222  //
223  // numXTiles(lx) returns the number of tiles in x direction
224  // that cover a level with level number (lx, *), where * is
225  // any number.
226  //
227  // return value is:
228  // (levelWidth(lx) + tileXSize() - 1) / tileXSize()
229  //
230  //
231  // numYTiles(ly) returns the number of tiles in y direction
232  // that cover a level with level number (*, ly), where * is
233  // any number.
234  //
235  // return value is:
236  // (levelHeight(ly) + tileXSize() - 1) / tileXSize()
237  //
238  //----------------------------------------------------------
239 
240  IMF_EXPORT
241  int numXTiles (int lx = 0) const;
242  IMF_EXPORT
243  int numYTiles (int ly = 0) const;
244 
245 
246  //---------------------------------------------------------
247  // Level pixel ranges:
248  //
249  // dataWindowForLevel(lx, ly) returns a 2-dimensional
250  // region of valid pixel coordinates for a level with
251  // level number (lx, ly)
252  //
253  // return value is a Box2i with min value:
254  // (dataWindow.min.x, dataWindow.min.y)
255  //
256  // and max value:
257  // (dataWindow.min.x + levelWidth(lx) - 1,
258  // dataWindow.min.y + levelHeight(ly) - 1)
259  //
260  // dataWindowForLevel(level) is a convenience function used
261  // for ONE_LEVEL and MIPMAP_LEVELS files. It returns
262  // dataWindowForLevel(level, level).
263  //
264  //---------------------------------------------------------
265 
266  IMF_EXPORT
267  IMATH_NAMESPACE::Box2i dataWindowForLevel (int l = 0) const;
268  IMF_EXPORT
269  IMATH_NAMESPACE::Box2i dataWindowForLevel (int lx, int ly) const;
270 
271 
272  //-------------------------------------------------------------------
273  // Tile pixel ranges:
274  //
275  // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
276  // region of valid pixel coordinates for a tile with tile coordinates
277  // (dx,dy) and level number (lx, ly).
278  //
279  // return value is a Box2i with min value:
280  // (dataWindow.min.x + dx * tileXSize(),
281  // dataWindow.min.y + dy * tileYSize())
282  //
283  // and max value:
284  // (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
285  // dataWindow.min.y + (dy + 1) * tileYSize() - 1)
286  //
287  // dataWindowForTile(dx, dy, level) is a convenience function
288  // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns
289  // dataWindowForTile(dx, dy, level, level).
290  //
291  //-------------------------------------------------------------------
292 
293  IMF_EXPORT
294  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy,
295  int l = 0) const;
296 
297  IMF_EXPORT
298  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy,
299  int lx, int ly) const;
300 
301  //------------------------------------------------------------------
302  // Write pixel data:
303  //
304  // writeTile(dx, dy, lx, ly) writes the tile with tile
305  // coordinates (dx, dy), and level number (lx, ly) to
306  // the file.
307  //
308  // dx must lie in the interval [0, numXTiles(lx) - 1]
309  // dy must lie in the interval [0, numYTiles(ly) - 1]
310  //
311  // lx must lie in the interval [0, numXLevels() - 1]
312  // ly must lie in the inverval [0, numYLevels() - 1]
313  //
314  // writeTile(dx, dy, level) is a convenience function
315  // used for ONE_LEVEL and MIPMAP_LEVEL files. It calls
316  // writeTile(dx, dy, level, level).
317  //
318  // The two writeTiles(dx1, dx2, dy1, dy2, ...) functions allow
319  // writing multiple tiles at once. If multi-threading is used
320  // multiple tiles are written concurrently. The tile coordinates,
321  // dx1, dx2 and dy1, dy2, specify inclusive ranges of tile
322  // coordinates. It is valid for dx1 < dx2 or dy1 < dy2; the
323  // tiles are always written in the order specified by the line
324  // order attribute. Hence, it is not possible to specify an
325  // "invalid" or empty tile range.
326  //
327  // Pixels that are outside the pixel coordinate range for the tile's
328  // level, are never accessed by writeTile().
329  //
330  // Each tile in the file must be written exactly once.
331  //
332  // The file's line order attribute determines the order of the tiles
333  // in the file:
334  //
335  // INCREASING_Y In the file, the tiles for each level are stored
336  // in a contiguous block. The levels are ordered
337  // like this:
338  //
339  // (0, 0) (1, 0) ... (nx-1, 0)
340  // (0, 1) (1, 1) ... (nx-1, 1)
341  // ...
342  // (0,ny-1) (1,ny-1) ... (nx-1,ny-1)
343  //
344  // where nx = numXLevels(), and ny = numYLevels().
345  // In an individual level, (lx, ly), the tiles
346  // are stored in the following order:
347  //
348  // (0, 0) (1, 0) ... (tx-1, 0)
349  // (0, 1) (1, 1) ... (tx-1, 1)
350  // ...
351  // (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
352  //
353  // where tx = numXTiles(lx),
354  // and ty = numYTiles(ly).
355  //
356  // DECREASING_Y As for INCREASING_Y, the tiles for each level
357  // are stored in a contiguous block. The levels
358  // are ordered the same way as for INCREASING_Y,
359  // but within an individual level, the tiles
360  // are stored in this order:
361  //
362  // (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
363  // ...
364  // (0, 1) (1, 1) ... (tx-1, 1)
365  // (0, 0) (1, 0) ... (tx-1, 0)
366  //
367  //
368  // RANDOM_Y The order of the calls to writeTile() determines
369  // the order of the tiles in the file.
370  //
371  //------------------------------------------------------------------
372 
373  IMF_EXPORT
374  void writeTile (int dx, int dy, int l = 0);
375  IMF_EXPORT
376  void writeTile (int dx, int dy, int lx, int ly);
377 
378  IMF_EXPORT
379  void writeTiles (int dx1, int dx2, int dy1, int dy2,
380  int lx, int ly);
381 
382  IMF_EXPORT
383  void writeTiles (int dx1, int dx2, int dy1, int dy2,
384  int l = 0);
385 
386 
387  //------------------------------------------------------------------
388  // Shortcut to copy all pixels from a TiledInputFile into this file,
389  // without uncompressing and then recompressing the pixel data.
390  // This file's header must be compatible with the TiledInputFile's
391  // header: The two header's "dataWindow", "compression",
392  // "lineOrder", "channels", and "tiles" attributes must be the same.
393  //------------------------------------------------------------------
394 
395  IMF_EXPORT
396  void copyPixels (DeepTiledInputFile &in);
397  IMF_EXPORT
398  void copyPixels (DeepTiledInputPart &in);
399 
400 
401 
402  //--------------------------------------------------------------
403  // Updating the preview image:
404  //
405  // updatePreviewImage() supplies a new set of pixels for the
406  // preview image attribute in the file's header. If the header
407  // does not contain a preview image, updatePreviewImage() throws
408  // an IEX_NAMESPACE::LogicExc.
409  //
410  // Note: updatePreviewImage() is necessary because images are
411  // often stored in a file incrementally, a few tiles at a time,
412  // while the image is being generated. Since the preview image
413  // is an attribute in the file's header, it gets stored in the
414  // file as soon as the file is opened, but we may not know what
415  // the preview image should look like until we have written the
416  // last tile of the main image.
417  //
418  //--------------------------------------------------------------
419 
420  IMF_EXPORT
421  void updatePreviewImage (const PreviewRgba newPixels[]);
422 
423 
424  //-------------------------------------------------------------
425  // Break a tile -- for testing and debugging only:
426  //
427  // breakTile(dx,dy,lx,ly,p,n,c) introduces an error into the
428  // output file by writing n copies of character c, starting
429  // p bytes from the beginning of the tile with tile coordinates
430  // (dx, dy) and level number (lx, ly).
431  //
432  // Warning: Calling this function usually results in a broken
433  // image file. The file or parts of it may not be readable,
434  // or the file may contain bad data.
435  //
436  //-------------------------------------------------------------
437 
438  IMF_EXPORT
439  void breakTile (int dx, int dy,
440  int lx, int ly,
441  int offset,
442  int length,
443  char c);
444  struct Data;
445 
446  private:
447 
448  // ----------------------------------------------------------------
449  // A constructor attaches the OutputStreamMutex to the
450  // given one from MultiPartOutputFile. Set the previewPosition
451  // and lineOffsetsPosition which have been acquired from
452  // the constructor of MultiPartOutputFile as well.
453  // ----------------------------------------------------------------
454  DeepTiledOutputFile (const OutputPartData* part);
455 
456  DeepTiledOutputFile (const DeepTiledOutputFile &) = delete;
457  DeepTiledOutputFile & operator = (const DeepTiledOutputFile &) = delete;
458  DeepTiledOutputFile (DeepTiledOutputFile &&) = delete;
459  DeepTiledOutputFile & operator = (DeepTiledOutputFile &&) = delete;
460 
461  void initialize (const Header &header);
462 
463  bool isValidTile (int dx, int dy,
464  int lx, int ly) const;
465 
466  size_t bytesPerLineForTile (int dx, int dy,
467  int lx, int ly) const;
468 
469  Data * _data;
470 
471 
472  friend class MultiPartOutputFile;
473 
474 };
475 
476 
478 
479 #endif
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
Definition: ImfNamespace.h:80
const GLfloat * c
Definition: glew.h:16631
GLuint in
Definition: glew.h:11552
enum IMF_EXPORT_ENUM LevelRoundingMode
GLdouble l
Definition: glew.h:9164
Box< V2i > Box2i
2D box of base type int.
Definition: ImathBox.h:143
#define IMF_EXPORT
Definition: ImfExport.h:54
OPENVDB_API void initialize()
Global registration of native Grid, Transform, Metadata and Point attribute types. Also initializes blosc (if enabled).
Definition: logging.h:294
class IMF_EXPORT_TYPE OStream
Definition: ImfForward.h:88
GLuint GLsizei GLsizei * length
Definition: glcorearb.h:795
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER IMF_EXPORT int globalThreadCount()
class IMF_EXPORT_TYPE DeepTiledOutputFile
Definition: ImfForward.h:42
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
Definition: ImfNamespace.h:79
GLintptr offset
Definition: glcorearb.h:665
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER enum IMF_EXPORT_ENUM LevelMode
#define IMF_EXPORT_TYPE
Definition: ImfExport.h:57