HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
ImfDeepTiledOutputPart.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 #ifndef IMFDEEPTILEDOUTPUTPART_H_
36 #define IMFDEEPTILEDOUTPUTPART_H_
37 
38 #include "ImfForward.h"
39 #include "ImfDeepTiledInputFile.h"
40 #include "ImfNamespace.h"
41 #include "ImfExport.h"
42 
43 
45 
46 
48 {
49  public:
50 
51  DeepTiledOutputPart(MultiPartOutputFile& multiPartFile, int partNumber);
52 
53  //------------------------
54  // Access to the file name
55  //------------------------
56 
57  const char * fileName () const;
58 
59 
60  //--------------------------
61  // Access to the file header
62  //--------------------------
63 
64  const Header & header () const;
65 
66 
67  //-------------------------------------------------------
68  // Set the current frame buffer -- copies the FrameBuffer
69  // object into the TiledOutputFile object.
70  //
71  // The current frame buffer is the source of the pixel
72  // data written to the file. The current frame buffer
73  // must be set at least once before writeTile() is
74  // called. The current frame buffer can be changed
75  // after each call to writeTile().
76  //-------------------------------------------------------
77 
78  void setFrameBuffer (const DeepFrameBuffer &frameBuffer);
79 
80 
81  //-----------------------------------
82  // Access to the current frame buffer
83  //-----------------------------------
84 
85  const DeepFrameBuffer & frameBuffer () const;
86 
87 
88  //-------------------
89  // Utility functions:
90  //-------------------
91 
92  //---------------------------------------------------------
93  // Multiresolution mode and tile size:
94  // The following functions return the xSize, ySize and mode
95  // fields of the file header's TileDescriptionAttribute.
96  //---------------------------------------------------------
97 
98  unsigned int tileXSize () const;
99  unsigned int tileYSize () const;
100  LevelMode levelMode () const;
101  LevelRoundingMode levelRoundingMode () const;
102 
103 
104  //--------------------------------------------------------------------
105  // Number of levels:
106  //
107  // numXLevels() returns the file's number of levels in x direction.
108  //
109  // if levelMode() == ONE_LEVEL:
110  // return value is: 1
111  //
112  // if levelMode() == MIPMAP_LEVELS:
113  // return value is: rfunc (log (max (w, h)) / log (2)) + 1
114  //
115  // if levelMode() == RIPMAP_LEVELS:
116  // return value is: rfunc (log (w) / log (2)) + 1
117  //
118  // where
119  // w is the width of the image's data window, max.x - min.x + 1,
120  // y is the height of the image's data window, max.y - min.y + 1,
121  // and rfunc(x) is either floor(x), or ceil(x), depending on
122  // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
123  //
124  // numYLevels() returns the file's number of levels in y direction.
125  //
126  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
127  // return value is the same as for numXLevels()
128  //
129  // if levelMode() == RIPMAP_LEVELS:
130  // return value is: rfunc (log (h) / log (2)) + 1
131  //
132  //
133  // numLevels() is a convenience function for use with MIPMAP_LEVELS
134  // files.
135  //
136  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
137  // return value is the same as for numXLevels()
138  //
139  // if levelMode() == RIPMAP_LEVELS:
140  // an IEX_NAMESPACE::LogicExc exception is thrown
141  //
142  // isValidLevel(lx, ly) returns true if the file contains
143  // a level with level number (lx, ly), false if not.
144  //
145  //--------------------------------------------------------------------
146 
147  int numLevels () const;
148  int numXLevels () const;
149  int numYLevels () const;
150  bool isValidLevel (int lx, int ly) const;
151 
152 
153  //---------------------------------------------------------
154  // Dimensions of a level:
155  //
156  // levelWidth(lx) returns the width of a level with level
157  // number (lx, *), where * is any number.
158  //
159  // return value is:
160  // max (1, rfunc (w / pow (2, lx)))
161  //
162  //
163  // levelHeight(ly) returns the height of a level with level
164  // number (*, ly), where * is any number.
165  //
166  // return value is:
167  // max (1, rfunc (h / pow (2, ly)))
168  //
169  //---------------------------------------------------------
170 
171  int levelWidth (int lx) const;
172  int levelHeight (int ly) const;
173 
174 
175  //----------------------------------------------------------
176  // Number of tiles:
177  //
178  // numXTiles(lx) returns the number of tiles in x direction
179  // that cover a level with level number (lx, *), where * is
180  // any number.
181  //
182  // return value is:
183  // (levelWidth(lx) + tileXSize() - 1) / tileXSize()
184  //
185  //
186  // numYTiles(ly) returns the number of tiles in y direction
187  // that cover a level with level number (*, ly), where * is
188  // any number.
189  //
190  // return value is:
191  // (levelHeight(ly) + tileXSize() - 1) / tileXSize()
192  //
193  //----------------------------------------------------------
194 
195  int numXTiles (int lx = 0) const;
196  int numYTiles (int ly = 0) const;
197 
198 
199  //---------------------------------------------------------
200  // Level pixel ranges:
201  //
202  // dataWindowForLevel(lx, ly) returns a 2-dimensional
203  // region of valid pixel coordinates for a level with
204  // level number (lx, ly)
205  //
206  // return value is a Box2i with min value:
207  // (dataWindow.min.x, dataWindow.min.y)
208  //
209  // and max value:
210  // (dataWindow.min.x + levelWidth(lx) - 1,
211  // dataWindow.min.y + levelHeight(ly) - 1)
212  //
213  // dataWindowForLevel(level) is a convenience function used
214  // for ONE_LEVEL and MIPMAP_LEVELS files. It returns
215  // dataWindowForLevel(level, level).
216  //
217  //---------------------------------------------------------
218 
219  IMATH_NAMESPACE::Box2i dataWindowForLevel (int l = 0) const;
220  IMATH_NAMESPACE::Box2i dataWindowForLevel (int lx, int ly) const;
221 
222 
223  //-------------------------------------------------------------------
224  // Tile pixel ranges:
225  //
226  // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
227  // region of valid pixel coordinates for a tile with tile coordinates
228  // (dx,dy) and level number (lx, ly).
229  //
230  // return value is a Box2i with min value:
231  // (dataWindow.min.x + dx * tileXSize(),
232  // dataWindow.min.y + dy * tileYSize())
233  //
234  // and max value:
235  // (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
236  // dataWindow.min.y + (dy + 1) * tileYSize() - 1)
237  //
238  // dataWindowForTile(dx, dy, level) is a convenience function
239  // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns
240  // dataWindowForTile(dx, dy, level, level).
241  //
242  //-------------------------------------------------------------------
243 
244  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy,
245  int l = 0) const;
246 
247  IMATH_NAMESPACE::Box2i dataWindowForTile (int dx, int dy,
248  int lx, int ly) const;
249 
250  //------------------------------------------------------------------
251  // Write pixel data:
252  //
253  // writeTile(dx, dy, lx, ly) writes the tile with tile
254  // coordinates (dx, dy), and level number (lx, ly) to
255  // the file.
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 inverval [0, numYLevels() - 1]
262  //
263  // writeTile(dx, dy, level) is a convenience function
264  // used for ONE_LEVEL and MIPMAP_LEVEL files. It calls
265  // writeTile(dx, dy, level, level).
266  //
267  // The two writeTiles(dx1, dx2, dy1, dy2, ...) functions allow
268  // writing multiple tiles at once. If multi-threading is used
269  // multiple tiles are written concurrently. The tile coordinates,
270  // dx1, dx2 and dy1, dy2, specify inclusive ranges of tile
271  // coordinates. It is valid for dx1 < dx2 or dy1 < dy2; the
272  // tiles are always written in the order specified by the line
273  // order attribute. Hence, it is not possible to specify an
274  // "invalid" or empty tile range.
275  //
276  // Pixels that are outside the pixel coordinate range for the tile's
277  // level, are never accessed by writeTile().
278  //
279  // Each tile in the file must be written exactly once.
280  //
281  // The file's line order attribute determines the order of the tiles
282  // in the file:
283  //
284  // INCREASING_Y In the file, the tiles for each level are stored
285  // in a contiguous block. The levels are ordered
286  // like this:
287  //
288  // (0, 0) (1, 0) ... (nx-1, 0)
289  // (0, 1) (1, 1) ... (nx-1, 1)
290  // ...
291  // (0,ny-1) (1,ny-1) ... (nx-1,ny-1)
292  //
293  // where nx = numXLevels(), and ny = numYLevels().
294  // In an individual level, (lx, ly), the tiles
295  // are stored in the following order:
296  //
297  // (0, 0) (1, 0) ... (tx-1, 0)
298  // (0, 1) (1, 1) ... (tx-1, 1)
299  // ...
300  // (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
301  //
302  // where tx = numXTiles(lx),
303  // and ty = numYTiles(ly).
304  //
305  // DECREASING_Y As for INCREASING_Y, the tiles for each level
306  // are stored in a contiguous block. The levels
307  // are ordered the same way as for INCREASING_Y,
308  // but within an individual level, the tiles
309  // are stored in this order:
310  //
311  // (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
312  // ...
313  // (0, 1) (1, 1) ... (tx-1, 1)
314  // (0, 0) (1, 0) ... (tx-1, 0)
315  //
316  //
317  // RANDOM_Y The order of the calls to writeTile() determines
318  // the order of the tiles in the file.
319  //
320  //------------------------------------------------------------------
321 
322  void writeTile (int dx, int dy, int l = 0);
323  void writeTile (int dx, int dy, int lx, int ly);
324 
325  void writeTiles (int dx1, int dx2, int dy1, int dy2,
326  int lx, int ly);
327 
328  void writeTiles (int dx1, int dx2, int dy1, int dy2,
329  int l = 0);
330 
331 
332  //------------------------------------------------------------------
333  // Shortcut to copy all pixels from a TiledInputFile into this file,
334  // without uncompressing and then recompressing the pixel data.
335  // This file's header must be compatible with the TiledInputFile's
336  // header: The two header's "dataWindow", "compression",
337  // "lineOrder", "channels", and "tiles" attributes must be the same.
338  //------------------------------------------------------------------
339 
340  void copyPixels (DeepTiledInputFile &in);
341  void copyPixels (DeepTiledInputPart &in);
342 
343 
344 
345 
346  //--------------------------------------------------------------
347  // Updating the preview image:
348  //
349  // updatePreviewImage() supplies a new set of pixels for the
350  // preview image attribute in the file's header. If the header
351  // does not contain a preview image, updatePreviewImage() throws
352  // an IEX_NAMESPACE::LogicExc.
353  //
354  // Note: updatePreviewImage() is necessary because images are
355  // often stored in a file incrementally, a few tiles at a time,
356  // while the image is being generated. Since the preview image
357  // is an attribute in the file's header, it gets stored in the
358  // file as soon as the file is opened, but we may not know what
359  // the preview image should look like until we have written the
360  // last tile of the main image.
361  //
362  //--------------------------------------------------------------
363 
364  void updatePreviewImage (const PreviewRgba newPixels[]);
365 
366 
367  //-------------------------------------------------------------
368  // Break a tile -- for testing and debugging only:
369  //
370  // breakTile(dx,dy,lx,ly,p,n,c) introduces an error into the
371  // output file by writing n copies of character c, starting
372  // p bytes from the beginning of the tile with tile coordinates
373  // (dx, dy) and level number (lx, ly).
374  //
375  // Warning: Calling this function usually results in a broken
376  // image file. The file or parts of it may not be readable,
377  // or the file may contain bad data.
378  //
379  //-------------------------------------------------------------
380 
381  void breakTile (int dx, int dy,
382  int lx, int ly,
383  int offset,
384  int length,
385  char c);
386 
387  private:
388  DeepTiledOutputFile* file;
389 
390 };
391 
393 
394 #endif /* IMFDEEPTILEDOUTPUTPART_H_ */
#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
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
Definition: ImfNamespace.h:108
GLuint GLsizei GLsizei * length
Definition: glcorearb.h:794