1 ///////////////////////////////////////////////////////////////////////////
3 // Copyright (c) 2004, Industrial Light & Magic, a division of Lucas
6 // All rights reserved.
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
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
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.
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.
33 ///////////////////////////////////////////////////////////////////////////
36 #ifndef INCLUDED_IMF_TILED_INPUT_FILE_H
37 #define INCLUDED_IMF_TILED_INPUT_FILE_H
39 //-----------------------------------------------------------------------------
41 // class TiledInputFile
43 //-----------------------------------------------------------------------------
45 #include <ImfHeader.h>
46 #include <ImfFrameBuffer.h>
48 #include <ImfTileDescription.h>
49 #include <ImfThreading.h>
58 //--------------------------------------------------------------------
59 // A constructor that opens the file with the specified name, and
60 // reads the file header. The constructor throws an Iex::ArgExc
61 // exception if the file is not tiled.
62 // The numThreads parameter specifies how many worker threads this
63 // file will try to keep busy when decompressing individual tiles.
64 // Destroying TiledInputFile objects constructed with this constructor
65 // automatically closes the corresponding files.
66 //--------------------------------------------------------------------
68 TiledInputFile (const char fileName[],
69 int numThreads = globalThreadCount ());
72 // ----------------------------------------------------------
73 // A constructor that attaches the new TiledInputFile object
74 // to a file that has already been opened.
75 // Destroying TiledInputFile objects constructed with this
76 // constructor does not automatically close the corresponding
78 // ----------------------------------------------------------
80 TiledInputFile (IStream &is, int numThreads = globalThreadCount ());
87 virtual ~TiledInputFile ();
90 //------------------------
91 // Access to the file name
92 //------------------------
94 const char * fileName () const;
97 //--------------------------
98 // Access to the file header
99 //--------------------------
101 const Header & header () const;
104 //----------------------------------
105 // Access to the file format version
106 //----------------------------------
108 int version () const;
111 //-----------------------------------------------------------
112 // Set the current frame buffer -- copies the FrameBuffer
113 // object into the TiledInputFile object.
115 // The current frame buffer is the destination for the pixel
116 // data read from the file. The current frame buffer must be
117 // set at least once before readTile() is called.
118 // The current frame buffer can be changed after each call
120 //-----------------------------------------------------------
122 void setFrameBuffer (const FrameBuffer &frameBuffer);
125 //-----------------------------------
126 // Access to the current frame buffer
127 //-----------------------------------
129 const FrameBuffer & frameBuffer () const;
132 //------------------------------------------------------------
133 // Check if the file is complete:
135 // isComplete() returns true if all pixels in the data window
136 // (in all levels) are present in the input file, or false if
137 // any pixels are missing. (Another program may still be busy
138 // writing the file, or file writing may have been aborted
140 //------------------------------------------------------------
142 bool isComplete () const;
145 //--------------------------------------------------
146 // Utility functions:
147 //--------------------------------------------------
149 //---------------------------------------------------------
150 // Multiresolution mode and tile size:
151 // The following functions return the xSize, ySize and mode
152 // fields of the file header's TileDescriptionAttribute.
153 //---------------------------------------------------------
155 unsigned int tileXSize () const;
156 unsigned int tileYSize () const;
157 LevelMode levelMode () const;
158 LevelRoundingMode levelRoundingMode () const;
161 //--------------------------------------------------------------------
164 // numXLevels() returns the file's number of levels in x direction.
166 // if levelMode() == ONE_LEVEL:
167 // return value is: 1
169 // if levelMode() == MIPMAP_LEVELS:
170 // return value is: rfunc (log (max (w, h)) / log (2)) + 1
172 // if levelMode() == RIPMAP_LEVELS:
173 // return value is: rfunc (log (w) / log (2)) + 1
176 // w is the width of the image's data window, max.x - min.x + 1,
177 // y is the height of the image's data window, max.y - min.y + 1,
178 // and rfunc(x) is either floor(x), or ceil(x), depending on
179 // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
181 // numYLevels() returns the file's number of levels in y direction.
183 // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
184 // return value is the same as for numXLevels()
186 // if levelMode() == RIPMAP_LEVELS:
187 // return value is: rfunc (log (h) / log (2)) + 1
190 // numLevels() is a convenience function for use with
191 // MIPMAP_LEVELS files.
193 // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
194 // return value is the same as for numXLevels()
196 // if levelMode() == RIPMAP_LEVELS:
197 // an Iex::LogicExc exception is thrown
199 // isValidLevel(lx, ly) returns true if the file contains
200 // a level with level number (lx, ly), false if not.
202 //--------------------------------------------------------------------
204 int numLevels () const;
205 int numXLevels () const;
206 int numYLevels () const;
207 bool isValidLevel (int lx, int ly) const;
210 //----------------------------------------------------------
211 // Dimensions of a level:
213 // levelWidth(lx) returns the width of a level with level
214 // number (lx, *), where * is any number.
217 // max (1, rfunc (w / pow (2, lx)))
220 // levelHeight(ly) returns the height of a level with level
221 // number (*, ly), where * is any number.
224 // max (1, rfunc (h / pow (2, ly)))
226 //----------------------------------------------------------
228 int levelWidth (int lx) const;
229 int levelHeight (int ly) const;
232 //--------------------------------------------------------------
235 // numXTiles(lx) returns the number of tiles in x direction
236 // that cover a level with level number (lx, *), where * is
240 // (levelWidth(lx) + tileXSize() - 1) / tileXSize()
243 // numYTiles(ly) returns the number of tiles in y direction
244 // that cover a level with level number (*, ly), where * is
248 // (levelHeight(ly) + tileXSize() - 1) / tileXSize()
250 //--------------------------------------------------------------
252 int numXTiles (int lx = 0) const;
253 int numYTiles (int ly = 0) const;
256 //---------------------------------------------------------------
257 // Level pixel ranges:
259 // dataWindowForLevel(lx, ly) returns a 2-dimensional region of
260 // valid pixel coordinates for a level with level number (lx, ly)
262 // return value is a Box2i with min value:
263 // (dataWindow.min.x, dataWindow.min.y)
266 // (dataWindow.min.x + levelWidth(lx) - 1,
267 // dataWindow.min.y + levelHeight(ly) - 1)
269 // dataWindowForLevel(level) is a convenience function used
270 // for ONE_LEVEL and MIPMAP_LEVELS files. It returns
271 // dataWindowForLevel(level, level).
273 //---------------------------------------------------------------
275 Imath::Box2i dataWindowForLevel (int l = 0) const;
276 Imath::Box2i dataWindowForLevel (int lx, int ly) const;
279 //-------------------------------------------------------------------
280 // Tile pixel ranges:
282 // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
283 // region of valid pixel coordinates for a tile with tile coordinates
284 // (dx,dy) and level number (lx, ly).
286 // return value is a Box2i with min value:
287 // (dataWindow.min.x + dx * tileXSize(),
288 // dataWindow.min.y + dy * tileYSize())
291 // (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
292 // dataWindow.min.y + (dy + 1) * tileYSize() - 1)
294 // dataWindowForTile(dx, dy, level) is a convenience function
295 // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns
296 // dataWindowForTile(dx, dy, level, level).
298 //-------------------------------------------------------------------
300 Imath::Box2i dataWindowForTile (int dx, int dy, int l = 0) const;
302 Imath::Box2i dataWindowForTile (int dx, int dy,
303 int lx, int ly) const;
305 //------------------------------------------------------------
308 // readTile(dx, dy, lx, ly) reads the tile with tile
309 // coordinates (dx, dy), and level number (lx, ly),
310 // and stores it in the current frame buffer.
312 // dx must lie in the interval [0, numXTiles(lx)-1]
313 // dy must lie in the interval [0, numYTiles(ly)-1]
315 // lx must lie in the interval [0, numXLevels()-1]
316 // ly must lie in the inverval [0, numYLevels()-1]
318 // readTile(dx, dy, level) is a convenience function used
319 // for ONE_LEVEL and MIPMAP_LEVELS files. It calls
320 // readTile(dx, dy, level, level).
322 // The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow
323 // reading multiple tiles at once. If multi-threading is used
324 // the multiple tiles are read concurrently.
326 // Pixels that are outside the pixel coordinate range for the
327 // tile's level, are never accessed by readTile().
329 // Attempting to access a tile that is not present in the file
330 // throws an InputExc exception.
332 //------------------------------------------------------------
334 void readTile (int dx, int dy, int l = 0);
335 void readTile (int dx, int dy, int lx, int ly);
337 void readTiles (int dx1, int dx2, int dy1, int dy2,
340 void readTiles (int dx1, int dx2, int dy1, int dy2,
344 //--------------------------------------------------
345 // Read a tile of raw pixel data from the file,
346 // without uncompressing it (this function is
347 // used to implement TiledOutputFile::copyPixels()).
348 //--------------------------------------------------
350 void rawTileData (int &dx, int &dy,
352 const char *&pixelData,
359 friend class InputFile;
361 TiledInputFile (const TiledInputFile &); // not implemented
362 TiledInputFile & operator = (const TiledInputFile &); // not implemented
364 TiledInputFile (const Header &header, IStream *is, int version,
369 bool isValidTile (int dx, int dy,
370 int lx, int ly) const;
372 size_t bytesPerLineForTile (int dx, int dy,
373 int lx, int ly) const;