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