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

source code of include/OpenEXR/ImfStandardAttributes.h