source: NonGTP/OpenEXR/include/IlmImf/ImfTiledOutputFile.h @ 855

Revision 855, 15.3 KB checked in by igarcia, 19 years ago (diff)
Line 
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
50namespace Imf {
51
52class TiledInputFile;
53class InputFile;
54struct PreviewRgba;
55
56
57class TiledOutputFile
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 be sorted in the file.
77    // When the file is read later, reading the tiles in the same order
78    // as they are in the file tends to be significantly faster than
79    // reading the tiles in random order (see writeTile, below).
80    //-------------------------------------------------------------------
81   
82    TiledOutputFile (const char fileName[], const Header &header);
83
84
85    // ----------------------------------------------------------------
86    // A constructor that attaches the new TiledOutputFile object to
87    // a file that has already been opened.  Destroying TiledOutputFile
88    // objects constructed with this constructor does not automatically
89    // closse the corresponding files.
90    // ----------------------------------------------------------------
91
92    TiledOutputFile (OStream &os, const Header &header);
93
94
95    //-----------------------------------------------------
96    // Destructor
97    //
98    // Destroying a TiledOutputFile object before all tiles
99    // have been written results in an incomplete file.
100    //-----------------------------------------------------
101   
102    virtual ~TiledOutputFile ();
103
104
105    //------------------------
106    // Access to the file name
107    //------------------------
108   
109    const char *        fileName () const;
110
111
112    //--------------------------
113    // Access to the file header
114    //--------------------------
115   
116    const Header &      header () const;
117
118
119    //-------------------------------------------------------
120    // Set the current frame buffer -- copies the FrameBuffer
121    // object into the TiledOutputFile object.
122    //
123    // The current frame buffer is the source of the pixel
124    // data written to the file.  The current frame buffer
125    // must be set at least once before writeTile() is
126    // called.  The current frame buffer can be changed
127    // after each call to writeTile().
128    //-------------------------------------------------------
129   
130    void                setFrameBuffer (const FrameBuffer &frameBuffer);
131
132
133    //-----------------------------------
134    // Access to the current frame buffer
135    //-----------------------------------
136   
137    const FrameBuffer & frameBuffer () const;
138
139
140    //-------------------
141    // Utility functions:
142    //-------------------
143
144    //---------------------------------------------------------
145    // Multiresolution mode and tile size:
146    // The following functions return the xSize, ySize and mode
147    // fields of the file header's TileDescriptionAttribute.
148    //---------------------------------------------------------
149
150    unsigned int        tileXSize () const;
151    unsigned int        tileYSize () const;
152    LevelMode           levelMode () const;
153    LevelRoundingMode   levelRoundingMode () const;
154
155
156    //--------------------------------------------------------------------
157    // Number of levels:
158    //
159    // numXLevels() returns the file's number of levels in x direction.
160    //
161    //  if levelMode() == ONE_LEVEL:
162    //      return value is: 1
163    //
164    //  if levelMode() == MIPMAP_LEVELS:
165    //      return value is: rfunc (log (max (w, h)) / log (2)) + 1
166    //
167    //  if levelMode() == RIPMAP_LEVELS:
168    //      return value is: rfunc (log (w) / log (2)) + 1
169    //
170    //  where
171    //      w is the width of the image's data window,  max.x - min.x + 1,
172    //      y is the height of the image's data window, max.y - min.y + 1,
173    //      and rfunc(x) is either floor(x), or ceil(x), depending on
174    //      whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
175    //
176    // numYLevels() returns the file's number of levels in y direction.
177    //
178    //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
179    //      return value is the same as for numXLevels()
180    //
181    //  if levelMode() == RIPMAP_LEVELS:
182    //      return value is: rfunc (log (h) / log (2)) + 1
183    //
184    //
185    // numLevels() is a convenience function for use with MIPMAP_LEVELS
186    // files.
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    //      an Iex::LogicExc exception is thrown
193    //
194    // isValidLevel(lx, ly) returns true if the file contains
195    // a level with level number (lx, ly), false if not.
196    //
197    //--------------------------------------------------------------------
198
199    int                 numLevels () const;
200    int                 numXLevels () const;
201    int                 numYLevels () const;
202    bool                isValidLevel (int lx, int ly) const;
203
204
205    //---------------------------------------------------------
206    // Dimensions of a level:
207    //
208    // levelWidth(lx) returns the width of a level with level
209    // number (lx, *), where * is any number.
210    //
211    //  return value is:
212    //      max (1, rfunc (w / pow (2, lx)))
213    //
214    //
215    // levelHeight(ly) returns the height of a level with level
216    // number (*, ly), where * is any number.
217    //
218    //  return value is:
219    //      max (1, rfunc (h / pow (2, ly)))
220    //
221    //---------------------------------------------------------
222
223    int                 levelWidth  (int lx) const;
224    int                 levelHeight (int ly) const;
225
226
227    //----------------------------------------------------------
228    // Number of tiles:
229    //
230    // numXTiles(lx) returns the number of tiles in x direction
231    // that cover a level with level number (lx, *), where * is
232    // any number.
233    //
234    //  return value is:
235    //      (levelWidth(lx) + tileXSize() - 1) / tileXSize()
236    //
237    //
238    // numYTiles(ly) returns the number of tiles in y direction
239    // that cover a level with level number (*, ly), where * is
240    // any number.
241    //
242    //  return value is:
243    //      (levelHeight(ly) + tileXSize() - 1) / tileXSize()
244    //
245    //----------------------------------------------------------
246
247    int                 numXTiles (int lx = 0) const;
248    int                 numYTiles (int ly = 0) const;
249
250
251    //---------------------------------------------------------
252    // Level pixel ranges:
253    //
254    // dataWindowForLevel(lx, ly) returns a 2-dimensional
255    // region of valid pixel coordinates for a level with
256    // level number (lx, ly)
257    //
258    //  return value is a Box2i with min value:
259    //      (dataWindow.min.x, dataWindow.min.y)
260    //
261    //  and max value:
262    //      (dataWindow.min.x + levelWidth(lx) - 1,
263    //       dataWindow.min.y + levelHeight(ly) - 1)
264    //
265    // dataWindowForLevel(level) is a convenience function used
266    // for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
267    // dataWindowForLevel(level, level).
268    //
269    //---------------------------------------------------------
270
271    Imath::Box2i        dataWindowForLevel (int l = 0) const;
272    Imath::Box2i        dataWindowForLevel (int lx, int ly) const;
273
274
275    //-------------------------------------------------------------------
276    // Tile pixel ranges:
277    //
278    // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
279    // region of valid pixel coordinates for a tile with tile coordinates
280    // (dx,dy) and level number (lx, ly).
281    //
282    //  return value is a Box2i with min value:
283    //      (dataWindow.min.x + dx * tileXSize(),
284    //       dataWindow.min.y + dy * tileYSize())
285    //
286    //  and max value:
287    //      (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
288    //       dataWindow.min.y + (dy + 1) * tileYSize() - 1)
289    //
290    // dataWindowForTile(dx, dy, level) is a convenience function
291    // used for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
292    // dataWindowForTile(dx, dy, level, level).
293    //
294    //-------------------------------------------------------------------
295
296    Imath::Box2i        dataWindowForTile (int dx, int dy,
297                                           int l = 0) const;
298
299    Imath::Box2i        dataWindowForTile (int dx, int dy,
300                                           int lx, int ly) const;
301
302    //------------------------------------------------------------------
303    // Write pixel data:
304    //
305    // writeTile(dx, dy, lx, ly) writes the tile with tile
306    // coordinates (dx, dy), and level number (lx, ly) to
307    // the file.
308    //
309    //   dx must lie in the interval [0, numXTiles(lx) - 1]
310    //   dy must lie in the interval [0, numYTiles(ly) - 1]
311    //
312    //   lx must lie in the interval [0, numXLevels() - 1]
313    //   ly must lie in the inverval [0, numYLevels() - 1]
314    //
315    // writeTile(dx, dy, level) is a convenience function
316    // used for ONE_LEVEL and MIPMAP_LEVEL files.  It calls
317    // writeTile(dx, dy, level, level).
318    //
319    // Pixels that are outside the pixel coordinate range for the tile's
320    // level, are never accessed by writeTile().
321    //
322    // Each tile in the file must be written exactly once.
323    //
324    // The file's line order attribute determines the order of the tiles
325    // in the file:
326    //
327    //   INCREASING_Y   In the file, the tiles for each level are stored
328    //                  in a contiguous block.  The levels are ordered
329    //                  like this:
330    //
331    //                      (0, 0)   (1, 0)   ... (nx-1, 0)
332    //                      (0, 1)   (1, 1)   ... (nx-1, 1)
333    //                       ...
334    //                      (0,ny-1) (1,ny-1) ... (nx-1,ny-1)
335    //
336    //                  where nx = numXLevels(), and ny = numYLevels().
337    //                  In an individual level, (lx, ly), the tiles
338    //                  are stored in the following order:
339    //
340    //                      (0, 0)   (1, 0)   ... (tx-1, 0)
341    //                      (0, 1)   (1, 1)   ... (tx-1, 1)
342    //                       ...
343    //                      (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
344    //
345    //                  where tx = numXTiles(lx),
346    //                  and   ty = numYTiles(ly).
347    //
348    //   DECREASING_Y   As for INCREASING_Y, the tiles for each level
349    //                  are stored in a contiguous block.  The levels
350    //                  are ordered the same way as for INCREASING_Y,
351    //                  but within an individual level, the tiles
352    //                  are stored in this order:
353    //
354    //                      (0,ty-1) (1,ty-1) ... (tx-1,ty-1)
355    //                       ...
356    //                      (0, 1)   (1, 1)   ... (tx-1, 1)
357    //                      (0, 0)   (1, 0)   ... (tx-1, 0)
358    //
359    //
360    //   RANDOM_Y       The order of the calls to writeTile() determines
361    //                  the order of the tiles in the file.
362    //
363    //------------------------------------------------------------------
364
365    void                writeTile (int dx, int dy, int l = 0);
366    void                writeTile (int dx, int dy, int lx, int ly);
367
368
369    //------------------------------------------------------------------
370    // Shortcut to copy all pixels from a TiledInputFile into this file,
371    // without uncompressing and then recompressing the pixel data.
372    // This file's header must be compatible with the TiledInputFile's
373    // header:  The two header's "dataWindow", "compression",
374    // "lineOrder", "channels", and "tiles" attributes must be the same.
375    //------------------------------------------------------------------
376   
377    void                copyPixels (TiledInputFile &in);
378   
379
380    //------------------------------------------------------------------
381    // Shortcut to copy all pixels from an InputFile into this file,
382    // without uncompressing and then recompressing the pixel data.
383    // This file's header must be compatible with the InputFile's
384    // header:  The two header's "dataWindow", "compression",
385    // "lineOrder", "channels", and "tiles" attributes must be the same.
386    //
387    // To use this function, the InputFile must be tiled.
388    //------------------------------------------------------------------
389   
390    void                copyPixels (InputFile &in);
391
392
393    //--------------------------------------------------------------
394    // Updating the preview image:
395    //
396    // updatePreviewImage() supplies a new set of pixels for the
397    // preview image attribute in the file's header.  If the header
398    // does not contain a preview image, updatePreviewImage() throws
399    // an Iex::LogicExc.
400    //
401    // Note: updatePreviewImage() is necessary because images are
402    // often stored in a file incrementally, a few tiles at a time,
403    // while the image is being generated.  Since the preview image
404    // is an attribute in the file's header, it gets stored in the
405    // file as soon as the file is opened, but we may not know what
406    // the preview image should look like until we have written the
407    // last tile of the main image.
408    //
409    //--------------------------------------------------------------
410
411    void                updatePreviewImage (const PreviewRgba newPixels[]);
412
413
414    struct Data;
415
416  private:
417
418    TiledOutputFile (const TiledOutputFile &);              // not implemented
419    TiledOutputFile & operator = (const TiledOutputFile &); // not implemented
420
421    void                initialize (const Header &header);
422
423    bool                isValidTile (int dx, int dy,
424                                     int lx, int ly) const;
425
426    size_t              bytesPerLineForTile (int dx, int dy,
427                                             int lx, int ly) const;
428
429    Data *              _data;
430};
431
432
433} // namespace Imf
434
435#endif
Note: See TracBrowser for help on using the repository browser.