IMG_Plane.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        IMG_Plane.h ( IMG Library, C++)
 *
 * COMMENTS:
 *      Description class of a single plane in a deep raster file.
 *      IMG_Stat contains a list of IMG_Plane structures.
 */
#ifndef __IMG_PLANE_INFO_H__
#define __IMG_PLANE_INFO_H__

#include "IMG_API.h"

#include <SYS/SYS_Types.h>
#include <UT/UT_String.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_Rect.h>
#include <UT/UT_Rect.h>
#include <PXL/PXL_Common.h>

#include "IMG_FileTypes.h"
#include "IMG_Metadata.h"

class IMG_Stat;
class UT_JSONWriter;

/// @brief standard plane names.
struct IMG_API IMG_PlaneName
{
    static const char *Color;           // "C"
    static const char *Alpha;           // "A"
    static const char *Opacity;         // "Of"
    static const char *Depth;           // "Pz"
    static const char *Position;        // "P"
    static const char *Normal;          // "N"

    /// For deep images, this plane contains the sample count for each pixel.
    static const char *DepthComplexity; // "Depth-Complexity"
};

/// @brief Describes the format and layout of a single plane in an image
/// The plane specifies the format and name of a single image plane in a deep
/// raster image. IMG_Stat contains a list of planes found in the image.
/// Non-deep raster formats only contain one plane.
class IMG_API IMG_Plane
{
public:
    /// @{
    /// Planes are generally not created by the user, but by
    /// IMG_Stat::addPlane()
    IMG_Plane();
    IMG_Plane(const IMG_Plane &p);
    IMG_Plane(const UT_StringHolder &name, IMG_DataType dt, IMG_ColorModel cm,
                  int index);
    /// @}

    IMG_Plane &operator=(const IMG_Plane &p) = delete;

    /// Returns the amount of memory owned by this IMG_Plane object
    int64 getMemoryUsage(bool inclusive) const;

    /// @{
    /// plane name - must be unique in the list of planes found in IMG_Stat
    void                         setName(const UT_StringHolder &name);
    const UT_StringHolder       &getName() const;
    /// @}

    /// @{
    /// data format of the individual pixel components (8bit - FP)
    void         setDataType(IMG_DataType dt);
    IMG_DataType getDataType() const;
    /// @}

    /// @{
    /// color model of the pixel, which specifies the components per pixel.
    /// (SINGLE_CHAN, RGB, RGBA)
    void           setColorModel(IMG_ColorModel cm);
    IMG_ColorModel getColorModel() const;
    /// @}

    /// @{
    /// type info of the data contained in the plane. This is purely an
    /// advisory indicator on how the data should be handled.
    /// Note that this can affect the colorspace of the plane if not COLOR.
    void           setTypeInfo(IMG_TypeInfo ti);
    IMG_TypeInfo   getTypeInfo() const;
    /// @}

    /// @{
    /// colorspace of the image data in the plane. This helps determine how to
    /// display the image data. If PXL_CS_UNKNOWN is returned, the format's
    /// colorspace will be used instead. 'gamma' is only needed for
    /// PXL_CS_CUSTOM_GAMMA.
    void                setColorSpace(PXL_ColorSpace cs, fpreal gamma = 0.0);
    PXL_ColorSpace      getColorSpace() const;
    fpreal              getColorSpaceGamma() const;
    /// @}

    /// This sets the PXL_ColorSpace to PXL_CS_OCIO and stores the OCIO color
    /// space.
    void                setOCIOColorSpace(const UT_StringHolder &space);
    /// Look up the OCIO color space when getColorSpace() == PXL_CS_OCIO
    const UT_StringHolder       &getOCIOColorSpace() const;

    /// Guess the OCIO color space based on plane semantics
    /// When this is the first plane (index==0), the @c file_space will be used
    /// if there's no existing color space.  If the @c file_space isn't defined
    /// (or if it's not the first plane), the color space will be determined
    /// using various heuristics (like channel names and data storage).
    UT_StringHolder     guessOCIOColorSpace(
                                const UT_StringHolder &file_space) const;

    /// @{
    /// Sets the individual component name(s) (default: r,g,b,a). Always call
    /// after setColorModel().
    void        setComponentNames(const char *c1,
                                  const char *c2=0,
                                  const char *c3=0,
                                  const char *c4=0);
    void        setComponentName(int comp, const char *name);

    /// Returns the name of the individual component of a pixel (r,g,b,a, x,y,z)
    const char *getComponentName(int comp) const;
    /// @}

