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;
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;