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