1 ///////////////////////////////////////////////////////////////////////////
3 // Copyright (c) 2004, Industrial Light & Magic, a division of Lucas
6 // All rights reserved.
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
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
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.
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.
33 ///////////////////////////////////////////////////////////////////////////
36 #ifndef INCLUDED_IMF_STANDARD_ATTRIBUTES_H
37 #define INCLUDED_IMF_STANDARD_ATTRIBUTES_H
39 //-----------------------------------------------------------------------------
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.
45 // For each attribute, with name "foo", and type "T", the following
46 // functions are automatically generated via macros:
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);
55 //-----------------------------------------------------------------------------
57 #include <ImfHeader.h>
58 #include <ImfFloatAttribute.h>
59 #include <ImfStringAttribute.h>
60 #include <ImfChromaticitiesAttribute.h>
61 #include <ImfEnvmapAttribute.h>
62 #include <ImfKeyCodeAttribute.h>
63 #include <ImfTimeCodeAttribute.h>
66 #define IMF_STD_ATTRIBUTE_DEF(name,suffix,type) \
68 void add##suffix (Header &header, const type &v); \
69 bool has##suffix (const Header &header); \
70 const TypedAttribute<type> & name##Attribute (const Header &header); \
71 TypedAttribute<type> & name##Attribute (Header &header); \
72 const type & name (const Header &header); \
73 type & name (Header &header);
79 // chromaticities -- for RGB images, specifies the CIE (x,y)
80 // chromaticities of the primaries and the white point
83 IMF_STD_ATTRIBUTE_DEF (chromaticities, Chromaticities, Chromaticities)
87 // whiteLuminance -- for RGB images, defines the luminance, in Nits
88 // (candelas per square meter) of the RGB value (1.0, 1.0, 1.0).
90 // If the chromaticities and the whiteLuminance of an RGB image are
91 // known, then it is possible to convert the image's pixels from RGB
92 // to CIE XYZ tristimulus values (see function RGBtoXYZ() in header
93 // file ImfChromaticities.h).
97 IMF_STD_ATTRIBUTE_DEF (whiteLuminance, WhiteLuminance, float)
101 // xDensity -- horizontal output density, in pixels per inch.
102 // The image's vertical output density is xDensity * pixelAspectRatio.
105 IMF_STD_ATTRIBUTE_DEF (xDensity, XDensity, float)
109 // owner -- name of the owner of the image
112 IMF_STD_ATTRIBUTE_DEF (owner, Owner, std::string)
116 // comments -- additional image information in human-readable
117 // form, for example a verbal description of the image
120 IMF_STD_ATTRIBUTE_DEF (comments, Comments, std::string)
124 // capDate -- the date when the image was created or captured,
125 // in local time, and formatted as
127 // YYYY:MM:DD hh:mm:ss
129 // where YYYY is the year (4 digits, e.g. 2003), MM is the month
130 // (2 digits, 01, 02, ... 12), DD is the day of the month (2 digits,
131 // 01, 02, ... 31), hh is the hour (2 digits, 00, 01, ... 23), mm
132 // is the minute, and ss is the second (2 digits, 00, 01, ... 59).
136 IMF_STD_ATTRIBUTE_DEF (capDate, CapDate, std::string)
140 // utcOffset -- offset of local time at capDate from
141 // Universal Coordinated Time (UTC), in seconds:
143 // UTC == local time + utcOffset
146 IMF_STD_ATTRIBUTE_DEF (utcOffset, utcOffset, float)
150 // longitude, latitude, altitude -- for images of real objects, the
151 // location where the image was recorded. Longitude and latitude are
152 // in degrees east of Greenwich and north of the equator. Altitude
153 // is in meters above sea level. For example, Kathmandu, Nepal is
154 // at longitude 85.317, latitude 27.717, altitude 1305.
157 IMF_STD_ATTRIBUTE_DEF (longitude, Longitude, float)
158 IMF_STD_ATTRIBUTE_DEF (latitude, Latitude, float)
159 IMF_STD_ATTRIBUTE_DEF (altitude, Altitude, float)
163 // focus -- the camera's focus distance, in meters
166 IMF_STD_ATTRIBUTE_DEF (focus, Focus, float)
170 // exposure -- exposure time, in seconds
173 IMF_STD_ATTRIBUTE_DEF (expTime, ExpTime, float)
177 // aperture -- the camera's lens aperture, in f-stops (focal length
178 // of the lens divided by the diameter of the iris opening)
181 IMF_STD_ATTRIBUTE_DEF (aperture, Aperture, float)
185 // isoSpeed -- the ISO speed of the film or image sensor
186 // that was used to record the image
189 IMF_STD_ATTRIBUTE_DEF (isoSpeed, IsoSpeed, float)
193 // envmap -- if this attribute is present, the image represents
194 // an environment map. The attribute's value defines how 3D
195 // directions are mapped to 2D pixel locations. For details
196 // see header file ImfEnvmap.h
199 IMF_STD_ATTRIBUTE_DEF (envmap, Envmap, Envmap)
203 // keyCode -- for motion picture film frames. Identifies film
204 // manufacturer, film type, film roll and frame position within
208 IMF_STD_ATTRIBUTE_DEF (keyCode, KeyCode, KeyCode)
212 // timeCode -- time and control code
215 IMF_STD_ATTRIBUTE_DEF (timeCode, TimeCode, TimeCode)
219 // wrapmodes -- determines how texture map images are extrapolated.
220 // If an OpenEXR file is used as a texture map for 3D rendering,
221 // texture coordinates (0.0, 0.0) and (1.0, 1.0) correspond to
222 // the upper left and lower right corners of the data window.
223 // If the image is mapped onto a surface with texture coordinates
224 // outside the zero-to-one range, then the image must be extrapolated.
225 // This attribute tells the renderer how to do this extrapolation.
226 // The attribute contains either a pair of comma-separated keywords,
227 // to specify separate extrapolation modes for the horizontal and
228 // vertical directions; or a single keyword, to specify extrapolation
229 // in both directions (e.g. "clamp,periodic" or "clamp"). Extra white
230 // space surrounding the keywords is allowed, but should be ignored
231 // by the renderer ("clamp, black " is equivalent to "clamp,black").
232 // The keywords listed below are predefined; some renderers may support
233 // additional extrapolation modes:
235 // black pixels outside the zero-to-one range are black
237 // clamp texture coordinates less than 0.0 and greater
238 // than 1.0 are clamped to 0.0 and 1.0 respectively
240 // periodic the texture image repeats periodically
242 // mirror the texture image repeats periodically, but
243 // every other instance is mirrored
246 IMF_STD_ATTRIBUTE_DEF (wrapmodes, Wrapmodes, std::string)