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