HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
IMG_Plane.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: IMG_Plane.h ( IMG Library, C++)
7  *
8  * COMMENTS:
9  * Description class of a single plane in a deep raster file.
10  * IMG_Stat contains a list of IMG_Plane structures.
11  */
12 #ifndef __IMG_PLANE_INFO_H__
13 #define __IMG_PLANE_INFO_H__
14 
15 #include "IMG_API.h"
16 
17 #include <SYS/SYS_Types.h>
18 #include <UT/UT_String.h>
19 #include <UT/UT_StringHolder.h>
20 #include <UT/UT_Rect.h>
21 #include <UT/UT_Rect.h>
22 #include <PXL/PXL_Common.h>
23 
24 #include "IMG_FileTypes.h"
25 #include "IMG_Metadata.h"
26 
27 class IMG_Stat;
28 class UT_JSONWriter;
29 
30 /// @brief standard plane names.
32 {
33  static const char *Color; // "C"
34  static const char *Alpha; // "A"
35  static const char *Opacity; // "Of"
36  static const char *Depth; // "Pz"
37  static const char *Position; // "P"
38  static const char *Normal; // "N"
39 
40  /// For deep images, this plane contains the sample count for each pixel.
41  static const char *DepthComplexity; // "Depth-Complexity"
42 };
43 
44 /// @brief Describes the format and layout of a single plane in an image
45 /// The plane specifies the format and name of a single image plane in a deep
46 /// raster image. IMG_Stat contains a list of planes found in the image.
47 /// Non-deep raster formats only contain one plane.
49 {
50 public:
51  /// @{
52  /// Planes are generally not created by the user, but by
53  /// IMG_Stat::addPlane()
54  IMG_Plane();
55  IMG_Plane(const IMG_Plane &p);
57  int index);
58  /// @}
59 
60  IMG_Plane &operator=(const IMG_Plane &p) = delete;
61 
62  /// Returns the amount of memory owned by this IMG_Plane object
63  int64 getMemoryUsage(bool inclusive) const;
64 
65  /// @{
66  /// plane name - must be unique in the list of planes found in IMG_Stat
67  void setName(const UT_StringHolder &name);
68  const UT_StringHolder &getName() const;
69  /// @}
70 
71  /// @{
72  /// data format of the individual pixel components (8bit - FP)
73  void setDataType(IMG_DataType dt);
74  IMG_DataType getDataType() const;
75  /// @}
76 
77  /// @{
78  /// color model of the pixel, which specifies the components per pixel.
79  /// (SINGLE_CHAN, RGB, RGBA)
80  void setColorModel(IMG_ColorModel cm);
81  IMG_ColorModel getColorModel() const;
82  /// @}
83 
84  /// @{
85  /// type info of the data contained in the plane. This is purely an
86  /// advisory indicator on how the data should be handled.
87  /// Note that this can affect the colorspace of the plane if not COLOR.
88  void setTypeInfo(IMG_TypeInfo ti);
89  IMG_TypeInfo getTypeInfo() const;
90  /// @}
91 
92  /// @{
93  /// colorspace of the image data in the plane. This helps determine how to
94  /// display the image data. If PXL_CS_UNKNOWN is returned, the format's
95  /// colorspace will be used instead. 'gamma' is only needed for
96  /// PXL_CS_CUSTOM_GAMMA.
97  void setColorSpace(PXL_ColorSpace cs, fpreal gamma = 0.0);
98  PXL_ColorSpace getColorSpace() const;
99  fpreal getColorSpaceGamma() const;
100  /// @}
101 
102  /// This sets the PXL_ColorSpace to PXL_CS_OCIO and stores the OCIO color
103  /// space.
104  void setOCIOColorSpace(const UT_StringHolder &space);
105  /// Look up the OCIO color space when getColorSpace() == PXL_CS_OCIO
106  const UT_StringHolder &getOCIOColorSpace() const;
107 
108  /// Guess the OCIO color space based on plane semantics
109  /// When this is the first plane (index==0), the @c file_space will be used
110  /// if there's no existing color space. If the @c file_space isn't defined
111  /// (or if it's not the first plane), the color space will be determined
112  /// using various heuristics (like channel names and data storage).
113  UT_StringHolder guessOCIOColorSpace(
114  const UT_StringHolder &file_space) const;
115 
116  /// @{
117  /// Sets the individual component name(s) (default: r,g,b,a). Always call
118  /// after setColorModel().
119  void setComponentNames(const char *c1,
120  const char *c2=0,
121  const char *c3=0,
122  const char *c4=0);
123  void setComponentName(int comp, const char *name);
124 
125  /// Returns the name of the individual component of a pixel (r,g,b,a, x,y,z)
126  const char *getComponentName(int comp) const;
127  /// @}
128 
129  /// @{
130  /// Specifies black/white points for integer formats (not supported for FP)
131  /// always set the data type before setting the BW points.
132  /// The black and white points must be within the range of the intger data
133  /// format (ie, 8b - 0-255).
134  void setBlackWhitePoints(int64 b, int64 w);
135  bool hasBlackWhitePoints() const;
136  void getBlackWhitePoints(int64 &b, int64 &w) const;
137  /// @}
138 
139  /// the size of a single pixel, in bytes, including the data format and
140  /// the color model.
141  int getPixelSize() const;
142 
143  /// This is the index of this plane, in the list of planes found in
144  /// IMG_Stat (0 to getNumPlanes()-1).
145  int getPlaneIndex() const { return myIndex; }
146 
147  /// Returns the number of components this plane consists of.
148  int getComponentCount() const
149  { return IMGvectorSize(myColorModel); }
150 
151  IMG_Metadata &metadata() { return myMetadata; }
152  const IMG_Metadata &metadata() const { return myMetadata; }
153  bool findMetadata(const UT_StringRef &key,
154  IMG_MetadataItem &value) const
155  { return metadata().find(key, value, metadataKey()); }
156  /// @}
157 
158  /// The format's default metadata key
159  const UT_StringHolder &metadataKey() const;
160 
161  /// @{
162  /// Metadata iterator
164  { return metadata().begin(); }
166  { return metadata().end(); }
167  /// @}
168 
169  /// @{
170  /// Import metadata. This will fall back to the value on the IMG_Stat.
171  bool importMetadata(const UT_StringRef &key, bool &val) const;
172  bool importMetadata(const UT_StringRef &key, int32 &val) const;
173  bool importMetadata(const UT_StringRef &key, int64 &val) const;
174  bool importMetadata(const UT_StringRef &key, fpreal32 &val) const;
175  bool importMetadata(const UT_StringRef &key, fpreal64 &val) const;
176  bool importMetadata(const UT_StringRef &key, UT_Matrix4F &val) const;
177  bool importMetadata(const UT_StringRef &key, UT_Matrix4D &val) const;
178  bool importMetadata(const UT_StringRef &key, UT_StringHolder &val) const;
179  /// @}
180 
181  /// Convert metadata to a string value. When @c pretty_print is @c true:
182  /// - If there's a menu, the corresponding label will be returned
183  /// - If there's type information, it will be used (i.e. printing a time or
184  /// memory)
185  bool metadataAsString(const UT_StringRef &key,
187  bool pretty_print) const;
188 
189  /// @{
190  /// Set metadata
191  bool setMetadata(const UT_StringHolder &key, const IMG_MetadataItem &item)
192  { return metadata().add(key, item); }
193  bool setMetadata(const UT_StringHolder &key, const UT_JSONValue &val)
194  { return metadata().add(key, IMG_MetadataItem(val)); }
195  bool setMetadata(const UT_StringHolder &key, bool val)
196  { return metadata().add(key, IMG_MetadataItem(UT_JSONValue(val))); }
198  { return metadata().add(key, IMG_MetadataItem(UT_JSONValue(val))); }
200  { return metadata().add(key, IMG_MetadataItem(UT_JSONValue(val))); }
202  { return metadata().add(key, IMG_MetadataItem(UT_JSONValue(val))); }
203  /// @}
204 
205  void dump() const;
206  void dump(UT_JSONWriter &w) const;
207 
208 private:
209  // only used by IMG_Stat.
210  void setParentStat(IMG_Stat *stat) { myStat = stat; }
211  void setPlaneIndex(int index) { myIndex = index; }
212  void updateComponentNames();
213 
214  // data members
215  UT_StringHolder myName;
216  UT_String myComponentNames[4];
217  int myIndex;
218 
219  IMG_DataType myDataType;
220  IMG_ColorModel myColorModel;
221  PXL_ColorSpace myColorSpace;
222  UT_StringHolder myOCIOColorSpace;
223  fpreal myColorSpaceGamma;
224  IMG_TypeInfo myTypeInfo;
225  int64 myBlackPoint;
226  int64 myWhitePoint;
227  IMG_Metadata myMetadata; // Main image metadata
228  IMG_Stat *myStat;
229 
230  friend class IMG_Stat;
231 };
232 
233 #endif
const IMG_Metadata & metadata() const
Definition: IMG_Plane.h:152
int int32
Definition: SYS_Types.h:39
bool setMetadata(const UT_StringHolder &key, const UT_StringHolder &val)
Definition: IMG_Plane.h:201
IMG_Metadata::const_iterator endMetadata() const
Definition: IMG_Plane.h:165
IMG_Metadata & metadata()
Definition: IMG_Plane.h:151
IMG_TypeInfo
How the channel data should be interpreted.
Definition: IMG_FileTypes.h:39
bool setMetadata(const UT_StringHolder &key, bool val)
Definition: IMG_Plane.h:195
int getComponentCount() const
Returns the number of components this plane consists of.
Definition: IMG_Plane.h:148
bool setMetadata(const UT_StringHolder &key, const IMG_MetadataItem &item)
Definition: IMG_Plane.h:191
Class which writes ASCII or binary JSON streams.
Definition: UT_JSONWriter.h:37
static const char * Opacity
Definition: IMG_Plane.h:35
Describes the format and layout of a single plane in an image The plane specifies the format and name...
Definition: IMG_Plane.h:48
float fpreal32
Definition: SYS_Types.h:200
static const char * DepthComplexity
For deep images, this plane contains the sample count for each pixel.
Definition: IMG_Plane.h:41
double fpreal64
Definition: SYS_Types.h:201
static const char * Depth
Definition: IMG_Plane.h:36
#define IMG_API
Definition: IMG_API.h:10
UT_StringMap< IMG_MetadataItem >::const_iterator const_iterator
Definition: IMG_Metadata.h:325
static const char * Normal
Definition: IMG_Plane.h:38
bool setMetadata(const UT_StringHolder &key, const UT_JSONValue &val)
Definition: IMG_Plane.h:193
PXL_API const char * getName(const ColorSpace *space)
Return the name of the color space.
IMG_DataType
Definition: IMG_FileTypes.h:17
long long int64
Definition: SYS_Types.h:116
standard plane names.
Definition: IMG_Plane.h:31
GLuint const GLchar * name
Definition: glcorearb.h:786
GLboolean GLboolean GLboolean b
Definition: glcorearb.h:1222
bool setMetadata(const UT_StringHolder &key, int64 val)
Definition: IMG_Plane.h:197
fpreal64 fpreal
Definition: SYS_Types.h:277
GLuint index
Definition: glcorearb.h:786
PXL_ColorSpace
Definition: PXL_Common.h:72
IMG_ColorModel
Definition: IMG_FileTypes.h:53
GLuint GLfloat * val
Definition: glcorearb.h:1608
IMG_Metadata::const_iterator beginMetadata() const
Definition: IMG_Plane.h:163
static const char * Color
Definition: IMG_Plane.h:33
Class to store JSON objects as C++ objects.
Definition: UT_JSONValue.h:99
Contains the details of a specific image file, used by IMG_File. This class contains all the high-lev...
Definition: IMG_Stat.h:38
bool findMetadata(const UT_StringRef &key, IMG_MetadataItem &value) const
Definition: IMG_Plane.h:153
bool setMetadata(const UT_StringHolder &key, fpreal64 val)
Definition: IMG_Plane.h:199
Map of metadata items.
Definition: IMG_Metadata.h:208
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:857
Definition: core.h:1131
static const char * Alpha
Definition: IMG_Plane.h:34
int getPlaneIndex() const
Definition: IMG_Plane.h:145
static const char * Position
Definition: IMG_Plane.h:37