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 ///////////////////////////////////////////////////////////////////////////
37 #ifndef INCLUDED_IMF_HEADER_H
38 #define INCLUDED_IMF_HEADER_H
40 //-----------------------------------------------------------------------------
44 //-----------------------------------------------------------------------------
46 #include <ImfLineOrder.h>
47 #include <ImfCompression.h>
49 #include <ImfTileDescription.h>
53 #include "IexBaseExc.h"
71 //----------------------------------------------------------------
72 // Default constructor -- the display window and the data window
73 // are both set to Box2i (V2i (0, 0), V2i (width-1, height-1).
74 //----------------------------------------------------------------
76 Header (int width = 64,
78 float pixelAspectRatio = 1,
79 const Imath::V2f &screenWindowCenter = Imath::V2f (0, 0),
80 float screenWindowWidth = 1,
81 LineOrder lineOrder = INCREASING_Y,
82 Compression = ZIP_COMPRESSION);
85 //--------------------------------------------------------------------
86 // Constructor -- the data window is specified explicitly; the display
87 // window is set to Box2i (V2i (0, 0), V2i (width-1, height-1).
88 //--------------------------------------------------------------------
92 const Imath::Box2i &dataWindow,
93 float pixelAspectRatio = 1,
94 const Imath::V2f &screenWindowCenter = Imath::V2f (0, 0),
95 float screenWindowWidth = 1,
96 LineOrder lineOrder = INCREASING_Y,
97 Compression = ZIP_COMPRESSION);
100 //----------------------------------------------------------
101 // Constructor -- the display window and the data window are
102 // both specified explicitly.
103 //----------------------------------------------------------
105 Header (const Imath::Box2i &displayWindow,
106 const Imath::Box2i &dataWindow,
107 float pixelAspectRatio = 1,
108 const Imath::V2f &screenWindowCenter = Imath::V2f (0, 0),
109 float screenWindowWidth = 1,
110 LineOrder lineOrder = INCREASING_Y,
111 Compression = ZIP_COMPRESSION);
118 Header (const Header &other);
132 Header & operator = (const Header &other);
135 //---------------------------------------------------------------
138 // insert(n,attr) If no attribute with name n exists, a new
139 // attribute with name n, and the same type as
140 // attr, is added, and the value of attr is
141 // copied into the new attribute.
143 // If an attribute with name n exists, and its
144 // type is the same as attr, the value of attr
145 // is copied into this attribute.
147 // If an attribute with name n exists, and its
148 // type is different from attr, an Iex::TypeExc
151 //---------------------------------------------------------------
153 void insert (const char name[],
154 const Attribute &attribute);
156 //------------------------------------------------------------------
157 // Access to existing attributes:
159 // [n] Returns a reference to the attribute
160 // with name n. If no attribute with
161 // name n exists, an Iex::ArgExc is thrown.
163 // typedAttribute<T>(n) Returns a reference to the attribute
164 // with name n and type T. If no attribute
165 // with name n exists, an Iex::ArgExc is
166 // thrown. If an attribute with name n
167 // exists, but its type is not T, an
168 // Iex::TypeExc is thrown.
170 // findTypedAttribute<T>(n) Returns a pointer to the attribute with
171 // name n and type T, or 0 if no attribute
172 // with name n and type T exists.
174 //------------------------------------------------------------------
176 Attribute & operator [] (const char name[]);
177 const Attribute & operator [] (const char name[]) const;
179 template <class T> T& typedAttribute (const char name[]);
180 template <class T> const T& typedAttribute (const char name[]) const;
182 template <class T> T* findTypedAttribute (const char name[]);
183 template <class T> const T* findTypedAttribute (const char name[]) const;
186 //---------------------------------------------
187 // Iterator-style access to existing attributes
188 //---------------------------------------------
190 typedef std::map <Name, Attribute *> AttributeMap;
196 ConstIterator begin () const;
198 ConstIterator end () const;
199 Iterator find (const char name[]);
200 ConstIterator find (const char name[]) const;
203 //--------------------------------
204 // Access to predefined attributes
205 //--------------------------------
207 Imath::Box2i & displayWindow ();
208 const Imath::Box2i & displayWindow () const;
210 Imath::Box2i & dataWindow ();
211 const Imath::Box2i & dataWindow () const;
213 float & pixelAspectRatio ();
214 const float & pixelAspectRatio () const;
216 Imath::V2f & screenWindowCenter ();
217 const Imath::V2f & screenWindowCenter () const;
219 float & screenWindowWidth ();
220 const float & screenWindowWidth () const;
222 ChannelList & channels ();
223 const ChannelList & channels () const;
225 LineOrder & lineOrder ();
226 const LineOrder & lineOrder () const;
228 Compression & compression ();
229 const Compression & compression () const;
232 //----------------------------------------------------------------------
235 // The tile description is a TileDescriptionAttribute whose name
236 // is "tiles". The "tiles" attribute must be present in any tiled
237 // image file. When present, it describes various properties of the
238 // tiles that make up the file.
240 // Convenience functions:
242 // setTileDescription(td)
243 // calls insert ("tiles", TileDescriptionAttribute (td))
246 // returns typedAttribute<TileDescriptionAttribute>("tiles").value()
248 // hasTileDescription()
249 // return findTypedAttribute<TileDescriptionAttribute>("tiles") != 0
251 //----------------------------------------------------------------------
253 void setTileDescription (const TileDescription & td);
255 TileDescription & tileDescription ();
256 const TileDescription & tileDescription () const;
258 bool hasTileDescription() const;
261 //----------------------------------------------------------------------
264 // The preview image is a PreviewImageAttribute whose name is "preview".
265 // This attribute is special -- while an image file is being written,
266 // the pixels of the preview image can be changed repeatedly by calling
267 // OutputFile::updatePreviewImage().
269 // Convenience functions:
271 // setPreviewImage(p)
272 // calls insert ("preview", PreviewImageAttribute (p))
275 // returns typedAttribute<PreviewImageAttribute>("preview").value()
278 // return findTypedAttribute<PreviewImageAttribute>("preview") != 0
280 //----------------------------------------------------------------------
282 void setPreviewImage (const PreviewImage &p);
284 PreviewImage & previewImage ();
285 const PreviewImage & previewImage () const;
287 bool hasPreviewImage () const;
290 //-------------------------------------------------------------
291 // Sanity check -- examines the header, and throws an exception
292 // if it finds something wrong (empty display window, negative
293 // pixel aspect ratio, unknown compression sceme etc.)
295 // set isTiled to true if you are checking a tiled/multi-res
297 //-------------------------------------------------------------
299 void sanityCheck (bool isTiled = false) const;
302 //------------------------------------------------------------------
305 // If the header contains a preview image attribute, then writeTo()
306 // returns the position of that attribute in the output stream; this
307 // information is used by OutputFile::updatePreviewImage().
308 // If the header contains no preview image attribute, then writeTo()
310 //------------------------------------------------------------------
313 Int64 writeTo (OStream &os,
314 bool isTiled = false) const;
316 void readFrom (IStream &is, int &version);
328 class Header::Iterator
333 Iterator (const Header::AttributeMap::iterator &i);
335 Iterator & operator ++ ();
336 Iterator operator ++ (int);
338 const char * name () const;
339 Attribute & attribute () const;
343 friend class Header::ConstIterator;
345 Header::AttributeMap::iterator _i;
349 class Header::ConstIterator
354 ConstIterator (const Header::AttributeMap::const_iterator &i);
355 ConstIterator (const Header::Iterator &other);
357 ConstIterator & operator ++ ();
358 ConstIterator operator ++ (int);
360 const char * name () const;
361 const Attribute & attribute () const;
365 friend bool operator == (const ConstIterator &, const ConstIterator &);
366 friend bool operator != (const ConstIterator &, const ConstIterator &);
368 Header::AttributeMap::const_iterator _i;
372 //------------------------------------------------------------------------
373 // Library initialization:
375 // In a multithreaded program, staticInitialize() must be called once
376 // during startup, before the program accesses any other functions or
377 // classes in the IlmImf library. Calling staticInitialize() in this
378 // way avoids races during initialization of the library's global
381 // Single-threaded programs are not required to call staticInitialize();
382 // initialization of the library's global variables happens automatically.
384 //------------------------------------------------------------------------
386 void staticInitialize ();
395 Header::Iterator::Iterator (): _i()
402 Header::Iterator::Iterator (const Header::AttributeMap::iterator &i): _i (i)
408 inline Header::Iterator &
409 Header::Iterator::operator ++ ()
416 inline Header::Iterator
417 Header::Iterator::operator ++ (int)
419 Iterator tmp = *this;
426 Header::Iterator::name () const
433 Header::Iterator::attribute () const
440 Header::ConstIterator::ConstIterator (): _i()
446 Header::ConstIterator::ConstIterator
447 (const Header::AttributeMap::const_iterator &i): _i (i)
454 Header::ConstIterator::ConstIterator (const Header::Iterator &other):
460 inline Header::ConstIterator &
461 Header::ConstIterator::operator ++ ()
468 inline Header::ConstIterator
469 Header::ConstIterator::operator ++ (int)
471 ConstIterator tmp = *this;
478 Header::ConstIterator::name () const
484 inline const Attribute &
485 Header::ConstIterator::attribute () const
492 operator == (const Header::ConstIterator &x, const Header::ConstIterator &y)
499 operator != (const Header::ConstIterator &x, const Header::ConstIterator &y)
505 //---------------------
506 // Template definitions
507 //---------------------
511 Header::typedAttribute (const char name[])
513 Attribute *attr = &(*this)[name];
514 T *tattr = dynamic_cast <T*> (attr);
517 throw Iex::TypeExc ("Unexpected attribute type.");
525 Header::typedAttribute (const char name[]) const
527 const Attribute *attr = &(*this)[name];
528 const T *tattr = dynamic_cast <const T*> (attr);
531 throw Iex::TypeExc ("Unexpected attribute type.");
539 Header::findTypedAttribute (const char name[])
541 AttributeMap::iterator i = _map.find (name);
542 return (i == _map.end())? 0: dynamic_cast <T*> (i->second);
548 Header::findTypedAttribute (const char name[]) const
550 AttributeMap::const_iterator i = _map.find (name);
551 return (i == _map.end())? 0: dynamic_cast <const T*> (i->second);