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

Revision 855, 12.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_INPUT_FILE_H
37#define INCLUDED_IMF_TILED_INPUT_FILE_H
38
39//-----------------------------------------------------------------------------
40//
41//      class TiledInputFile
42//
43//-----------------------------------------------------------------------------
44
45#include <ImfHeader.h>
46#include <ImfFrameBuffer.h>
47#include <ImathBox.h>
48#include <ImfTileDescription.h>
49
50namespace Imf {
51
52
53class TiledInputFile
54{
55  public:
56
57    //--------------------------------------------------------------------
58    // A constructor that opens the file with the specified name, and
59    // reads the file header.  The constructor throws an Iex::ArgExc
60    // exception if the file is not tiled.
61    // Destroying TiledInputFile objects constructed with this constructor
62    // automatically closes the corresponding files.
63    //--------------------------------------------------------------------
64
65    TiledInputFile (const char fileName[]);
66
67   
68    // ----------------------------------------------------------
69    // A constructor that attaches the new TiledInputFile object
70    // to a file that has already been opened. 
71    // Destroying TiledInputFile objects constructed with this
72    // constructor does not automatically close the corresponding
73    // files.
74    // ----------------------------------------------------------
75
76    TiledInputFile (IStream &is);
77
78
79    //-----------
80    // Destructor
81    //-----------
82
83    virtual ~TiledInputFile ();
84
85
86    //------------------------
87    // Access to the file name
88    //------------------------
89
90    const char *        fileName () const;
91
92
93    //--------------------------
94    // Access to the file header
95    //--------------------------
96
97    const Header &      header () const;
98
99
100    //----------------------------------
101    // Access to the file format version
102    //----------------------------------
103
104    int                 version () const;
105
106
107    //-----------------------------------------------------------
108    // Set the current frame buffer -- copies the FrameBuffer
109    // object into the TiledInputFile object.
110    //
111    // The current frame buffer is the destination for the pixel
112    // data read from the file.  The current frame buffer must be
113    // set at least once before readTile() is called.
114    // The current frame buffer can be changed after each call
115    // to readTile().
116    //-----------------------------------------------------------
117
118    void                setFrameBuffer (const FrameBuffer &frameBuffer);
119
120
121    //-----------------------------------
122    // Access to the current frame buffer
123    //-----------------------------------
124
125    const FrameBuffer & frameBuffer () const;
126
127
128    //------------------------------------------------------------
129    // Check if the file is complete:
130    //
131    // isComplete() returns true if all pixels in the data window
132    // (in all levels) are present in the input file, or false if
133    // any pixels are missing.  (Another program may still be busy
134    // writing the file, or file writing may have been aborted
135    // prematurely.)
136    //------------------------------------------------------------
137
138    bool                isComplete () const;
139
140
141    //--------------------------------------------------
142    // Utility functions:
143    //--------------------------------------------------
144
145    //---------------------------------------------------------
146    // Multiresolution mode and tile size:
147    // The following functions return the xSize, ySize and mode
148    // fields of the file header's TileDescriptionAttribute.
149    //---------------------------------------------------------
150
151    unsigned int        tileXSize () const;
152    unsigned int        tileYSize () const;
153    LevelMode           levelMode () const;
154    LevelRoundingMode   levelRoundingMode () const;
155
156
157    //--------------------------------------------------------------------
158    // Number of levels:
159    //
160    // numXLevels() returns the file's number of levels in x direction.
161    //
162    //  if levelMode() == ONE_LEVEL:
163    //      return value is: 1
164    //
165    //  if levelMode() == MIPMAP_LEVELS:
166    //      return value is: rfunc (log (max (w, h)) / log (2)) + 1
167    //
168    //  if levelMode() == RIPMAP_LEVELS:
169    //      return value is: rfunc (log (w) / log (2)) + 1
170    //
171    //  where
172    //      w is the width of the image's data window,  max.x - min.x + 1,
173    //      y is the height of the image's data window, max.y - min.y + 1,
174    //      and rfunc(x) is either floor(x), or ceil(x), depending on
175    //      whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
176    //
177    // numYLevels() returns the file's number of levels in y direction.
178    //
179    //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
180    //      return value is the same as for numXLevels()
181    //
182    //  if levelMode() == RIPMAP_LEVELS:
183    //      return value is: rfunc (log (h) / log (2)) + 1
184    //
185    //
186    // numLevels() is a convenience function for use with
187    // MIPMAP_LEVELS files.
188    //
189    //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
190    //      return value is the same as for numXLevels()
191    //
192    //  if levelMode() == RIPMAP_LEVELS:
193    //      an Iex::LogicExc exception is thrown
194    //
195    // isValidLevel(lx, ly) returns true if the file contains
196    // a level with level number (lx, ly), false if not.
197    //
198    //--------------------------------------------------------------------
199
200    int                 numLevels () const;
201    int                 numXLevels () const;
202    int                 numYLevels () const;
203    bool                isValidLevel (int lx, int ly) const;
204
205
206    //----------------------------------------------------------
207    // Dimensions of a level:
208    //
209    // levelWidth(lx) returns the width of a level with level
210    // number (lx, *), where * is any number.
211    //
212    //  return value is:
213    //      max (1, rfunc (w / pow (2, lx)))
214    //
215    //
216    // levelHeight(ly) returns the height of a level with level
217    // number (*, ly), where * is any number.
218    //
219    //  return value is:
220    //      max (1, rfunc (h / pow (2, ly)))
221    //
222    //----------------------------------------------------------
223
224    int                 levelWidth  (int lx) const;
225    int                 levelHeight (int ly) const;
226
227
228    //--------------------------------------------------------------
229    // Number of tiles:
230    //
231    // numXTiles(lx) returns the number of tiles in x direction
232    // that cover a level with level number (lx, *), where * is
233    // any number.
234    //
235    //  return value is:
236    //      (levelWidth(lx) + tileXSize() - 1) / tileXSize()
237    //
238    //
239    // numYTiles(ly) returns the number of tiles in y direction
240    // that cover a level with level number (*, ly), where * is
241    // any number.
242    //
243    //  return value is:
244    //      (levelHeight(ly) + tileXSize() - 1) / tileXSize()
245    //
246    //--------------------------------------------------------------
247
248    int                 numXTiles (int lx = 0) const;
249    int                 numYTiles (int ly = 0) const;
250
251
252    //---------------------------------------------------------------
253    // Level pixel ranges:
254    //
255    // dataWindowForLevel(lx, ly) returns a 2-dimensional region of
256    // valid pixel coordinates for a level with 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, int l = 0) const;
297
298    Imath::Box2i        dataWindowForTile (int dx, int dy,
299                                           int lx, int ly) const;
300
301    //----------------------------------------------------------------
302    // Read pixel data:
303    //
304    // readTile(dx, dy, lx, ly) reads the tile with tile
305    // coordinates (dx, dy), and level number (lx, ly),
306    // and stores it in the current frame buffer.
307    //
308    //   dx must lie in the interval [0, numXTiles(lx)-1]
309    //   dy must lie in the interval [0, numYTiles(ly)-1]
310    //
311    //   lx must lie in the interval [0, numXLevels()-1]
312    //   ly must lie in the inverval [0, numYLevels()-1]
313    //
314    // readTile(dx, dy, level) is a convenience function used
315    // for ONE_LEVEL and MIPMAP_LEVELS files.  It calls
316    // readTile(dx, dy, level, level).
317    //
318    // Pixels that are outside the pixel coordinate range for the
319    // tile's level, are never accessed by readTile().
320    //
321    // Attempting to access a tile that is not present in the file
322    // throws an InputExc exception.
323    //
324    //----------------------------------------------------------------
325
326    void                readTile (int dx, int dy, int l = 0);
327    void                readTile (int dx, int dy, int lx, int ly);
328
329
330    //--------------------------------------------------
331    // Read a tile of raw pixel data from the file,
332    // without uncompressing it (this function is
333    // used to implement TiledOutputFile::copyPixels()).
334    //--------------------------------------------------
335
336    void                rawTileData (int &dx, int &dy,
337                                     int &lx, int &ly,
338                                     const char *&pixelData,
339                                     int &pixelDataSize);
340
341    struct Data;
342
343  private:
344
345    friend class InputFile;
346
347    TiledInputFile (const TiledInputFile &);              // not implemented
348    TiledInputFile & operator = (const TiledInputFile &); // not implemented
349
350    TiledInputFile (const Header &header, IStream *is, int version);
351
352    void                initialize ();
353
354    bool                isValidTile (int dx, int dy,
355                                     int lx, int ly) const;
356
357    size_t              bytesPerLineForTile (int dx, int dy,
358                                             int lx, int ly) const;
359
360    Data *              _data;
361};
362
363
364} // namespace Imf
365
366#endif
Note: See TracBrowser for help on using the repository browser.