//

// SPDX-License-Identifier: BSD-3-Clause

// Copyright (c) Contributors to the OpenEXR Project.

//

#ifndef INCLUDED_IMF_HEADER_H

#define INCLUDED_IMF_HEADER_H

//-----------------------------------------------------------------------------

//

//  class Header

//

//-----------------------------------------------------------------------------

#include "ImfForward.h"

#include "IexBaseExc.h"

#include "ImfCompression.h"

#include "ImfLineOrder.h"

#include "ImfName.h"

#include "ImfTileDescription.h"

#include "ImfAttribute.h"

#include <Imath/ImathBox.h>

#include <Imath/ImathVec.h>

#include <cstdint>

#include <iosfwd>

#include <map>

#include <string>

OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER

using std::string;

class IMF_EXPORT_TYPE Header

{

public:

    //----------------------------------------------------------------

    // Default constructor -- the display window and the data window

    // are both set to Box2i (V2i (0, 0), V2i (width-1, height-1).

    //----------------------------------------------------------------

    IMF_EXPORT

    Header (

        int                         width            = 64,

        int                         height           = 64,

        float                       pixelAspectRatio = 1,

        const IMATH_NAMESPACE::V2f& screenWindowCenter =

            IMATH_NAMESPACE::V2f (0, 0),

        float     screenWindowWidth = 1,

        LineOrder lineOrder         = INCREASING_Y,

        Compression                 = ZIP_COMPRESSION);

    //--------------------------------------------------------------------

    // Constructor -- the data window is specified explicitly; the display

    // window is set to Box2i (V2i (0, 0), V2i (width-1, height-1).

    //--------------------------------------------------------------------

    IMF_EXPORT

    Header (

        int                           width,

        int                           height,

        const IMATH_NAMESPACE::Box2i& dataWindow,

        float                         pixelAspectRatio = 1,

        const IMATH_NAMESPACE::V2f&   screenWindowCenter =

            IMATH_NAMESPACE::V2f (0, 0),

        float     screenWindowWidth = 1,

        LineOrder lineOrder         = INCREASING_Y,

        Compression                 = ZIP_COMPRESSION);

    //----------------------------------------------------------

    // Constructor -- the display window and the data window are

    // both specified explicitly.

    //----------------------------------------------------------

    IMF_EXPORT

    Header (

        const IMATH_NAMESPACE::Box2i& displayWindow,

        const IMATH_NAMESPACE::Box2i& dataWindow,

        float                         pixelAspectRatio = 1,

        const IMATH_NAMESPACE::V2f&   screenWindowCenter =

            IMATH_NAMESPACE::V2f (0, 0),

        float     screenWindowWidth = 1,

        LineOrder lineOrder         = INCREASING_Y,

        Compression                 = ZIP_COMPRESSION);

    //-----------------

    // Copy constructor

    //-----------------

    IMF_EXPORT

    Header (const Header& other);

    IMF_EXPORT

    Header (Header&& other);

    //-----------

    // Destructor

    //-----------

    IMF_EXPORT

    ~Header ();

    //-----------

    // Assignment

    //-----------

    IMF_EXPORT

    Header& operator= (const Header& other);

    IMF_EXPORT

    Header& operator= (Header&& other);

    //---------------------------------------------------------------

    // Add an attribute:

    //

    // insert(n,attr) If no attribute with name n exists, a new

    //      attribute with name n, and the same type as

    //      attr, is added, and the value of attr is

    //      copied into the new attribute.

    //

    //      If an attribute with name n exists, and its

    //      type is the same as attr, the value of attr

    //      is copied into this attribute.

    //

    //      If an attribute with name n exists, and its

    //      type is different from attr, an IEX_NAMESPACE::TypeExc

    //      is thrown.

    //

    //---------------------------------------------------------------

    IMF_EXPORT

    void insert (const char name[], const Attribute& attribute);

    IMF_EXPORT

    void insert (const std::string& name, const Attribute& attribute);

    //---------------------------------------------------------------

    // Remove an attribute:

    //

    // remove(n)       If an attribute with name n exists, then it

    //                 is removed from the map of present attributes.

    //

    //                 If no attribute with name n exists, then this

    //                 functions becomes a 'no-op'

    //

    //---------------------------------------------------------------

    IMF_EXPORT

    void erase (const char name[]);

    IMF_EXPORT

    void erase (const std::string& name);

