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

source code of include/OpenEXR/ImfEnvmap.h