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 
37#ifndef INCLUDED_IMF_HEADER_H 
38#define INCLUDED_IMF_HEADER_H 
39 
40//----------------------------------------------------------------------------- 
41// 
42// class Header 
43// 
44//----------------------------------------------------------------------------- 
45 
46#include "ImfLineOrder.h" 
47#include "ImfCompression.h" 
48#include "ImfName.h" 
49#include "ImfTileDescription.h" 
50#include "ImfInt64.h" 
51#include "ImathVec.h" 
52#include "ImathBox.h" 
53#include "IexBaseExc.h" 
54 
55#include "ImfForward.h" 
56#include "ImfNamespace.h" 
57#include "ImfExport.h" 
58 
59#include <map> 
60#include <iosfwd> 
61#include <string> 
62 
63 
64OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER 
65 
66using std::string; 
67 
68 
69class Header 
70{ 
71 public: 
72  
73 //---------------------------------------------------------------- 
74 // Default constructor -- the display window and the data window 
75 // are both set to Box2i (V2i (0, 0), V2i (width-1, height-1). 
76 //---------------------------------------------------------------- 
77 
78 IMF_EXPORT 
79 Header (int width = 64, 
80 int height = 64, 
81 float pixelAspectRatio = 1, 
82 const IMATH_NAMESPACE::V2f &screenWindowCenter = IMATH_NAMESPACE::V2f (0, 0), 
83 float screenWindowWidth = 1, 
84 LineOrder lineOrder = INCREASING_Y, 
85 Compression = ZIP_COMPRESSION); 
86 
87 
88 //-------------------------------------------------------------------- 
89 // Constructor -- the data window is specified explicitly; the display 
90 // window is set to Box2i (V2i (0, 0), V2i (width-1, height-1). 
91 //-------------------------------------------------------------------- 
92 
93 IMF_EXPORT 
94 Header (int width, 
95 int height, 
96 const IMATH_NAMESPACE::Box2i &dataWindow, 
97 float pixelAspectRatio = 1, 
98 const IMATH_NAMESPACE::V2f &screenWindowCenter = IMATH_NAMESPACE::V2f (0, 0), 
99 float screenWindowWidth = 1, 
100 LineOrder lineOrder = INCREASING_Y, 
101 Compression = ZIP_COMPRESSION); 
102 
103 
104 //---------------------------------------------------------- 
105 // Constructor -- the display window and the data window are 
106 // both specified explicitly. 
107 //---------------------------------------------------------- 
108 
109 IMF_EXPORT 
110 Header (const IMATH_NAMESPACE::Box2i &displayWindow, 
111 const IMATH_NAMESPACE::Box2i &dataWindow, 
112 float pixelAspectRatio = 1, 
113 const IMATH_NAMESPACE::V2f &screenWindowCenter = IMATH_NAMESPACE::V2f (0, 0), 
114 float screenWindowWidth = 1, 
115 LineOrder lineOrder = INCREASING_Y, 
116 Compression = ZIP_COMPRESSION); 
117 
118 
119 //----------------- 
120 // Copy constructor 
121 //----------------- 
122 
123 IMF_EXPORT 
124 Header (const Header &other); 
125 
126 
127 //----------- 
128 // Destructor 
129 //----------- 
130 
131 IMF_EXPORT 
132 ~Header (); 
133 
134 
135 //----------- 
136 // Assignment 
137 //----------- 
138 
139 IMF_EXPORT 
140 Header & operator = (const Header &other); 
141 
142 
143 //--------------------------------------------------------------- 
144 // Add an attribute: 
145 // 
146 // insert(n,attr) If no attribute with name n exists, a new 
147 // attribute with name n, and the same type as 
148 // attr, is added, and the value of attr is 
149 // copied into the new attribute. 
150 // 
151 // If an attribute with name n exists, and its 
152 // type is the same as attr, the value of attr 
153 // is copied into this attribute. 
154 // 
155 // If an attribute with name n exists, and its 
156 // type is different from attr, an IEX_NAMESPACE::TypeExc 
157 // is thrown. 
158 // 
159 //--------------------------------------------------------------- 
160 
161 IMF_EXPORT 
162 void insert (const char name[], 
163 const Attribute &attribute); 
164 
165 IMF_EXPORT 
166 void insert (const std::string &name, 
167 const Attribute &attribute); 
168 
169 //--------------------------------------------------------------- 
170 // Remove an attribute: 
171 // 
172 // remove(n) If an attribute with name n exists, then it 
173 // is removed from the map of present attributes. 
174 // 
175 // If no attribute with name n exists, then this 
176 // functions becomes a 'no-op' 
177 // 
178 //--------------------------------------------------------------- 
179 
180 IMF_EXPORT 
181 void erase (const char name[]); 
182 IMF_EXPORT 
183 void erase (const std::string &name); 
184 
185  
186  
187 //------------------------------------------------------------------ 
188 // Access to existing attributes: 
189 // 
190 // [n] Returns a reference to the attribute 
191 // with name n. If no attribute with 
192 // name n exists, an IEX_NAMESPACE::ArgExc is thrown. 
193 // 
194 // typedAttribute<T>(n) Returns a reference to the attribute 
195 // with name n and type T. If no attribute 
196 // with name n exists, an IEX_NAMESPACE::ArgExc is 
197 // thrown. If an attribute with name n 
198 // exists, but its type is not T, an 
199 // IEX_NAMESPACE::TypeExc is thrown. 
200 // 
201 // findTypedAttribute<T>(n) Returns a pointer to the attribute with 
202 // name n and type T, or 0 if no attribute 
203 // with name n and type T exists. 
204 // 
205 //------------------------------------------------------------------ 
206 
207 IMF_EXPORT 
208 Attribute & operator [] (const char name[]); 
209 IMF_EXPORT 
210 const Attribute & operator [] (const char name[]) const; 
211 
212 IMF_EXPORT 
213 Attribute & operator [] (const std::string &name); 
214 IMF_EXPORT 
215 const Attribute & operator [] (const std::string &name) const; 
216 
217 template <class T> T& typedAttribute (const char name[]); 
218 template <class T> const T& typedAttribute (const char name[]) const; 
219 
220 template <class T> T& typedAttribute (const std::string &name); 
221 template <class T> const T& typedAttribute (const std::string &name) const; 
222 
223 template <class T> T* findTypedAttribute (const char name[]); 
224 template <class T> const T* findTypedAttribute (const char name[]) const; 
225 
226 template <class T> T* findTypedAttribute (const std::string &name); 
227 template <class T> const T* findTypedAttribute (const std::string &name) 
228 const; 
229 
230 //--------------------------------------------- 
231 // Iterator-style access to existing attributes 
232 //--------------------------------------------- 
233 
234 typedef std::map <Name, Attribute *> AttributeMap; 
235 
236 class Iterator; 
237 class ConstIterator; 
238 
239 IMF_EXPORT 
240 Iterator begin (); 
241 IMF_EXPORT 
242 ConstIterator begin () const; 
243 
244 IMF_EXPORT 
245 Iterator end (); 
246 IMF_EXPORT 
247 ConstIterator end () const; 
248 
249 IMF_EXPORT 
250 Iterator find (const char name[]); 
251 IMF_EXPORT 
252 ConstIterator find (const char name[]) const; 
253 
254 IMF_EXPORT 
255 Iterator find (const std::string &name); 
256 IMF_EXPORT 
257 ConstIterator find (const std::string &name) const; 
258 
259 
260 //-------------------------------- 
261 // Access to predefined attributes 
262 //-------------------------------- 
263 
264 IMF_EXPORT 
265 IMATH_NAMESPACE::Box2i & displayWindow (); 
266 IMF_EXPORT 
267 const IMATH_NAMESPACE::Box2i & displayWindow () const; 
268 
269 IMF_EXPORT 
270 IMATH_NAMESPACE::Box2i & dataWindow (); 
271 IMF_EXPORT 
272 const IMATH_NAMESPACE::Box2i & dataWindow () const; 
273 
274 IMF_EXPORT 
275 float & pixelAspectRatio (); 
276 IMF_EXPORT 
277 const float & pixelAspectRatio () const; 
278 
279 IMF_EXPORT 
280 IMATH_NAMESPACE::V2f & screenWindowCenter (); 
281 IMF_EXPORT 
282 const IMATH_NAMESPACE::V2f & screenWindowCenter () const; 
283 
284 IMF_EXPORT 
285 float & screenWindowWidth (); 
286 IMF_EXPORT 
287 const float & screenWindowWidth () const; 
288 
289 IMF_EXPORT 
290 ChannelList & channels (); 
291 IMF_EXPORT 
292 const ChannelList & channels () const; 
293 
294 IMF_EXPORT 
295 LineOrder & lineOrder (); 
296 IMF_EXPORT 
297 const LineOrder & lineOrder () const; 
298 
299 IMF_EXPORT 
300 Compression & compression (); 
301 IMF_EXPORT 
302 const Compression & compression () const; 
303 
304 
305 //----------------------------------------------------- 
306 // Access to required attributes for multipart files 
307 // They are optional to non-multipart files and mandatory 
308 // for multipart files. 
309 //----------------------------------------------------- 
310 IMF_EXPORT 
311 void setName (const string& name); 
312 
313 IMF_EXPORT 
314 string& name(); 
315 IMF_EXPORT 
316 const string& name() const; 
317 
318 IMF_EXPORT 
319 bool hasName() const; 
320 
321 IMF_EXPORT 
322 void setType (const string& Type); 
323 
324 IMF_EXPORT 
325 string& type(); 
326 IMF_EXPORT 
327 const string& type() const; 
328 
329 IMF_EXPORT 
330 bool hasType() const; 
331 
332 IMF_EXPORT 
333 void setVersion (const int version); 
334 
335 IMF_EXPORT 
336 int& version(); 
337 IMF_EXPORT 
338 const int& version() const; 
339 
340 IMF_EXPORT 
341 bool hasVersion() const; 
342 
343 // 
344 // the chunkCount attribute is set automatically when a file is written. 
345 // There is no need to set it manually 
346 // 
347 IMF_EXPORT 
348 void setChunkCount(int chunks); 
349 IMF_EXPORT 
350 bool hasChunkCount() const; 
351 IMF_EXPORT 
352 const int & chunkCount() const; 
353 IMF_EXPORT 
354 int & chunkCount(); 
355 
356  
357 // 
358 // for multipart files, return whether the file has a view string attribute 
359 // (for the deprecated single part multiview format EXR, see ImfMultiView.h) 
360 // 
361 IMF_EXPORT 
362 void setView(const string & view); 
363 IMF_EXPORT 
364 bool hasView() const; 
365 IMF_EXPORT 
366 string & view(); 
367 IMF_EXPORT 
368 const string & view() const; 
369  
370 
371 //---------------------------------------------------------------------- 
372 // Tile Description: 
373 // 
374 // The tile description is a TileDescriptionAttribute whose name 
375 // is "tiles". The "tiles" attribute must be present in any tiled 
376 // image file. When present, it describes various properties of the 
377 // tiles that make up the file. 
378 // 
379 // Convenience functions: 
380 // 
381 // setTileDescription(td) 
382 // calls insert ("tiles", TileDescriptionAttribute (td)) 
383 // 
384 // tileDescription() 
385 // returns typedAttribute<TileDescriptionAttribute>("tiles").value() 
386 // 
387 // hasTileDescription() 
388 // return findTypedAttribute<TileDescriptionAttribute>("tiles") != 0 
389 // 
390 //---------------------------------------------------------------------- 
391 
392 IMF_EXPORT 
393 void setTileDescription (const TileDescription & td); 
394 
395 IMF_EXPORT 
396 TileDescription & tileDescription (); 
397 IMF_EXPORT 
398 const TileDescription & tileDescription () const; 
399 
400 IMF_EXPORT 
401 bool hasTileDescription() const; 
402 
403 
404 //---------------------------------------------------------------------- 
405 // Preview image: 
406 // 
407 // The preview image is a PreviewImageAttribute whose name is "preview". 
408 // This attribute is special -- while an image file is being written, 
409 // the pixels of the preview image can be changed repeatedly by calling 
410 // OutputFile::updatePreviewImage(). 
411 // 
412 // Convenience functions: 
413 // 
414 // setPreviewImage(p) 
415 // calls insert ("preview", PreviewImageAttribute (p)) 
416 // 
417 // previewImage() 
418 // returns typedAttribute<PreviewImageAttribute>("preview").value() 
419 // 
420 // hasPreviewImage() 
421 // return findTypedAttribute<PreviewImageAttribute>("preview") != 0 
422 // 
423 //---------------------------------------------------------------------- 
424 
425 IMF_EXPORT 
426 void setPreviewImage (const PreviewImage &p); 
427 
428 IMF_EXPORT 
429 PreviewImage & previewImage (); 
430 IMF_EXPORT 
431 const PreviewImage & previewImage () const; 
432 
433 IMF_EXPORT 
434 bool hasPreviewImage () const; 
435 
436 
437 //------------------------------------------------------------- 
438 // Sanity check -- examines the header, and throws an exception 
439 // if it finds something wrong (empty display window, negative 
440 // pixel aspect ratio, unknown compression sceme etc.) 
441 // 
442 // set isTiled to true if you are checking a tiled/multi-res 
443 // header 
444 //------------------------------------------------------------- 
445 
446 IMF_EXPORT 
447 void sanityCheck (bool isTiled = false, 
448 bool isMultipartFile = false) const; 
449 
450 
451 //---------------------------------------------------------------- 
452 // Maximum image size and maximim tile size: 
453 // 
454 // sanityCheck() will throw an exception if the width or height of 
455 // the data window exceeds the maximum image width or height, or 
456 // if the size of a tile exceeds the maximum tile width or height. 
457 //  
458 // At program startup the maximum image and tile width and height 
459 // are set to zero, meaning that width and height are unlimited. 
460 // 
461 // Limiting image and tile width and height limits how much memory 
462 // will be allocated when a file is opened. This can help protect 
463 // applications from running out of memory while trying to read 
464 // a damaged image file. 
465 //---------------------------------------------------------------- 
466 
467 IMF_EXPORT 
468 static void setMaxImageSize (int maxWidth, int maxHeight); 
469 IMF_EXPORT 
470 static void setMaxTileSize (int maxWidth, int maxHeight); 
471 
472 // 
473 // Check if the header reads nothing. 
474 // 
475 IMF_EXPORT 
476 bool readsNothing(); 
477 
478 
479 //------------------------------------------------------------------ 
480 // Input and output: 
481 // 
482 // If the header contains a preview image attribute, then writeTo() 
483 // returns the position of that attribute in the output stream; this 
484 // information is used by OutputFile::updatePreviewImage(). 
485 // If the header contains no preview image attribute, then writeTo() 
486 // returns 0. 
487 //------------------------------------------------------------------ 
488 
489 
490 IMF_EXPORT 
491 Int64 writeTo (OPENEXR_IMF_INTERNAL_NAMESPACE::OStream &os, 
492 bool isTiled = false) const; 
493 
494 IMF_EXPORT 
495 void readFrom (OPENEXR_IMF_INTERNAL_NAMESPACE::IStream &is, 
496 int &version); 
497  
498 
499 private: 
500 
501 AttributeMap _map; 
502 
503 bool _readsNothing; 
504}; 
505 
506 
507//---------- 
508// Iterators 
509//---------- 
510 
511class Header::Iterator 
512{ 
513 public: 
514 
515 IMF_EXPORT 
516 Iterator (); 
517 IMF_EXPORT 
518 Iterator (const Header::AttributeMap::iterator &i); 
519 
520 IMF_EXPORT 
521 Iterator & operator ++ (); 
522 IMF_EXPORT 
523 Iterator operator ++ (int); 
524 
525 IMF_EXPORT 
526 const char * name () const; 
527 IMF_EXPORT 
528 Attribute & attribute () const; 
529 
530 private: 
531 
532 friend class Header::ConstIterator; 
533 
534 Header::AttributeMap::iterator _i; 
535}; 
536 
537 
538class Header::ConstIterator 
539{ 
540 public: 
541 
542 IMF_EXPORT 
543 ConstIterator (); 
544 IMF_EXPORT 
545 ConstIterator (const Header::AttributeMap::const_iterator &i); 
546 IMF_EXPORT 
547 ConstIterator (const Header::Iterator &other); 
548 
549 IMF_EXPORT 
550 ConstIterator & operator ++ (); 
551 IMF_EXPORT 
552 ConstIterator operator ++ (int); 
553 
554 IMF_EXPORT 
555 const char * name () const; 
556 IMF_EXPORT 
557 const Attribute & attribute () const; 
558 
559 private: 
560 
561 friend bool operator == (const ConstIterator &, const ConstIterator &); 
562 friend bool operator != (const ConstIterator &, const ConstIterator &); 
563 
564 Header::AttributeMap::const_iterator _i; 
565}; 
566 
567 
568//------------------------------------------------------------------------ 
569// Library initialization: 
570// 
571// In a multithreaded program, staticInitialize() must be called once 
572// during startup, before the program accesses any other functions or 
573// classes in the IlmImf library. Calling staticInitialize() in this 
574// way avoids races during initialization of the library's global 
575// variables. 
576// 
577// Single-threaded programs are not required to call staticInitialize(); 
578// initialization of the library's global variables happens automatically. 
579// 
580//------------------------------------------------------------------------ 
581 
582void IMF_EXPORT staticInitialize (); 
583 
584 
585//----------------- 
586// Inline Functions 
587//----------------- 
588 
589 
590inline 
591Header::Iterator::Iterator (): _i() 
592{ 
593 // empty 
594} 
595 
596 
597inline 
598Header::Iterator::Iterator (const Header::AttributeMap::iterator &i): _i (i) 
599{ 
600 // empty 
601} 
602 
603 
604inline Header::Iterator &  
605Header::Iterator::operator ++ () 
606{ 
607 ++_i; 
608 return *this; 
609} 
610 
611 
612inline Header::Iterator  
613Header::Iterator::operator ++ (int) 
614{ 
615 Iterator tmp = *this; 
616 ++_i; 
617 return tmp; 
618} 
619 
620 
621inline const char * 
622Header::Iterator::name () const 
623{ 
624 return *_i->first; 
625} 
626 
627 
628inline Attribute &  
629Header::Iterator::attribute () const 
630{ 
631 return *_i->second; 
632} 
633 
634 
635inline 
636Header::ConstIterator::ConstIterator (): _i() 
637{ 
638 // empty 
639} 
640 
641inline 
642Header::ConstIterator::ConstIterator 
643 (const Header::AttributeMap::const_iterator &i): _i (i) 
644{ 
645 // empty 
646} 
647 
648 
649inline 
650Header::ConstIterator::ConstIterator (const Header::Iterator &other): 
651 _i (other._i) 
652{ 
653 // empty 
654} 
655 
656inline Header::ConstIterator & 
657Header::ConstIterator::operator ++ () 
658{ 
659 ++_i; 
660 return *this; 
661} 
662 
663 
664inline Header::ConstIterator  
665Header::ConstIterator::operator ++ (int) 
666{ 
667 ConstIterator tmp = *this; 
668 ++_i; 
669 return tmp; 
670} 
671 
672 
673inline const char * 
674Header::ConstIterator::name () const 
675{ 
676 return *_i->first; 
677} 
678 
679 
680inline const Attribute &  
681Header::ConstIterator::attribute () const 
682{ 
683 return *_i->second; 
684} 
685 
686 
687inline bool 
688operator == (const Header::ConstIterator &x, const Header::ConstIterator &y) 
689{ 
690 return x._i == y._i; 
691} 
692 
693 
694inline bool 
695operator != (const Header::ConstIterator &x, const Header::ConstIterator &y) 
696{ 
697 return !(x == y); 
698} 
699 
700 
701//--------------------- 
702// Template definitions 
703//--------------------- 
704 
705template <class T> 
706T & 
707Header::typedAttribute (const char name[]) 
708{ 
709 Attribute *attr = &(*this)[name]; 
710 T *tattr = dynamic_cast <T*> (attr); 
711 
712 if (tattr == 0) 
713 throw IEX_NAMESPACE::TypeExc ("Unexpected attribute type."); 
714 
715 return *tattr; 
716} 
717 
718 
719template <class T> 
720const T & 
721Header::typedAttribute (const char name[]) const 
722{ 
723 const Attribute *attr = &(*this)[name]; 
724 const T *tattr = dynamic_cast <const T*> (attr); 
725 
726 if (tattr == 0) 
727 throw IEX_NAMESPACE::TypeExc ("Unexpected attribute type."); 
728 
729 return *tattr; 
730} 
731 
732 
733template <class T> 
734T & 
735Header::typedAttribute (const std::string &name) 
736{ 
737 return typedAttribute<T> (name.c_str()); 
738} 
739 
740 
741template <class T> 
742const T & 
743Header::typedAttribute (const std::string &name) const 
744{ 
745 return typedAttribute<T> (name.c_str()); 
746} 
747 
748 
749template <class T> 
750T * 
751Header::findTypedAttribute (const char name[]) 
752{ 
753 AttributeMap::iterator i = _map.find (name); 
754 return (i == _map.end())? 0: dynamic_cast <T*> (i->second); 
755} 
756 
757 
758template <class T> 
759const T * 
760Header::findTypedAttribute (const char name[]) const 
761{ 
762 AttributeMap::const_iterator i = _map.find (name); 
763 return (i == _map.end())? 0: dynamic_cast <const T*> (i->second); 
764} 
765 
766 
767template <class T> 
768T * 
769Header::findTypedAttribute (const std::string &name) 
770{ 
771 return findTypedAttribute<T> (name.c_str()); 
772} 
773 
774 
775template <class T> 
776const T * 
777Header::findTypedAttribute (const std::string &name) const 
778{ 
779 return findTypedAttribute<T> (name.c_str()); 
780} 
781 
782 
783OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT 
784 
785#endif 
786