    //------------------------------------------------------------------

    // Access to existing attributes:

    //

    // [n]      Returns a reference to the attribute

    //        with name n.  If no attribute with

    //        name n exists, an IEX_NAMESPACE::ArgExc is thrown.

    //

    // typedAttribute<T>(n) Returns a reference to the attribute

    //        with name n and type T.  If no attribute

    //        with name n exists, an IEX_NAMESPACE::ArgExc is

    //        thrown.  If an attribute with name n

    //        exists, but its type is not T, an

    //        IEX_NAMESPACE::TypeExc is thrown.

    //

    // findTypedAttribute<T>(n) Returns a pointer to the attribute with

    //        name n and type T, or 0 if no attribute

    //        with name n and type T exists.

    //

    //------------------------------------------------------------------

    IMF_EXPORT

    Attribute& operator[] (const char name[]);

    IMF_EXPORT

    const Attribute& operator[] (const char name[]) const;

    IMF_EXPORT

    Attribute& operator[] (const std::string& name);

    IMF_EXPORT

    const Attribute& operator[] (const std::string& name) const;

    template <class T> T&       typedAttribute (const char name[]);

    template <class T> const T& typedAttribute (const char name[]) const;

    template <class T> T&       typedAttribute (const std::string& name);

    template <class T> const T& typedAttribute (const std::string& name) const;

    template <class T> T*       findTypedAttribute (const char name[]);

    template <class T> const T* findTypedAttribute (const char name[]) const;

    template <class T> T* findTypedAttribute (const std::string& name);

    template <class T>

    const T* findTypedAttribute (const std::string& name) const;

    //---------------------------------------------

    // Iterator-style access to existing attributes

    //---------------------------------------------

    typedef std::map<Name, Attribute*> AttributeMap;

    class Iterator;

    class ConstIterator;

    IMF_EXPORT

    Iterator begin ();

    IMF_EXPORT

    ConstIterator begin () const;

    IMF_EXPORT

    Iterator end ();

    IMF_EXPORT

    ConstIterator end () const;

    IMF_EXPORT

    Iterator find (const char name[]);

    IMF_EXPORT

    ConstIterator find (const char name[]) const;

    IMF_EXPORT

    Iterator find (const std::string& name);

    IMF_EXPORT

    ConstIterator find (const std::string& name) const;

    //--------------------------------

    // Access to predefined attributes

    //--------------------------------

    IMF_EXPORT

    IMATH_NAMESPACE::Box2i& displayWindow ();

    IMF_EXPORT

    const IMATH_NAMESPACE::Box2i& displayWindow () const;

    IMF_EXPORT

    IMATH_NAMESPACE::Box2i& dataWindow ();

    IMF_EXPORT

    const IMATH_NAMESPACE::Box2i& dataWindow () const;

    IMF_EXPORT

    float& pixelAspectRatio ();

    IMF_EXPORT

    const float& pixelAspectRatio () const;

    IMF_EXPORT

    IMATH_NAMESPACE::V2f& screenWindowCenter ();

    IMF_EXPORT

    const IMATH_NAMESPACE::V2f& screenWindowCenter () const;

    IMF_EXPORT

    float& screenWindowWidth ();

    IMF_EXPORT

    const float& screenWindowWidth () const;

    IMF_EXPORT

    ChannelList& channels ();

    IMF_EXPORT

    const ChannelList& channels () const;

    IMF_EXPORT

    LineOrder& lineOrder ();

    IMF_EXPORT

    const LineOrder& lineOrder () const;

    IMF_EXPORT

    Compression& compression ();

    IMF_EXPORT

    const Compression& compression () const;

    //-----------------------------------------------------

    // The header object allows one to store a compression level to be

    // used when writing a file.

    //

    // NB: These are NOT attributes, and will not be written to the

    // file, but are instead ephemeral settings to be used for this

    // instance of the header object.

    //

    // -----------------------------------------------------

    IMF_EXPORT

    void resetDefaultCompressionLevels ();

    IMF_EXPORT

    int& zipCompressionLevel ();

    IMF_EXPORT

    int zipCompressionLevel () const;

    IMF_EXPORT

    float& dwaCompressionLevel ();

    IMF_EXPORT

    float dwaCompressionLevel () const;

    IMF_EXPORT

    float& lossyHTJ2KQuality ();

    IMF_EXPORT