    /// @{
    /// Specifies black/white points for integer formats (not supported for FP)
    /// always set the data type before setting the BW points.
    /// The black and white points must be within the range of the intger data
    /// format (ie, 8b - 0-255).
    void           setBlackWhitePoints(int64 b, int64 w);
    bool           hasBlackWhitePoints() const;
    void           getBlackWhitePoints(int64 &b, int64 &w) const;
    /// @}

    /// the size of a single pixel, in bytes, including the data format and
    /// the color model.
    int            getPixelSize() const;

    /// This is the index of this plane, in the list of planes found in
    /// IMG_Stat (0 to getNumPlanes()-1).
    int            getPlaneIndex() const { return myIndex; }

    /// Returns the number of components this plane consists of.
    int            getComponentCount() const
                   { return IMGvectorSize(myColorModel); }

    IMG_Metadata        &metadata() { return myMetadata; }
    const IMG_Metadata  &metadata() const { return myMetadata; }
    bool        findMetadata(const UT_StringRef &key,
                                IMG_MetadataItem &value) const
                    { return metadata().find(key, value, metadataKey()); }
    /// @}

    /// The format's default metadata key
    const UT_StringHolder       &metadataKey() const;

    /// @{
    /// Metadata iterator
    IMG_Metadata::const_iterator        beginMetadata() const
                                            { return metadata().begin(); }
    IMG_Metadata::const_iterator        endMetadata() const
                                            { return metadata().end(); }
    /// @}

    /// @{
    /// Import metadata.  This will fall back to the value on the IMG_Stat.
    bool        importMetadata(const UT_StringRef &key, bool &val) const;
    bool        importMetadata(const UT_StringRef &key, int32 &val) const;
    bool        importMetadata(const UT_StringRef &key, int64 &val) const;
    bool        importMetadata(const UT_StringRef &key, fpreal32 &val) const;
    bool        importMetadata(const UT_StringRef &key, fpreal64 &val) const;
    bool        importMetadata(const UT_StringRef &key, UT_Matrix4F &val) const;
    bool        importMetadata(const UT_StringRef &key, UT_Matrix4D &val) const;
    bool        importMetadata(const UT_StringRef &key, UT_StringHolder &val) const;
    /// @}

    /// Convert metadata to a string value.  When @c pretty_print is @c true:
    /// - If there's a menu, the corresponding label will be returned
    /// - If there's type information, it will be used (i.e. printing a time or
    ///   memory)
    bool        metadataAsString(const UT_StringRef &key,
                                UT_StringHolder &value,
                                bool pretty_print) const;

    /// @{
    /// Set metadata
    bool setMetadata(const UT_StringHolder &key, const IMG_MetadataItem &item)
            { return metadata().add(key, item); }
    bool setMetadata(const UT_StringHolder &key, const UT_JSONValue &val)
            { return metadata().add(key, IMG_MetadataItem(val)); }
    bool setMetadata(const UT_StringHolder &key, bool val)
            { return metadata().add(key, IMG_MetadataItem(UT_JSONValue(val))); }
    bool setMetadata(const UT_StringHolder &key, int64 val)
            { return metadata().add(key, IMG_MetadataItem(UT_JSONValue(val))); }
    bool setMetadata(const UT_StringHolder &key, fpreal64 val)
            { return metadata().add(key, IMG_MetadataItem(UT_JSONValue(val))); }
    bool setMetadata(const UT_StringHolder &key, const UT_StringHolder &val)
            { return metadata().add(key, IMG_MetadataItem(UT_JSONValue(val))); }
    /// @}

    void        dump() const;
    void        dump(UT_JSONWriter &w) const;

private:
    // only used by IMG_Stat.
    void        setParentStat(IMG_Stat *stat) { myStat = stat; }
    void        setPlaneIndex(int index) { myIndex = index; }
    void        updateComponentNames();

    // data members
    UT_StringHolder      myName;
    UT_String            myComponentNames[4];
    int                  myIndex;

    IMG_DataType         myDataType;
    IMG_ColorModel       myColorModel;
    PXL_ColorSpace       myColorSpace;
    UT_StringHolder      myOCIOColorSpace;
    fpreal               myColorSpaceGamma;
    IMG_TypeInfo         myTypeInfo;
    int64                myBlackPoint;
    int64                myWhitePoint;
    IMG_Metadata         myMetadata; // Main image metadata
    IMG_Stat            *myStat;

    friend class IMG_Stat;
};

#endif