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