    float lossyHTJ2KQuality () const;

    // Valid levels are 1 through 22 (libzstd range). Values outside

    // that range are clamped. The library default is 5.

    IMF_EXPORT

    int& zstdCompressionLevel ();

    IMF_EXPORT

    int zstdCompressionLevel () const;

    IMF_EXPORT

    //-----------------------------------------------------

    // Access to required attributes for multipart files

    // They are optional to non-multipart files and mandatory

    // for multipart files.

    //-----------------------------------------------------

    IMF_EXPORT

    void setName (const string& name);

    IMF_EXPORT

    string& name ();

    IMF_EXPORT

    const string& name () const;

    IMF_EXPORT

    bool hasName () const;

    IMF_EXPORT

    void setType (const string& Type);

    IMF_EXPORT

    string& type ();

    IMF_EXPORT

    const string& type () const;

    IMF_EXPORT

    bool hasType () const;

    IMF_EXPORT

    void setVersion (const int version);

    IMF_EXPORT

    int& version ();

    IMF_EXPORT

    const int& version () const;

    IMF_EXPORT

    bool hasVersion () const;

    //

    // the chunkCount attribute is set automatically when a file is written.

    // There is no need to set it manually

    //

    IMF_EXPORT

    void setChunkCount (int chunks);

    IMF_EXPORT

    bool hasChunkCount () const;

    IMF_EXPORT

    const int& chunkCount () const;

    IMF_EXPORT

    int& chunkCount ();

    //

    // for multipart files, return whether the file has a view string attribute

    // (for the deprecated single part multiview format EXR, see ImfMultiView.h)

    //

    IMF_EXPORT

    void setView (const string& view);

    IMF_EXPORT

    bool hasView () const;

    IMF_EXPORT

    string& view ();

    IMF_EXPORT

    const string& view () const;

    //----------------------------------------------------------------------

    // Tile Description:

    //

    // The tile description is a TileDescriptionAttribute whose name

    // is "tiles".  The "tiles" attribute must be present in any tiled

    // image file. When present, it describes various properties of the

    // tiles that make up the file.

    //

    // Convenience functions:

    //

    // setTileDescription(td)

    //     calls insert ("tiles", TileDescriptionAttribute (td))

    //

    // tileDescription()

    //     returns typedAttribute<TileDescriptionAttribute>("tiles").value()

    //

    // hasTileDescription()

    //     return findTypedAttribute<TileDescriptionAttribute>("tiles") != 0

    //

    //----------------------------------------------------------------------

    IMF_EXPORT

    void setTileDescription (const TileDescription& td);

    IMF_EXPORT

    TileDescription& tileDescription ();

    IMF_EXPORT

    const TileDescription& tileDescription () const;

    IMF_EXPORT

    bool hasTileDescription () const;

    //----------------------------------------------------------------------

    // Preview image:

    //

    // The preview image is a PreviewImageAttribute whose name is "preview".

    // This attribute is special -- while an image file is being written,

    // the pixels of the preview image can be changed repeatedly by calling

    // OutputFile::updatePreviewImage().

    //

    // Convenience functions:

    //

    // setPreviewImage(p)

    //     calls insert ("preview", PreviewImageAttribute (p))

    //

    // previewImage()

    //     returns typedAttribute<PreviewImageAttribute>("preview").value()

    //

    // hasPreviewImage()

    //     return findTypedAttribute<PreviewImageAttribute>("preview") != 0

    //

    //----------------------------------------------------------------------

    IMF_EXPORT

    void setPreviewImage (const PreviewImage& p);

    IMF_EXPORT

    PreviewImage& previewImage ();

    IMF_EXPORT

    const PreviewImage& previewImage () const;

    IMF_EXPORT

    bool hasPreviewImage () const;

    //-------------------------------------------------------------

    // Sanity check -- examines the header, and throws an exception

    // if it finds something wrong (empty display window, negative

    // pixel aspect ratio, unknown compression scheme etc...)

    //

    // set isTiled to true if you are checking a tiled/multi-res

    // header

    //-------------------------------------------------------------

    IMF_EXPORT

    void sanityCheck (bool isTiled = false, bool isMultipartFile = false) const;

    //----------------------------------------------------------------

    // Maximum image size and maximum tile size:

    //

    // sanityCheck() will throw an exception if the width or height of

    // the data window exceeds the maximum image width or height, or

