/src/FreeImage/Source/OpenEXR/IlmImf/ImfTiledInputFile.h

https://bitbucket.org/cabalistic/ogredeps/ · C++ Header · 381 lines · 64 code · 72 blank · 245 comment · 0 complexity · 6b10b1cc125ae73ae9dc17391390bf22 MD5 · raw file

  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. #ifndef INCLUDED_IMF_TILED_INPUT_FILE_H
  35. #define INCLUDED_IMF_TILED_INPUT_FILE_H
  36. //-----------------------------------------------------------------------------
  37. //
  38. // class TiledInputFile
  39. //
  40. //-----------------------------------------------------------------------------
  41. #include <ImfHeader.h>
  42. #include <ImfFrameBuffer.h>
  43. #include "ImathBox.h"
  44. #include <ImfTileDescription.h>
  45. #include <ImfThreading.h>
  46. namespace Imf {
  47. class TiledInputFile
  48. {
  49. public:
  50. //--------------------------------------------------------------------
  51. // A constructor that opens the file with the specified name, and
  52. // reads the file header. The constructor throws an Iex::ArgExc
  53. // exception if the file is not tiled.
  54. // The numThreads parameter specifies how many worker threads this
  55. // file will try to keep busy when decompressing individual tiles.
  56. // Destroying TiledInputFile objects constructed with this constructor
  57. // automatically closes the corresponding files.
  58. //--------------------------------------------------------------------
  59. TiledInputFile (const char fileName[],
  60. int numThreads = globalThreadCount ());
  61. // ----------------------------------------------------------
  62. // A constructor that attaches the new TiledInputFile object
  63. // to a file that has already been opened.
  64. // Destroying TiledInputFile objects constructed with this
  65. // constructor does not automatically close the corresponding
  66. // files.
  67. // ----------------------------------------------------------
  68. TiledInputFile (IStream &is, int numThreads = globalThreadCount ());
  69. //-----------
  70. // Destructor
  71. //-----------
  72. virtual ~TiledInputFile ();
  73. //------------------------
  74. // Access to the file name
  75. //------------------------
  76. const char * fileName () const;
  77. //--------------------------
  78. // Access to the file header
  79. //--------------------------
  80. const Header & header () const;
  81. //----------------------------------
  82. // Access to the file format version
  83. //----------------------------------
  84. int version () const;
  85. //-----------------------------------------------------------
  86. // Set the current frame buffer -- copies the FrameBuffer
  87. // object into the TiledInputFile object.
  88. //
  89. // The current frame buffer is the destination for the pixel
  90. // data read from the file. The current frame buffer must be
  91. // set at least once before readTile() is called.
  92. // The current frame buffer can be changed after each call
  93. // to readTile().
  94. //-----------------------------------------------------------
  95. void setFrameBuffer (const FrameBuffer &frameBuffer);
  96. //-----------------------------------
  97. // Access to the current frame buffer
  98. //-----------------------------------
  99. const FrameBuffer & frameBuffer () const;
  100. //------------------------------------------------------------
  101. // Check if the file is complete:
  102. //
  103. // isComplete() returns true if all pixels in the data window
  104. // (in all levels) are present in the input file, or false if
  105. // any pixels are missing. (Another program may still be busy
  106. // writing the file, or file writing may have been aborted
  107. // prematurely.)
  108. //------------------------------------------------------------
  109. bool isComplete () const;
  110. //--------------------------------------------------
  111. // Utility functions:
  112. //--------------------------------------------------
  113. //---------------------------------------------------------
  114. // Multiresolution mode and tile size:
  115. // The following functions return the xSize, ySize and mode
  116. // fields of the file header's TileDescriptionAttribute.
  117. //---------------------------------------------------------
  118. unsigned int tileXSize () const;
  119. unsigned int tileYSize () const;
  120. LevelMode levelMode () const;
  121. LevelRoundingMode levelRoundingMode () const;
  122. //--------------------------------------------------------------------
  123. // Number of levels:
  124. //
  125. // numXLevels() returns the file's number of levels in x direction.
  126. //
  127. // if levelMode() == ONE_LEVEL:
  128. // return value is: 1
  129. //
  130. // if levelMode() == MIPMAP_LEVELS:
  131. // return value is: rfunc (log (max (w, h)) / log (2)) + 1
  132. //
  133. // if levelMode() == RIPMAP_LEVELS:
  134. // return value is: rfunc (log (w) / log (2)) + 1
  135. //
  136. // where
  137. // w is the width of the image's data window, max.x - min.x + 1,
  138. // y is the height of the image's data window, max.y - min.y + 1,
  139. // and rfunc(x) is either floor(x), or ceil(x), depending on
  140. // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
  141. //
  142. // numYLevels() returns the file's number of levels in y direction.
  143. //
  144. // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
  145. // return value is the same as for numXLevels()
  146. //
  147. // if levelMode() == RIPMAP_LEVELS:
  148. // return value is: rfunc (log (h) / log (2)) + 1
  149. //
  150. //
  151. // numLevels() is a convenience function for use with
  152. // MIPMAP_LEVELS files.
  153. //
  154. // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
  155. // return value is the same as for numXLevels()
  156. //
  157. // if levelMode() == RIPMAP_LEVELS:
  158. // an Iex::LogicExc exception is thrown
  159. //
  160. // isValidLevel(lx, ly) returns true if the file contains
  161. // a level with level number (lx, ly), false if not.
  162. //
  163. //--------------------------------------------------------------------
  164. int numLevels () const;
  165. int numXLevels () const;
  166. int numYLevels () const;
  167. bool isValidLevel (int lx, int ly) const;
  168. //----------------------------------------------------------
  169. // Dimensions of a level:
  170. //
  171. // levelWidth(lx) returns the width of a level with level
  172. // number (lx, *), where * is any number.
  173. //
  174. // return value is:
  175. // max (1, rfunc (w / pow (2, lx)))
  176. //
  177. //
  178. // levelHeight(ly) returns the height of a level with level
  179. // number (*, ly), where * is any number.
  180. //
  181. // return value is:
  182. // max (1, rfunc (h / pow (2, ly)))
  183. //
  184. //----------------------------------------------------------
  185. int levelWidth (int lx) const;
  186. int levelHeight (int ly) const;
  187. //--------------------------------------------------------------
  188. // Number of tiles:
  189. //
  190. // numXTiles(lx) returns the number of tiles in x direction
  191. // that cover a level with level number (lx, *), where * is
  192. // any number.
  193. //
  194. // return value is:
  195. // (levelWidth(lx) + tileXSize() - 1) / tileXSize()
  196. //
  197. //
  198. // numYTiles(ly) returns the number of tiles in y direction
  199. // that cover a level with level number (*, ly), where * is
  200. // any number.
  201. //
  202. // return value is:
  203. // (levelHeight(ly) + tileXSize() - 1) / tileXSize()
  204. //
  205. //--------------------------------------------------------------
  206. int numXTiles (int lx = 0) const;
  207. int numYTiles (int ly = 0) const;
  208. //---------------------------------------------------------------
  209. // Level pixel ranges:
  210. //
  211. // dataWindowForLevel(lx, ly) returns a 2-dimensional region of
  212. // valid pixel coordinates for a level with level number (lx, ly)
  213. //
  214. // return value is a Box2i with min value:
  215. // (dataWindow.min.x, dataWindow.min.y)
  216. //
  217. // and max value:
  218. // (dataWindow.min.x + levelWidth(lx) - 1,
  219. // dataWindow.min.y + levelHeight(ly) - 1)
  220. //
  221. // dataWindowForLevel(level) is a convenience function used
  222. // for ONE_LEVEL and MIPMAP_LEVELS files. It returns
  223. // dataWindowForLevel(level, level).
  224. //
  225. //---------------------------------------------------------------
  226. Imath::Box2i dataWindowForLevel (int l = 0) const;
  227. Imath::Box2i dataWindowForLevel (int lx, int ly) const;
  228. //-------------------------------------------------------------------
  229. // Tile pixel ranges:
  230. //
  231. // dataWindowForTile(dx, dy, lx, ly) returns a 2-dimensional
  232. // region of valid pixel coordinates for a tile with tile coordinates
  233. // (dx,dy) and level number (lx, ly).
  234. //
  235. // return value is a Box2i with min value:
  236. // (dataWindow.min.x + dx * tileXSize(),
  237. // dataWindow.min.y + dy * tileYSize())
  238. //
  239. // and max value:
  240. // (dataWindow.min.x + (dx + 1) * tileXSize() - 1,
  241. // dataWindow.min.y + (dy + 1) * tileYSize() - 1)
  242. //
  243. // dataWindowForTile(dx, dy, level) is a convenience function
  244. // used for ONE_LEVEL and MIPMAP_LEVELS files. It returns
  245. // dataWindowForTile(dx, dy, level, level).
  246. //
  247. //-------------------------------------------------------------------
  248. Imath::Box2i dataWindowForTile (int dx, int dy, int l = 0) const;
  249. Imath::Box2i dataWindowForTile (int dx, int dy,
  250. int lx, int ly) const;
  251. //------------------------------------------------------------
  252. // Read pixel data:
  253. //
  254. // readTile(dx, dy, lx, ly) reads the tile with tile
  255. // coordinates (dx, dy), and level number (lx, ly),
  256. // and stores it in the current frame buffer.
  257. //
  258. // dx must lie in the interval [0, numXTiles(lx)-1]
  259. // dy must lie in the interval [0, numYTiles(ly)-1]
  260. //
  261. // lx must lie in the interval [0, numXLevels()-1]
  262. // ly must lie in the inverval [0, numYLevels()-1]
  263. //
  264. // readTile(dx, dy, level) is a convenience function used
  265. // for ONE_LEVEL and MIPMAP_LEVELS files. It calls
  266. // readTile(dx, dy, level, level).
  267. //
  268. // The two readTiles(dx1, dx2, dy1, dy2, ...) functions allow
  269. // reading multiple tiles at once. If multi-threading is used
  270. // the multiple tiles are read concurrently.
  271. //
  272. // Pixels that are outside the pixel coordinate range for the
  273. // tile's level, are never accessed by readTile().
  274. //
  275. // Attempting to access a tile that is not present in the file
  276. // throws an InputExc exception.
  277. //
  278. //------------------------------------------------------------
  279. void readTile (int dx, int dy, int l = 0);
  280. void readTile (int dx, int dy, int lx, int ly);
  281. void readTiles (int dx1, int dx2, int dy1, int dy2,
  282. int lx, int ly);
  283. void readTiles (int dx1, int dx2, int dy1, int dy2,
  284. int l = 0);
  285. //--------------------------------------------------
  286. // Read a tile of raw pixel data from the file,
  287. // without uncompressing it (this function is
  288. // used to implement TiledOutputFile::copyPixels()).
  289. //--------------------------------------------------
  290. void rawTileData (int &dx, int &dy,
  291. int &lx, int &ly,
  292. const char *&pixelData,
  293. int &pixelDataSize);
  294. struct Data;
  295. private:
  296. friend class InputFile;
  297. TiledInputFile (const TiledInputFile &); // not implemented
  298. TiledInputFile & operator = (const TiledInputFile &); // not implemented
  299. TiledInputFile (const Header &header, IStream *is, int version,
  300. int numThreads);
  301. void initialize ();
  302. bool isValidTile (int dx, int dy,
  303. int lx, int ly) const;
  304. size_t bytesPerLineForTile (int dx, int dy,
  305. int lx, int ly) const;
  306. Data * _data;
  307. };
  308. } // namespace Imf
  309. #endif