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 <ImfChromaticitiesAttribute.h> 59#include <ImfEnvmapAttribute.h> 60#include <ImfFloatAttribute.h> 61#include <ImfKeyCodeAttribute.h> 62#include <ImfMatrixAttribute.h> 63#include <ImfRationalAttribute.h> 64#include <ImfStringAttribute.h> 65#include <ImfStringVectorAttribute.h> 66#include <ImfTimeCodeAttribute.h> 67#include <ImfVecAttribute.h> 68 69#define IMF_STD_ATTRIBUTE_DEF(name,suffix,type) \ 70 \ 71 void add##suffix (Header &header, const type &v); \ 72 bool has##suffix (const Header &header); \ 73 const TypedAttribute<type> & name##Attribute (const Header &header); \ 74 TypedAttribute<type> & name##Attribute (Header &header); \ 75 const type & name (const Header &header); \ 76 type & name (Header &header); 77 78 79namespace Imf { 80 81// 82// chromaticities -- for RGB images, specifies the CIE (x,y) 83// chromaticities of the primaries and the white point 84// 85 86IMF_STD_ATTRIBUTE_DEF (chromaticities, Chromaticities, Chromaticities) 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 100IMF_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 110IMF_STD_ATTRIBUTE_DEF (adoptedNeutral, AdoptedNeutral, Imath::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 119IMF_STD_ATTRIBUTE_DEF (renderingTransform, RenderingTransform, std::string) 120IMF_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 128IMF_STD_ATTRIBUTE_DEF (xDensity, XDensity, float) 129 130 131// 132// owner -- name of the owner of the image 133// 134 135IMF_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 143IMF_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 159IMF_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 169IMF_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 180IMF_STD_ATTRIBUTE_DEF (longitude, Longitude, float) 181IMF_STD_ATTRIBUTE_DEF (latitude, Latitude, float) 182IMF_STD_ATTRIBUTE_DEF (altitude, Altitude, float) 183 184 185// 186// focus -- the camera's focus distance, in meters 187// 188 189IMF_STD_ATTRIBUTE_DEF (focus, Focus, float) 190 191 192// 193// exposure -- exposure time, in seconds 194// 195 196IMF_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 204IMF_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 212IMF_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 222IMF_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 231IMF_STD_ATTRIBUTE_DEF (keyCode, KeyCode, KeyCode) 232 233 234// 235// timeCode -- time and control code 236// 237 238IMF_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 269IMF_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 288IMF_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 302IMF_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 319IMF_STD_ATTRIBUTE_DEF (worldToCamera, WorldToCamera, Imath::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 339IMF_STD_ATTRIBUTE_DEF (worldToNDC, WorldToNDC, Imath::M44f) 340 341} // namespace Imf 342 343#endif 344