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_STANDARD_ATTRIBUTES_H |
37 | #define INCLUDED_IMF_STANDARD_ATTRIBUTES_H |
38 | |
39 | //----------------------------------------------------------------------------- |
40 | // |
41 | // Optional Standard Attributes -- these attributes are "optional" |
42 | // because not every image file header has them, but they define a |
43 | // "standard" way to represent commonly used data in the file header. |
44 | // |
45 | // For each attribute, with name "foo", and type "T", the following |
46 | // functions are automatically generated via macros: |
47 | // |
48 | // void addFoo (Header &header, const T &value); |
49 | // bool hasFoo (const Header &header); |
50 | // const TypedAttribute<T> & fooAttribute (const Header &header); |
51 | // TypedAttribute<T> & fooAttribute (Header &header); |
52 | // const T & foo (const Header &Header); |
53 | // T & foo (Header &Header); |
54 | // |
55 | //----------------------------------------------------------------------------- |
56 | |
57 | #include "ImfHeader.h" |
58 | #include "ImfBoxAttribute.h" |
59 | #include "ImfChromaticitiesAttribute.h" |
60 | #include "ImfEnvmapAttribute.h" |
61 | #include "ImfDeepImageStateAttribute.h" |
62 | #include "ImfFloatAttribute.h" |
63 | #include "ImfKeyCodeAttribute.h" |
64 | #include "ImfMatrixAttribute.h" |
65 | #include "ImfRationalAttribute.h" |
66 | #include "ImfStringAttribute.h" |
67 | #include "ImfStringVectorAttribute.h" |
68 | #include "ImfTimeCodeAttribute.h" |
69 | #include "ImfVecAttribute.h" |
70 | #include "ImfNamespace.h" |
71 | #include "ImfExport.h" |
72 | |
73 | #define IMF_STD_ATTRIBUTE_DEF(name,suffix,object) \ |
74 | \ |
75 | OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER \ |
76 | IMF_EXPORT void add##suffix (Header &, const object &v); \ |
77 | IMF_EXPORT bool has##suffix (const Header &); \ |
78 | IMF_EXPORT const TypedAttribute<object> & \ |
79 | name##Attribute (const Header &); \ |
80 | IMF_EXPORT TypedAttribute<object> & \ |
81 | name##Attribute (Header &); \ |
82 | IMF_EXPORT const object & \ |
83 | name (const Header &); \ |
84 | IMF_EXPORT object & name (Header &); \ |
85 | OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT \ |
86 | |
87 | // |
88 | // chromaticities -- for RGB images, specifies the CIE (x,y) |
89 | // chromaticities of the primaries and the white point |
90 | // |
91 | |
92 | IMF_STD_ATTRIBUTE_DEF (, Chromaticities, Chromaticities) |
93 | |
94 | |
95 | // |
96 | // whiteLuminance -- for RGB images, defines the luminance, in Nits |
97 | // (candelas per square meter) of the RGB value (1.0, 1.0, 1.0). |
98 | // |
99 | // If the chromaticities and the whiteLuminance of an RGB image are |
100 | // known, then it is possible to convert the image's pixels from RGB |
101 | // to CIE XYZ tristimulus values (see function RGBtoXYZ() in header |
102 | // file ImfChromaticities.h). |
103 | // |
104 | // |
105 | |
106 | IMF_STD_ATTRIBUTE_DEF (, WhiteLuminance, float) |
107 | |
108 | |
109 | // |
110 | // adoptedNeutral -- specifies the CIE (x,y) coordinates that should |
111 | // be considered neutral during color rendering. Pixels in the image |
112 | // file whose (x,y) coordinates match the adoptedNeutral value should |
113 | // be mapped to neutral values on the display. |
114 | // |
115 | |
116 | IMF_STD_ATTRIBUTE_DEF (, AdoptedNeutral, IMATH_NAMESPACE::V2f) |
117 | |
118 | |
119 | // |
120 | // renderingTransform, lookModTransform -- specify the names of the |
121 | // CTL functions that implements the intended color rendering and look |
122 | // modification transforms for this image. |
123 | // |
124 | |
125 | IMF_STD_ATTRIBUTE_DEF (, RenderingTransform, std::string) |
126 | IMF_STD_ATTRIBUTE_DEF (, LookModTransform, std::string) |
127 | |
128 | |
129 | // |
130 | // xDensity -- horizontal output density, in pixels per inch. |
131 | // The image's vertical output density is xDensity * pixelAspectRatio. |
132 | // |
133 | |
134 | IMF_STD_ATTRIBUTE_DEF (, XDensity, float) |
135 | |
136 | |
137 | // |
138 | // owner -- name of the owner of the image |
139 | // |
140 | |
141 | IMF_STD_ATTRIBUTE_DEF (, Owner, std::string) |
142 | |
143 | |
144 | // |
145 | // comments -- additional image information in human-readable |
146 | // form, for example a verbal description of the image |
147 | // |
148 | |
149 | IMF_STD_ATTRIBUTE_DEF (, Comments, std::string) |
150 | |
151 | |
152 | // |
153 | // capDate -- the date when the image was created or captured, |
154 | // in local time, and formatted as |
155 | // |
156 | // YYYY:MM:DD hh:mm:ss |
157 | // |
158 | // where YYYY is the year (4 digits, e.g. 2003), MM is the month |
159 | // (2 digits, 01, 02, ... 12), DD is the day of the month (2 digits, |
160 | // 01, 02, ... 31), hh is the hour (2 digits, 00, 01, ... 23), mm |
161 | // is the minute, and ss is the second (2 digits, 00, 01, ... 59). |
162 | // |
163 | // |
164 | |
165 | IMF_STD_ATTRIBUTE_DEF (, CapDate, std::string) |
166 | |
167 | |
168 | // |
169 | // utcOffset -- offset of local time at capDate from |
170 | // Universal Coordinated Time (UTC), in seconds: |
171 | // |
172 | // UTC == local time + utcOffset |
173 | // |
174 | |
175 | IMF_STD_ATTRIBUTE_DEF (, UtcOffset, float) |
176 | |
177 | |
178 | // |
179 | // longitude, latitude, altitude -- for images of real objects, the |
180 | // location where the image was recorded. Longitude and latitude are |
181 | // in degrees east of Greenwich and north of the equator. Altitude |
182 | // is in meters above sea level. For example, Kathmandu, Nepal is |
183 | // at longitude 85.317, latitude 27.717, altitude 1305. |
184 | // |
185 | |
186 | IMF_STD_ATTRIBUTE_DEF (, Longitude, float) |
187 | IMF_STD_ATTRIBUTE_DEF (, Latitude, float) |
188 | IMF_STD_ATTRIBUTE_DEF (, Altitude, float) |
189 | |
190 | |
191 | // |
192 | // focus -- the camera's focus distance, in meters |
193 | // |
194 | |
195 | IMF_STD_ATTRIBUTE_DEF (, Focus, float) |
196 | |
197 | |
198 | // |
199 | // exposure -- exposure time, in seconds |
200 | // |
201 | |
202 | IMF_STD_ATTRIBUTE_DEF (, ExpTime, float) |
203 | |
204 | |
205 | // |
206 | // aperture -- the camera's lens aperture, in f-stops (focal length |
207 | // of the lens divided by the diameter of the iris opening) |
208 | // |
209 | |
210 | IMF_STD_ATTRIBUTE_DEF (, Aperture, float) |
211 | |
212 | |
213 | // |
214 | // isoSpeed -- the ISO speed of the film or image sensor |
215 | // that was used to record the image |
216 | // |
217 | |
218 | IMF_STD_ATTRIBUTE_DEF (, IsoSpeed, float) |
219 | |
220 | |
221 | // |
222 | // envmap -- if this attribute is present, the image represents |
223 | // an environment map. The attribute's value defines how 3D |
224 | // directions are mapped to 2D pixel locations. For details |
225 | // see header file ImfEnvmap.h |
226 | // |
227 | |
228 | IMF_STD_ATTRIBUTE_DEF (, Envmap, Envmap) |
229 | |
230 | |
231 | // |
232 | // keyCode -- for motion picture film frames. Identifies film |
233 | // manufacturer, film type, film roll and frame position within |
234 | // the roll. |
235 | // |
236 | |
237 | IMF_STD_ATTRIBUTE_DEF (, KeyCode, KeyCode) |
238 | |
239 | |
240 | // |
241 | // timeCode -- time and control code |
242 | // |
243 | |
244 | IMF_STD_ATTRIBUTE_DEF (, TimeCode, TimeCode) |
245 | |
246 | |
247 | // |
248 | // wrapmodes -- determines how texture map images are extrapolated. |
249 | // If an OpenEXR file is used as a texture map for 3D rendering, |
250 | // texture coordinates (0.0, 0.0) and (1.0, 1.0) correspond to |
251 | // the upper left and lower right corners of the data window. |
252 | // If the image is mapped onto a surface with texture coordinates |
253 | // outside the zero-to-one range, then the image must be extrapolated. |
254 | // This attribute tells the renderer how to do this extrapolation. |
255 | // The attribute contains either a pair of comma-separated keywords, |
256 | // to specify separate extrapolation modes for the horizontal and |
257 | // vertical directions; or a single keyword, to specify extrapolation |
258 | // in both directions (e.g. "clamp,periodic" or "clamp"). Extra white |
259 | // space surrounding the keywords is allowed, but should be ignored |
260 | // by the renderer ("clamp, black " is equivalent to "clamp,black"). |
261 | // The keywords listed below are predefined; some renderers may support |
262 | // additional extrapolation modes: |
263 | // |
264 | // black pixels outside the zero-to-one range are black |
265 | // |
266 | // clamp texture coordinates less than 0.0 and greater |
267 | // than 1.0 are clamped to 0.0 and 1.0 respectively |
268 | // |
269 | // periodic the texture image repeats periodically |
270 | // |
271 | // mirror the texture image repeats periodically, but |
272 | // every other instance is mirrored |
273 | // |
274 | |
275 | IMF_STD_ATTRIBUTE_DEF (, Wrapmodes, std::string) |
276 | |
277 | |
278 | // |
279 | // framesPerSecond -- defines the nominal playback frame rate for image |
280 | // sequences, in frames per second. Every image in a sequence should |
281 | // have a framesPerSecond attribute, and the attribute value should be |
282 | // the same for all images in the sequence. If an image sequence has |
283 | // no framesPerSecond attribute, playback software should assume that |
284 | // the frame rate for the sequence is 24 frames per second. |
285 | // |
286 | // In order to allow exact representation of NTSC frame and field rates, |
287 | // framesPerSecond is stored as a rational number. A rational number is |
288 | // a pair of integers, n and d, that represents the value n/d. |
289 | // |
290 | // For the exact values of commonly used frame rates, please see header |
291 | // file ImfFramesPerSecond.h. |
292 | // |
293 | |
294 | IMF_STD_ATTRIBUTE_DEF (, FramesPerSecond, Rational) |
295 | |
296 | |
297 | // |
298 | // multiView -- defines the view names for multi-view image files. |
299 | // A multi-view image contains two or more views of the same scene, |
300 | // as seen from different viewpoints, for example a left-eye and |
301 | // a right-eye view for stereo displays. The multiView attribute |
302 | // lists the names of the views in an image, and a naming convention |
303 | // identifies the channels that belong to each view. |
304 | // |
305 | // For details, please see header file ImfMultiView.h |
306 | // |
307 | |
308 | IMF_STD_ATTRIBUTE_DEF ( , MultiView, StringVector) |
309 | |
310 | |
311 | // |
312 | // worldToCamera -- for images generated by 3D computer graphics rendering, |
313 | // a matrix that transforms 3D points from the world to the camera coordinate |
314 | // space of the renderer. |
315 | // |
316 | // The camera coordinate space is left-handed. Its origin indicates the |
317 | // location of the camera. The positive x and y axes correspond to the |
318 | // "right" and "up" directions in the rendered image. The positive z |
319 | // axis indicates the camera's viewing direction. (Objects in front of |
320 | // the camera have positive z coordinates.) |
321 | // |
322 | // Camera coordinate space in OpenEXR is the same as in Pixar's Renderman. |
323 | // |
324 | |
325 | IMF_STD_ATTRIBUTE_DEF (, WorldToCamera, IMATH_NAMESPACE::M44f) |
326 | |
327 | |
328 | // |
329 | // worldToNDC -- for images generated by 3D computer graphics rendering, a |
330 | // matrix that transforms 3D points from the world to the Normalized Device |
331 | // Coordinate (NDC) space of the renderer. |
332 | // |
333 | // NDC is a 2D coordinate space that corresponds to the image plane, with |
334 | // positive x and pointing to the right and y positive pointing down. The |
335 | // coordinates (0, 0) and (1, 1) correspond to the upper left and lower right |
336 | // corners of the OpenEXR display window. |
337 | // |
338 | // To transform a 3D point in word space into a 2D point in NDC space, |
339 | // multiply the 3D point by the worldToNDC matrix and discard the z |
340 | // coordinate. |
341 | // |
342 | // NDC space in OpenEXR is the same as in Pixar's Renderman. |
343 | // |
344 | |
345 | IMF_STD_ATTRIBUTE_DEF (, WorldToNDC, IMATH_NAMESPACE::M44f) |
346 | |
347 | |
348 | // |
349 | // deepImageState -- specifies whether the pixels in a deep image are |
350 | // sorted and non-overlapping. |
351 | // |
352 | // Note: this attribute can be set by application code that writes a file |
353 | // in order to tell applications that read the file whether the pixel data |
354 | // must be cleaned up prior to image processing operations such as flattening. |
355 | // The IlmImf library does not verify that the attribute is consistent with |
356 | // the actual state of the pixels. Application software may assume that the |
357 | // attribute is valid, as long as the software will not crash or lock up if |
358 | // any pixels are inconsistent with the deepImageState attribute. |
359 | // |
360 | |
361 | IMF_STD_ATTRIBUTE_DEF (, DeepImageState, DeepImageState) |
362 | |
363 | |
364 | // |
365 | // originalDataWindow -- if application software crops an image, then it |
366 | // should save the data window of the original, un-cropped image in the |
367 | // originalDataWindow attribute. |
368 | // |
369 | |
370 | IMF_STD_ATTRIBUTE_DEF |
371 | (, OriginalDataWindow, IMATH_NAMESPACE::Box2i) |
372 | |
373 | |
374 | // |
375 | // dwaCompressionLevel -- sets the quality level for images compressed |
376 | // with the DWAA or DWAB method. |
377 | // |
378 | |
379 | IMF_STD_ATTRIBUTE_DEF (, DwaCompressionLevel, float) |
380 | |
381 | |
382 | #endif |
383 | |