    // if the size of a tile exceeds the maximum tile width or height.

    //

    // At program startup the maximum image and tile width and height

    // are set to zero, meaning that width and height are unlimited.

    //

    // Limiting image and tile width and height limits how much memory

    // will be allocated when a file is opened.  This can help protect

    // applications from running out of memory while trying to read

    // a damaged image file.

    //----------------------------------------------------------------

    IMF_EXPORT

    static void setMaxImageSize (int maxWidth, int maxHeight);

    IMF_EXPORT

    static void setMaxTileSize (int maxWidth, int maxHeight);

    IMF_EXPORT

    static void getMaxImageSize (int& maxWidth, int& maxHeight);

    IMF_EXPORT

    static void getMaxTileSize (int& maxWidth, int& maxHeight);

    //

    // Check if the header reads nothing.

    //

    IMF_EXPORT

    bool readsNothing ();

    //------------------------------------------------------------------

    // Input and output:

    //

    // If the header contains a preview image attribute, then writeTo()

    // returns the position of that attribute in the output stream; this

    // information is used by OutputFile::updatePreviewImage().

    // If the header contains no preview image attribute, then writeTo()

    // returns 0.

    //------------------------------------------------------------------

    IMF_EXPORT

    uint64_t writeTo (

        OPENEXR_IMF_INTERNAL_NAMESPACE::OStream& os,

        bool                                     isTiled = false) const;

    IMF_EXPORT

    void readFrom (OPENEXR_IMF_INTERNAL_NAMESPACE::IStream& is, int& version);

private:

    AttributeMap _map;

    bool _readsNothing;

};

//----------

// Iterators

//----------

class IMF_EXPORT_TYPE Header::Iterator

{

public:

    Iterator ();

    Iterator (const Header::AttributeMap::iterator& i);

    Iterator& operator++ ();

    Iterator operator++ (int);

    const char* name () const;

    Attribute&  attribute () const;

private:

    friend class Header::ConstIterator;

    Header::AttributeMap::iterator _i;

};

class IMF_EXPORT_TYPE Header::ConstIterator

{

public:

    ConstIterator ();

    ConstIterator (const Header::AttributeMap::const_iterator& i);

    ConstIterator (const Header::Iterator& other);

    ConstIterator& operator++ ();

    ConstIterator  operator++ (int);

    const char*     name () const;

    const Attribute& attribute () const;

private:

    friend bool operator== (const ConstIterator&, const ConstIterator&);

    friend bool operator!= (const ConstIterator&, const ConstIterator&);

    Header::AttributeMap::const_iterator _i;

};

//------------------------------------------------------------------------

// Library initialization:

//

// In a multithreaded program, staticInitialize() must be called once

// during startup, before the program accesses any other functions or

// classes in the OpenEXR library.  Calling staticInitialize() in this

// way avoids races during initialization of the library's global

// variables.

//

// Single-threaded programs are not required to call staticInitialize();

// initialization of the library's global variables happens automatically.

//

//------------------------------------------------------------------------

IMF_EXPORT void staticInitialize ();

//-----------------

// Inline Functions

//-----------------

inline Header::Iterator::Iterator () : _i ()

{

    // empty

}

inline Header::Iterator::Iterator (const Header::AttributeMap::iterator& i)

    : _i (i)

{

    // empty

}

inline Header::Iterator&

Header::Iterator::operator++ ()

{

    ++_i;

    return *this;

}

inline Header::Iterator

Header::Iterator::operator++ (int)

{

    Iterator tmp = *this;

    ++_i;

    return tmp;

}

inline const char*

Header::Iterator::name () const

{

    return *_i->first;

}

inline Attribute&

Header::Iterator::attribute () const

{

    return *_i->second;

}

inline Header::ConstIterator::ConstIterator () : _i ()

{

    // empty

}

inline Header::ConstIterator::ConstIterator (

    const Header::AttributeMap::const_iterator& i)

    : _i (i)

{

    // empty

}

inline Header::ConstIterator::ConstIterator (const Header::Iterator& other)

    : _i (other._i)

{

    // empty

}

inline Header::ConstIterator&

Header::ConstIterator::operator++ ()

{

    ++_i;

    return *this;

}

inline Header::ConstIterator

Header::ConstIterator::operator++ (int)

{

    ConstIterator tmp = *this;

    ++_i;

    return tmp;

}

inline const char*

