git.maemo.org Git - opencv/blob - otherlibs/_graphics/include/OpenEXR/ImfTiledInputFile.h

   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 #include <ImfThreading.h>
  50
  51 namespace Imf {
  52
  53
  54 class TiledInputFile
  55 {
  56   public:
  57
  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     //--------------------------------------------------------------------
  67
  68     TiledInputFile (const char fileName[],
  69                     int numThreads = globalThreadCount ());
  70
  71
  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
  77     // files.
  78     // ----------------------------------------------------------
  79
  80     TiledInputFile (IStream &is, int numThreads = globalThreadCount ());
  81
  82
  83     //-----------
  84     // Destructor
  85     //-----------
  86
  87     virtual ~TiledInputFile ();
  88
  89
  90     //------------------------
  91     // Access to the file name
  92     //------------------------
  93
  94     const char *        fileName () const;
  95
  96
  97     //--------------------------
  98     // Access to the file header
  99     //--------------------------
 100
 101     const Header &      header () const;
 102
 103
 104     //----------------------------------
 105     // Access to the file format version
 106     //----------------------------------
 107
 108     int                 version () const;
 109
 110
 111     //-----------------------------------------------------------
 112     // Set the current frame buffer -- copies the FrameBuffer
 113     // object into the TiledInputFile object.
 114     //
 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
 119     // to readTile().
 120     //-----------------------------------------------------------
 121
 122     void                setFrameBuffer (const FrameBuffer &frameBuffer);
 123
 124
 125     //-----------------------------------
 126     // Access to the current frame buffer
 127     //-----------------------------------
 128
 129     const FrameBuffer & frameBuffer () const;
 130
 131
 132     //------------------------------------------------------------
 133     // Check if the file is complete:
 134     //
 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
 139     // prematurely.)
 140     //------------------------------------------------------------
 141
 142     bool                isComplete () const;
 143
 144
 145     //--------------------------------------------------
 146     // Utility functions:
 147     //--------------------------------------------------
 148
 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     //---------------------------------------------------------
 154
 155     unsigned int        tileXSize () const;
 156     unsigned int        tileYSize () const;
 157     LevelMode           levelMode () const;
 158     LevelRoundingMode   levelRoundingMode () const;
 159
 160
 161     //--------------------------------------------------------------------
 162     // Number of levels:
 163     //
 164     // numXLevels() returns the file's number of levels in x direction.
 165     //
 166     //  if levelMode() == ONE_LEVEL:
 167     //      return value is: 1
 168     //
 169     //  if levelMode() == MIPMAP_LEVELS:
 170     //      return value is: rfunc (log (max (w, h)) / log (2)) + 1
 171     //
 172     //  if levelMode() == RIPMAP_LEVELS:
 173     //      return value is: rfunc (log (w) / log (2)) + 1
 174     //
 175     //  where
 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.
 180     //
 181     // numYLevels() returns the file's number of levels in y direction.
 182     //
 183     //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
 184     //      return value is the same as for numXLevels()
 185     //
 186     //  if levelMode() == RIPMAP_LEVELS:
 187     //      return value is: rfunc (log (h) / log (2)) + 1
 188     //
 189     //
 190     // numLevels() is a convenience function for use with
 191     // MIPMAP_LEVELS files.
 192     //
 193     //  if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
 194     //      return value is the same as for numXLevels()
 195     //
 196     //  if levelMode() == RIPMAP_LEVELS:
 197     //      an Iex::LogicExc exception is thrown
 198     //
 199     // isValidLevel(lx, ly) returns true if the file contains
 200     // a level with level number (lx, ly), false if not.
 201     //
 202     //--------------------------------------------------------------------
 203
 204     int                 numLevels () const;
 205     int                 numXLevels () const;
 206     int                 numYLevels () const;
 207     bool                isValidLevel (int lx, int ly) const;
 208
 209
 210     //----------------------------------------------------------
 211     // Dimensions of a level:
 212     //
 213     // levelWidth(lx) returns the width of a level with level
 214     // number (lx, *), where * is any number.
 215     //
 216     //  return value is:
 217     //      max (1, rfunc (w / pow (2, lx)))
 218     //
 219     //
 220     // levelHeight(ly) returns the height of a level with level
 221     // number (*, ly), where * is any number.
 222     //
 223     //  return value is:
 224     //      max (1, rfunc (h / pow (2, ly)))
 225     //
 226     //----------------------------------------------------------
 227
 228     int                 levelWidth  (int lx) const;
 229     int                 levelHeight (int ly) const;
 230
 231
 232     //--------------------------------------------------------------
 233     // Number of tiles:
 234     //
 235     // numXTiles(lx) returns the number of tiles in x direction
 236     // that cover a level with level number (lx, *), where * is
 237     // any number.
 238     //
 239     //  return value is:
 240     //      (levelWidth(lx) + tileXSize() - 1) / tileXSize()
 241     //
 242     //
 243     // numYTiles(ly) returns the number of tiles in y direction
 244     // that cover a level with level number (*, ly), where * is
 245     // any number.
 246     //
 247     //  return value is:
 248     //      (levelHeight(ly) + tileXSize() - 1) / tileXSize()
 249     //
 250     //--------------------------------------------------------------
 251
 252     int                 numXTiles (int lx = 0) const;
 253     int                 numYTiles (int ly = 0) const;
 254
 255
 256     //---------------------------------------------------------------
 257     // Level pixel ranges:
 258     //
 259     // dataWindowForLevel(lx, ly) returns a 2-dimensional region of
 260     // valid pixel coordinates for a level with level number (lx, ly)
 261     //
 262     //  return value is a Box2i with min value:
 263     //      (dataWindow.min.x, dataWindow.min.y)
 264     //
 265     //  and max value:
 266     //      (dataWindow.min.x + levelWidth(lx) - 1,
 267     //       dataWindow.min.y + levelHeight(ly) - 1)
 268     //
 269     // dataWindowForLevel(level) is a convenience function used
 270     // for ONE_LEVEL and MIPMAP_LEVELS files.  It returns
 271     // dataWindowForLevel(level, level).
 272     //
 273     //---------------------------------------------------------------
 274
 275     Imath::Box2i        dataWindowForLevel (int l = 0) const;
 276     Imath::Box2i        dataWindowForLevel (int lx, int ly) const;
 277
 278
 279     //-------------------------------------------------------------------
 280     // Tile pixel ranges:
 281     //
 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).
 285     //
 286     //  return value is a Box2i with min value:
 287     //      (dataWindow.min.x + dx * tileXSize(),
 288     //       dataWindow.min.y + dy * tileYSize())
 289     //
 290     //  and max value:
 291     //      (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
 292     //       dataWindow.min.y + (dy + 1) * tileYSize() - 1)
 293     //
 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).
 297     //
 298     //-------------------------------------------------------------------
 299
 300     Imath::Box2i        dataWindowForTile (int dx, int dy, int l = 0) const;
 301
 302     Imath::Box2i        dataWindowForTile (int dx, int dy,
 303                                            int lx, int ly) const;
 304
 305     //------------------------------------------------------------
 306     // Read pixel data:
 307     //
 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.
 311     //
 312     //   dx must lie in the interval [0, numXTiles(lx)-1]
 313     //   dy must lie in the interval [0, numYTiles(ly)-1]
 314     //
 315     //   lx must lie in the interval [0, numXLevels()-1]
 316     //   ly must lie in the inverval [0, numYLevels()-1]
 317     //
 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).
 321     //
 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.
 325     //
 326     // Pixels that are outside the pixel coordinate range for the
 327     // tile's level, are never accessed by readTile().
 328     //
 329     // Attempting to access a tile that is not present in the file
 330     // throws an InputExc exception.
 331     //
 332     //------------------------------------------------------------
 333
 334     void                readTile  (int dx, int dy, int l = 0);
 335     void                readTile  (int dx, int dy, int lx, int ly);
 336
 337     void                readTiles (int dx1, int dx2, int dy1, int dy2,
 338                                    int lx, int ly);
 339
 340     void                readTiles (int dx1, int dx2, int dy1, int dy2,
 341                                    int l = 0);
 342
 343
 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     //--------------------------------------------------
 349
 350     void                rawTileData (int &dx, int &dy,
 351                                      int &lx, int &ly,
 352                                      const char *&pixelData,
 353                                      int &pixelDataSize);
 354
 355     struct Data;
 356
 357   private:
 358
 359     friend class InputFile;
 360
 361     TiledInputFile (const TiledInputFile &);              // not implemented
 362     TiledInputFile & operator = (const TiledInputFile &); // not implemented
 363
 364     TiledInputFile (const Header &header, IStream *is, int version,
 365                     int numThreads);
 366
 367     void                initialize ();
 368
 369     bool                isValidTile (int dx, int dy,
 370                                      int lx, int ly) const;
 371
 372     size_t              bytesPerLineForTile (int dx, int dy,
 373                                              int lx, int ly) const;
 374
 375     Data *              _data;
 376 };
 377
 378
 379 } // namespace Imf
 380
 381 #endif