source: NonGTP/OpenEXR/include/IlmImf/ImfHeader.h @ 855

Revision 855, 14.5 KB checked in by igarcia, 19 years ago (diff)
Line 
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#include <map>
55#include <iosfwd>
56
57namespace Imf {
58
59
60class Attribute;
61class ChannelList;
62class IStream;
63class OStream;
64class PreviewImage;
65
66
67class Header
68{
69  public:
70   
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    //----------------------------------------------------------------
75
76    Header (int width = 64,
77            int height = 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);
83
84
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    //--------------------------------------------------------------------
89
90    Header (int width,
91            int height,
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);
98
99
100    //----------------------------------------------------------
101    // Constructor -- the display window and the data window are
102    // both specified explicitly.
103    //----------------------------------------------------------
104
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);
112
113
114    //-----------------
115    // Copy constructor
116    //-----------------
117
118    Header (const Header &other);
119
120
121    //-----------
122    // Destructor
123    //-----------
124
125    ~Header ();
126
127
128    //-----------
129    // Assignment
130    //-----------
131
132    Header &                    operator = (const Header &other);
133
134
135    //---------------------------------------------------------------
136    // Add an attribute:
137    //
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.
142    //
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.
146    //
147    //                  If an attribute with name n exists, and its
148    //                  type is different from attr, an Iex::TypeExc
149    //                  is thrown.
150    //
151    //---------------------------------------------------------------
152
153    void                        insert (const char name[],
154                                        const Attribute &attribute);
155
156    //------------------------------------------------------------------
157    // Access to existing attributes:
158    //
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.
162    //
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.
169    //
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.
173    //
174    //------------------------------------------------------------------
175
176    Attribute &                 operator [] (const char name[]);
177    const Attribute &           operator [] (const char name[]) const;
178
179    template <class T> T&       typedAttribute (const char name[]);
180    template <class T> const T& typedAttribute (const char name[]) const;
181
182    template <class T> T*       findTypedAttribute (const char name[]);
183    template <class T> const T* findTypedAttribute (const char name[]) const;
184
185
186    //---------------------------------------------
187    // Iterator-style access to existing attributes
188    //---------------------------------------------
189
190    typedef std::map <Name, Attribute *> AttributeMap;
191
192    class Iterator;
193    class ConstIterator;
194
195    Iterator                    begin ();
196    ConstIterator               begin () const;
197    Iterator                    end ();
198    ConstIterator               end () const;
199    Iterator                    find (const char name[]);
200    ConstIterator               find (const char name[]) const;
201
202
203    //--------------------------------
204    // Access to predefined attributes
205    //--------------------------------
206
207    Imath::Box2i &              displayWindow ();
208    const Imath::Box2i &        displayWindow () const;
209
210    Imath::Box2i &              dataWindow ();
211    const Imath::Box2i &        dataWindow () const;
212
213    float &                     pixelAspectRatio ();
214    const float &               pixelAspectRatio () const;
215
216    Imath::V2f &                screenWindowCenter ();
217    const Imath::V2f &          screenWindowCenter () const;
218
219    float &                     screenWindowWidth ();
220    const float &               screenWindowWidth () const;
221
222    ChannelList &               channels ();
223    const ChannelList &         channels () const;
224
225    LineOrder &                 lineOrder ();
226    const LineOrder &           lineOrder () const;
227
228    Compression &               compression ();
229    const Compression &         compression () const;
230
231
232    //----------------------------------------------------------------------
233    // Tile Description:
234    //
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.
239    //
240    // Convenience functions:
241    //
242    // setTileDescription(td)
243    //     calls insert ("tiles", TileDescriptionAttribute (td))
244    //
245    // tileDescription()
246    //     returns typedAttribute<TileDescriptionAttribute>("tiles").value()
247    //
248    // hasTileDescription()
249    //     return findTypedAttribute<TileDescriptionAttribute>("tiles") != 0
250    //
251    //----------------------------------------------------------------------
252
253    void                        setTileDescription (const TileDescription & td);
254
255    TileDescription &           tileDescription ();
256    const TileDescription &     tileDescription () const;
257
258    bool                        hasTileDescription() const;
259
260
261    //----------------------------------------------------------------------
262    // Preview image:
263    //
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().
268    //
269    // Convenience functions:
270    //
271    // setPreviewImage(p)
272    //     calls insert ("preview", PreviewImageAttribute (p))
273    //
274    // previewImage()
275    //     returns typedAttribute<PreviewImageAttribute>("preview").value()
276    //
277    // hasPreviewImage()
278    //     return findTypedAttribute<PreviewImageAttribute>("preview") != 0
279    //
280    //----------------------------------------------------------------------
281
282    void                        setPreviewImage (const PreviewImage &p);
283
284    PreviewImage &              previewImage ();
285    const PreviewImage &        previewImage () const;
286
287    bool                        hasPreviewImage () const;
288
289
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.)
294    //
295    // set isTiled to true if you are checking a tiled/multi-res
296    // header
297    //-------------------------------------------------------------
298
299    void                        sanityCheck (bool isTiled = false) const;
300
301
302    //------------------------------------------------------------------
303    // Input and output:
304    //
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()
309    // returns 0.
310    //------------------------------------------------------------------
311
312
313    Int64                       writeTo (OStream &os,
314                                         bool isTiled = false) const;
315
316    void                        readFrom (IStream &is, int &version);
317
318  private:
319
320    AttributeMap                _map;
321};
322
323
324//----------
325// Iterators
326//----------
327
328class Header::Iterator
329{
330  public:
331
332    Iterator ();
333    Iterator (const Header::AttributeMap::iterator &i);
334
335    Iterator &                  operator ++ ();
336    Iterator                    operator ++ (int);
337
338    const char *                name () const;
339    Attribute &                 attribute () const;
340
341  private:
342
343    friend class Header::ConstIterator;
344
345    Header::AttributeMap::iterator _i;
346};
347
348
349class Header::ConstIterator
350{
351  public:
352
353    ConstIterator ();
354    ConstIterator (const Header::AttributeMap::const_iterator &i);
355    ConstIterator (const Header::Iterator &other);
356
357    ConstIterator &             operator ++ ();
358    ConstIterator               operator ++ (int);
359
360    const char *                name () const;
361    const Attribute &           attribute () const;
362
363  private:
364
365    friend bool operator == (const ConstIterator &, const ConstIterator &);
366    friend bool operator != (const ConstIterator &, const ConstIterator &);
367
368    Header::AttributeMap::const_iterator _i;
369};
370
371
372//------------------------------------------------------------------------
373// Library initialization:
374//
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
379// variables.
380//
381// Single-threaded programs are not required to call staticInitialize();
382// initialization of the library's global variables happens automatically.
383//
384//------------------------------------------------------------------------
385
386void staticInitialize ();
387
388
389//-----------------
390// Inline Functions
391//-----------------
392
393
394inline
395Header::Iterator::Iterator (): _i()
396{
397    // empty
398}
399
400
401inline
402Header::Iterator::Iterator (const Header::AttributeMap::iterator &i): _i (i)
403{
404    // empty
405}
406
407
408inline Header::Iterator &               
409Header::Iterator::operator ++ ()
410{
411    ++_i;
412    return *this;
413}
414
415
416inline Header::Iterator         
417Header::Iterator::operator ++ (int)
418{
419    Iterator tmp = *this;
420    ++_i;
421    return tmp;
422}
423
424
425inline const char *
426Header::Iterator::name () const
427{
428    return *_i->first;
429}
430
431
432inline Attribute &     
433Header::Iterator::attribute () const
434{
435    return *_i->second;
436}
437
438
439inline
440Header::ConstIterator::ConstIterator (): _i()
441{
442    // empty
443}
444
445inline
446Header::ConstIterator::ConstIterator
447    (const Header::AttributeMap::const_iterator &i): _i (i)
448{
449    // empty
450}
451
452
453inline
454Header::ConstIterator::ConstIterator (const Header::Iterator &other):
455    _i (other._i)
456{
457    // empty
458}
459
460inline Header::ConstIterator &
461Header::ConstIterator::operator ++ ()
462{
463    ++_i;
464    return *this;
465}
466
467
468inline Header::ConstIterator           
469Header::ConstIterator::operator ++ (int)
470{
471    ConstIterator tmp = *this;
472    ++_i;
473    return tmp;
474}
475
476
477inline const char *
478Header::ConstIterator::name () const
479{
480    return *_i->first;
481}
482
483
484inline const Attribute &       
485Header::ConstIterator::attribute () const
486{
487    return *_i->second;
488}
489
490
491inline bool
492operator == (const Header::ConstIterator &x, const Header::ConstIterator &y)
493{
494    return x._i == y._i;
495}
496
497
498inline bool
499operator != (const Header::ConstIterator &x, const Header::ConstIterator &y)
500{
501    return !(x == y);
502}
503
504
505//---------------------
506// Template definitions
507//---------------------
508
509template <class T>
510T &
511Header::typedAttribute (const char name[])
512{
513    Attribute *attr = &(*this)[name];
514    T *tattr = dynamic_cast <T*> (attr);
515
516    if (tattr == 0)
517        throw Iex::TypeExc ("Unexpected attribute type.");
518
519    return *tattr;
520}
521
522
523template <class T>
524const T &
525Header::typedAttribute (const char name[]) const
526{
527    const Attribute *attr = &(*this)[name];
528    const T *tattr = dynamic_cast <const T*> (attr);
529
530    if (tattr == 0)
531        throw Iex::TypeExc ("Unexpected attribute type.");
532
533    return *tattr;
534}
535
536
537template <class T>
538T *
539Header::findTypedAttribute (const char name[])
540{
541    AttributeMap::iterator i = _map.find (name);
542    return (i == _map.end())? 0: dynamic_cast <T*> (i->second);
543}
544
545
546template <class T>
547const T *
548Header::findTypedAttribute (const char name[]) const
549{
550    AttributeMap::const_iterator i = _map.find (name);
551    return (i == _map.end())? 0: dynamic_cast <const T*> (i->second);
552}
553
554
555} // namespace Imf
556
557#endif
Note: See TracBrowser for help on using the repository browser.