Header::ConstIterator::name () const

{

    return *_i->first;

}

inline const Attribute&

Header::ConstIterator::attribute () const

{

    return *_i->second;

}

inline bool

operator== (const Header::ConstIterator& x, const Header::ConstIterator& y)

{

    return x._i == y._i;

}

inline bool

operator!= (const Header::ConstIterator& x, const Header::ConstIterator& y)

{

    return !(x == y);

}

//---------------------

// Template definitions

//---------------------

template <class T>

T&

Header::typedAttribute (const char name[])

{

    Attribute* attr  = &(*this)[name];

    T*         tattr = dynamic_cast<T*> (attr);

    if (tattr == 0) throw IEX_NAMESPACE::TypeExc ("Unexpected attribute type.");

    return *tattr;

}

template <class T>

const T&

Header::typedAttribute (const char name[]) const

{

    const Attribute* attr  = &(*this)[name];

    const T*         tattr = dynamic_cast<const T*> (attr);

    if (tattr == 0) throw IEX_NAMESPACE::TypeExc ("Unexpected attribute type.");

    return *tattr;

}

template <class T>

T&

Header::typedAttribute (const std::string& name)

{

    return typedAttribute<T> (name.c_str ());

}

template <class T>

const T&

Header::typedAttribute (const std::string& name) const

{

    return typedAttribute<T> (name.c_str ());

}

template <class T>

T*

Header::findTypedAttribute (const char name[])

{

    AttributeMap::iterator i = _map.find (name);

    return (i == _map.end ()) ? 0 : dynamic_cast<T*> (i->second);

}

template <class T>

const T*

Header::findTypedAttribute (const char name[]) const

{

    AttributeMap::const_iterator i = _map.find (name);

    return (i == _map.end ()) ? 0 : dynamic_cast<const T*> (i->second);

}

Imf_3_5::TypedAttribute<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > > const* Imf_3_5::Header::findTypedAttribute<Imf_3_5::TypedAttribute<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > > >(char const*) const

Line

Count

Source

706

45.2k

{

707

45.2k

    AttributeMap::const_iterator i = _map.find (name);

708

45.2k

    return (i == _map.end ()) ? 0 : dynamic_cast<const T*> (i->second);

709

45.2k

}

Imf_3_5::TypedAttribute<float> const* Imf_3_5::Header::findTypedAttribute<Imf_3_5::TypedAttribute<float> >(char const*) const

Line

Count

Source

706

14.1k

{

707

14.1k

    AttributeMap::const_iterator i = _map.find (name);

708

14.1k

    return (i == _map.end ()) ? 0 : dynamic_cast<const T*> (i->second);

709

14.1k

}

Imf_3_5::OpaqueAttribute const* Imf_3_5::Header::findTypedAttribute<Imf_3_5::OpaqueAttribute>(char const*) const

Line

Count

Source

706

3.47k

{

707

3.47k

    AttributeMap::const_iterator i = _map.find (name);

708

3.47k

    return (i == _map.end ()) ? 0 : dynamic_cast<const T*> (i->second);

709

3.47k

}

Imf_3_5::TypedAttribute<Imf_3_5::Chromaticities> const* Imf_3_5::Header::findTypedAttribute<Imf_3_5::TypedAttribute<Imf_3_5::Chromaticities> >(char const*) const

Line

Count

Source

706

2.75k

{

707

2.75k

    AttributeMap::const_iterator i = _map.find (name);

708

2.75k

    return (i == _map.end ()) ? 0 : dynamic_cast<const T*> (i->second);

709

2.75k

}

Imf_3_5::TypedAttribute<std::__1::vector<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::allocator<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > > > > const* Imf_3_5::Header::findTypedAttribute<Imf_3_5::TypedAttribute<std::__1::vector<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >, std::__1::allocator<std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > > > > >(char const*) const

Line

Count

Source

706

6.45k

{

707

6.45k

    AttributeMap::const_iterator i = _map.find (name);

708

6.45k

    return (i == _map.end ()) ? 0 : dynamic_cast<const T*> (i->second);

709

6.45k

}

template <class T>

T*

Header::findTypedAttribute (const std::string& name)

{

    return findTypedAttribute<T> (name.c_str ());

}

template <class T>

const T*

Header::findTypedAttribute (const std::string& name) const

{

    return findTypedAttribute<T> (name.c_str ());

}

OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT

#endif