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

https://bitbucket.org/cabalistic/ogredeps/ · C++ Header · 322 lines · 49 code · 45 blank · 228 comment · 0 complexity · 04c4b0da65a47c58537bd852cf47bcec 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_ENVMAP_H
  35. #define INCLUDED_IMF_ENVMAP_H
  36. //-----------------------------------------------------------------------------
  37. //
  38. // Environment maps
  39. //
  40. // Environment maps define a mapping from 3D directions to 2D
  41. // pixel space locations. Environment maps are typically used
  42. // in 3D rendering, for effects such as quickly approximating
  43. // how shiny surfaces reflect their environment.
  44. //
  45. // Environment maps can be stored in scanline-based or in tiled
  46. // OpenEXR files. The fact that an image is an environment map
  47. // is indicated by the presence of an EnvmapAttribute whose name
  48. // is "envmap". (Convenience functions to access this attribute
  49. // are defined in header file ImfStandardAttributes.h.)
  50. // The attribute's value defines the mapping from 3D directions
  51. // to 2D pixel space locations.
  52. //
  53. // This header file defines the set of possible EnvmapAttribute
  54. // values.
  55. //
  56. // For each possible EnvmapAttribute value, this header file also
  57. // defines a set of convienience functions to convert between 3D
  58. // directions and 2D pixel locations.
  59. //
  60. // Most of the convenience functions defined below require a
  61. // dataWindow parameter. For scanline-based images, and for
  62. // tiled images with level mode ONE_LEVEL, the dataWindow
  63. // parameter should be set to the image's data window, as
  64. // defined in the image header. For tiled images with level
  65. // mode MIPMAP_LEVELS or RIPMAP_LEVELS, the data window of the
  66. // image level that is being accessed should be used instead.
  67. // (See the dataWindowForLevel() methods in ImfTiledInputFile.h
  68. // and ImfTiledOutputFile.h.)
  69. //
  70. //-----------------------------------------------------------------------------
  71. #include "ImathBox.h"
  72. namespace Imf {
  73. //--------------------------------
  74. // Supported environment map types
  75. //--------------------------------
  76. enum Envmap
  77. {
  78. ENVMAP_LATLONG = 0, // Latitude-longitude environment map
  79. ENVMAP_CUBE = 1, // Cube map
  80. NUM_ENVMAPTYPES // Number of different environment map types
  81. };
  82. //-------------------------------------------------------------------------
  83. // Latitude-Longitude Map:
  84. //
  85. // The environment is projected onto the image using polar coordinates
  86. // (latitude and longitude). A pixel's x coordinate corresponds to
  87. // its longitude, and the y coordinate corresponds to its latitude.
  88. // Pixel (dataWindow.min.x, dataWindow.min.y) has latitude +pi/2 and
  89. // longitude +pi; pixel (dataWindow.max.x, dataWindow.max.y) has
  90. // latitude -pi/2 and longitude -pi.
  91. //
  92. // In 3D space, latitudes -pi/2 and +pi/2 correspond to the negative and
  93. // positive y direction. Latitude 0, longitude 0 points into positive
  94. // z direction; and latitude 0, longitude pi/2 points into positive x
  95. // direction.
  96. //
  97. // The size of the data window should be 2*N by N pixels (width by height),
  98. // where N can be any integer greater than 0.
  99. //-------------------------------------------------------------------------
  100. namespace LatLongMap
  101. {
  102. //----------------------------------------------------
  103. // Convert a 3D direction to a 2D vector whose x and y
  104. // components represent the corresponding latitude
  105. // and longitude.
  106. //----------------------------------------------------
  107. Imath::V2f latLong (const Imath::V3f &direction);
  108. //--------------------------------------------------------
  109. // Convert the position of a pixel to a 2D vector whose
  110. // x and y components represent the corresponding latitude
  111. // and longitude.
  112. //--------------------------------------------------------
  113. Imath::V2f latLong (const Imath::Box2i &dataWindow,
  114. const Imath::V2f &pixelPosition);
  115. //-------------------------------------------------------------
  116. // Convert a 2D vector, whose x and y components represent
  117. // longitude and latitude, into a corresponding pixel position.
  118. //-------------------------------------------------------------
  119. Imath::V2f pixelPosition (const Imath::Box2i &dataWindow,
  120. const Imath::V2f &latLong);
  121. //-----------------------------------------------------
  122. // Convert a 3D direction vector into a corresponding
  123. // pixel position. pixelPosition(dw,dir) is equivalent
  124. // to pixelPosition(dw,latLong(dw,dir)).
  125. //-----------------------------------------------------
  126. Imath::V2f pixelPosition (const Imath::Box2i &dataWindow,
  127. const Imath::V3f &direction);
  128. //--------------------------------------------------------
  129. // Convert the position of a pixel in a latitude-longitude
  130. // map into a corresponding 3D direction.
  131. //--------------------------------------------------------
  132. Imath::V3f direction (const Imath::Box2i &dataWindow,
  133. const Imath::V2f &pixelPosition);
  134. }
  135. //--------------------------------------------------------------
  136. // Cube Map:
  137. //
  138. // The environment is projected onto the six faces of an
  139. // axis-aligned cube. The cube's faces are then arranged
  140. // in a 2D image as shown below.
  141. //
  142. // 2-----------3
  143. // / /|
  144. // / / | Y
  145. // / / | |
  146. // 6-----------7 | |
  147. // | | | |
  148. // | | | |
  149. // | 0 | 1 *------- X
  150. // | | / /
  151. // | | / /
  152. // | |/ /
  153. // 4-----------5 Z
  154. //
  155. // dataWindow.min
  156. // /
  157. // /
  158. // +-----------+
  159. // |3 Y 7|
  160. // | | |
  161. // | | |
  162. // | ---+---Z | +X face
  163. // | | |
  164. // | | |
  165. // |1 5|
  166. // +-----------+
  167. // |6 Y 2|
  168. // | | |
  169. // | | |
  170. // | Z---+--- | -X face
  171. // | | |
  172. // | | |
  173. // |4 0|
  174. // +-----------+
  175. // |6 Z 7|
  176. // | | |
  177. // | | |
  178. // | ---+---X | +Y face
  179. // | | |
  180. // | | |
  181. // |2 3|
  182. // +-----------+
  183. // |0 1|
  184. // | | |
  185. // | | |
  186. // | ---+---X | -Y face
  187. // | | |
  188. // | | |
  189. // |4 Z 5|
  190. // +-----------+
  191. // |7 Y 6|
  192. // | | |
  193. // | | |
  194. // | X---+--- | +Z face
  195. // | | |
  196. // | | |
  197. // |5 4|
  198. // +-----------+
  199. // |2 Y 3|
  200. // | | |
  201. // | | |
  202. // | ---+---X | -Z face
  203. // | | |
  204. // | | |
  205. // |0 1|
  206. // +-----------+
  207. // /
  208. // /
  209. // dataWindow.max
  210. //
  211. // The size of the data window should be N by 6*N pixels
  212. // (width by height), where N can be any integer greater
  213. // than 0.
  214. //
  215. //--------------------------------------------------------------
  216. //------------------------------------
  217. // Names for the six faces of the cube
  218. //------------------------------------
  219. enum CubeMapFace
  220. {
  221. CUBEFACE_POS_X, // +X face
  222. CUBEFACE_NEG_X, // -X face
  223. CUBEFACE_POS_Y, // +Y face
  224. CUBEFACE_NEG_Y, // -Y face
  225. CUBEFACE_POS_Z, // +Z face
  226. CUBEFACE_NEG_Z // -Z face
  227. };
  228. namespace CubeMap
  229. {
  230. //---------------------------------------------
  231. // Width and height of a cube's face, in pixels
  232. //---------------------------------------------
  233. int sizeOfFace (const Imath::Box2i &dataWindow);
  234. //------------------------------------------
  235. // Compute the region in the environment map
  236. // that is covered by the specified face.
  237. //------------------------------------------
  238. Imath::Box2i dataWindowForFace (CubeMapFace face,
  239. const Imath::Box2i &dataWindow);
  240. //----------------------------------------------------
  241. // Convert the coordinates of a pixel within a face
  242. // [in the range from (0,0) to (s-1,s-1), where
  243. // s == sizeOfFace(dataWindow)] to pixel coordinates
  244. // in the environment map.
  245. //----------------------------------------------------
  246. Imath::V2f pixelPosition (CubeMapFace face,
  247. const Imath::Box2i &dataWindow,
  248. Imath::V2f positionInFace);
  249. //--------------------------------------------------------------
  250. // Convert a 3D direction into a cube face, and a pixel position
  251. // within that face.
  252. //
  253. // If you have a 3D direction, dir, the following code fragment
  254. // finds the position, pos, of the corresponding pixel in an
  255. // environment map with data window dw:
  256. //
  257. // CubeMapFace f;
  258. // V2f pif, pos;
  259. //
  260. // faceAndPixelPosition (dir, dw, f, pif);
  261. // pos = pixelPosition (f, dw, pif);
  262. //
  263. //--------------------------------------------------------------
  264. void faceAndPixelPosition (const Imath::V3f &direction,
  265. const Imath::Box2i &dataWindow,
  266. CubeMapFace &face,
  267. Imath::V2f &positionInFace);
  268. // --------------------------------------------------------
  269. // Given a cube face and a pixel position within that face,
  270. // compute the corresponding 3D direction.
  271. // --------------------------------------------------------
  272. Imath::V3f direction (CubeMapFace face,
  273. const Imath::Box2i &dataWindow,
  274. const Imath::V2f &positionInFace);
  275. }
  276. } // namespace Imf
  277. #endif