HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
IMG_Stat.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_Stat.h ( IMG Library, C++)
7  *
8  * COMMENTS: Information about a raster IO stream. This is what's passed
9  * around to read/write the raster. It's virtual so that each
10  * Format can define it's on private information to stash and keep
11  * around.
12  */
13 
14 #ifndef __IMG_Stat__
15 #define __IMG_Stat__
16 
17 #include "IMG_API.h"
18 
19 #include "IMG_FileTypes.h"
20 #include "IMG_Plane.h"
21 
22 #include <UT/UT_String.h>
23 #include <UT/UT_Rect.h>
24 #include <UT/UT_ValArray.h>
25 #include <UT/UT_IntArray.h>
26 #include <UT/UT_SharedPtr.h>
27 
28 
29 class IMG_Format;
30 class IMG_Plane;
31 class IMG_DeepStat;
32 
33 
34 /// @brief Contains the details of a specific image file, used by IMG_File.
35 /// This class contains all the high-level details needed to save an image file,
36 /// or query a loaded image file's statistics. It contains such data as the
37 /// resolution, pixel aspect ratios, data formats and image planes. The set()
38 /// methods are used when creating a new IMG_Stat for writing an image file,
39 /// while the get() methods are generally used when reading.
41 {
42 public:
44  IMG_Stat();
45  /// Sets up the resolution of the image. addPlane() or addDefaultPlane()
46  /// must be called to fill out the
47  IMG_Stat(unsigned xres, unsigned yres);
48 
49  /// sets up a single image plane format, without requiring addPlane().
50  /// Don't use this for deep raster images.
51  IMG_Stat(unsigned xres, unsigned yres,
53 
54  ~IMG_Stat();
55 
56  int64 getMemoryUsage(bool inclusive) const;
57 
58  IMG_Stat(const IMG_Stat &s)
59  {
60  copy(s);
61  }
63  {
64  copy(s);
65  return *this;
66  }
67  void copy(const IMG_Stat &src);
68 
69  /// @{
70  /// Read/write image a specific mode. If the format does not support
71  /// it, or the image being read is not of that type, IMG_File::open or
72  /// IMG_File::create calls will fail.
73  /// The default value is IMG_TYPE_2D.
74  void setImageType(IMG_ImageType it);
75 
76  IMG_ImageType getImageType() const { return myImageType; }
77  /// @}
78 
79  /// @{
80  /// Sets the resolution for the image, if not specified by the constructor.
81  void setResolution(unsigned xres, unsigned yres)
82  {
83  myXres = xres;
84  myYres = yres;
85  recomputeOffsets();
86  }
87 
88  /// Returns the resolution of the image to be written or the one that was
89  /// read.
90  /// @sa getDataWidth
91  /// @sa getDataHeight
92  unsigned getXres() const { return myXres; }
93  unsigned getYres() const { return myYres; }
94  /// @}
95 
96  /// @{
97  /// Pixel aspect ratio of the file (X/Y). Square pixels are 1.0 (default).
98  void setAspectRatio(fpreal aspect) { myAspectRatio=aspect; }
99  fpreal getAspectRatio() const { return myAspectRatio; }
100  /// @}
101 
102 
103  /// filename of the opened file. Files attached to streams may not have
104  /// a filename.
105  /// @{
106  void setFilename(const char *name){ myName.harden(name); }
107  const UT_String &getFilename() const { return myName; }
108  /// @}
109 
110  /// @{
111  /// @brief Returns the number of image planes in the image
112  /// a plane contains the actual structure of the image data. An image
113  /// needs at least one. Deep rasters can have multiple planes.
114  int getNumPlanes() const;
115  /// @brief Get an image plane by index
116  IMG_Plane *getPlane(int i = 0) const;
117 
118  /// @brief Get an image plane by name
119  /// Returns the plane with name 'name', or NULL if no matching plane is
120  /// found.
121  IMG_Plane *getPlaneName(const char *name) const;
122 
123  /// @brief Returns the index of the plane with 'name'
124  /// Returns the index of the plane with name 'name', or -1 if not found.
125  int getPlaneIndex(const char *name) const;
126  /// @}
127 
128  /// @{
129  /// @brief Add a plane to an image file.
130  /// Add a plane to the image file. This is only used when writing files.
131  /// Plane names must be unique. To write a file, at least one plane must be
132  /// present.
133  IMG_Plane *addPlane(const char *name,
134  IMG_DataType d,
135  IMG_ColorModel cm,
136  const char *c0name = 0,
137  const char *c1name = 0,
138  const char *c2name = 0,
139  const char *c3name = 0);
140  /// @private
141  IMG_Plane *addPlane(const IMG_Plane &pi);
142  /// @brief Add a default 8bit, RGBA plane to the image.
144  { return addPlane("C", IMG_UCHAR, IMG_RGBA, "r","g","b","a"); }
145  /// @}
146 
147  /// Adds 6 planes named Left, Right, Top, Bottom, Front and Back, all using
148  /// the same image format.
149  void addEnvMapPlanes(IMG_DataType dt, IMG_ColorModel cm);
150 
151  /// isEnvMap() will return true, only if the image is an environment map.
152  bool isEnvMap() const { return myEnvMapPlanes; }
153 
154  /// Sets the environment flag, if the image planes can be treated
155  /// as an environment map.
156  /// @return True if setting to the environment map was successful,
157  /// false otherwise.
158  bool setEnvMap();
159 
160  /// @private
161  void insertPlane(IMG_Plane *plane, int beforeindex);
162 
163  /// @{
164  /// Remove a plane by index from the stat. Used only for writing files.
165  void removePlane(int pindex);
166  /// Remove a plane by index from the stat. Used only for writing files.
167  void removePlane(const char *name);
168  /// Remove all planes from the stat. Used only for writing files.
169  void removeAllPlanes();
170  /// @}
171 
172  /// Alters the order of planes in the stat.
173  void reorderPlane(IMG_Plane *plane, int beforeindex);
174 
175  /// @{
176  /// Swap two planes
177  void swapPlaneOrder(int plane_a, int plane_b);
178  void swapPlaneOrder(const IMG_Plane *p, int plane_b)
179  { swapPlaneOrder(p->getPlaneIndex(), plane_b); }
180  /// @}
181 
182  /// @{
183  /// @brief Manipulate the data window of an image.
184  /// The data window is constant across all planes. It may be smaller than
185  /// the actual resolution (crop region) or larger. The data window is
186  /// inclusive in that x2 and y2 are part of the region. You can also use
187  /// the UT_DimRect versions for easier manipulations of the area.
188  /// Image data is only defined for the area contained by the data window.
189  /// By default, it is (0,0) - (xres-1, yres-1) (the entire image).
190  void setDataWindow(const UT_DimRect &win);
191  void setDataWindow(int x1, int y1, int x2, int y2);
192  void clearDataWindow();
193 
194  /// @brief Get the data window of an image.
195  void getDataWindow(UT_DimRect &r) const;
196  /// @brief Get the data window of an image.
197  void getDataWindow(int &x1, int &y1,
198  int &x2, int &y2) const;
199  /// @brief Return the data window for the image
200  const UT_DimRect &getDataWindow() const { return myDataWindow; }
201  /// @brief Returns true if the image has a data window
202  bool hasDataWindow() const;
203  /// @}
204 
205  /// The image data outside the data window can be represented one of two
206  /// ways: with a constant color, or by streaking the edges of the window.
207  /// @{
208  void setBackgroundColor(fpreal col[4]);
209  void getBackgroundColor(fpreal col[4]) const;
210 
211  void setBackgroundStreak(bool streak)
212  { myDataStreakFlag = streak; }
213  bool getBackgroundStreak() const {return myDataStreakFlag;}
214  /// @}
215 
216  /// This returns the width of the image. If no data window is
217  /// present, then this is Xres. If a data window is present, then
218  /// this is the width of the data window.
219  int getDataWidth() const;
220  /// This returns the height of the image. If no data window is
221  /// present, then this is Yres. If a data window is present, then
222  /// this is the height of the data window.
223  int getDataHeight() const;
224 
225  /// @deprecated
226  /// the number of frames in the file. Mostly for movie formats.
227  int getNumFrames() const { return myNumFrames; }
228  /// @deprecated
229  /// the number of frames in the file. Mostly for movie formats.
230  void setNumFrames(int nf) { myNumFrames = nf; }
231 
232  /// @deprecated the FPS for frame playback.
233  fpreal getFPS() const { return myFPS; }
234  /// @deprecated the FPS for frame playback.
235  void setFPS(fpreal fps) { myFPS = fps; }
236 
237  /// If the image file has a recorded render time, this
238  /// returns the render time, else it returns -1.
239  fpreal getRenderTime() const { return myRenderTime; }
240  /// Sets the render time from the image file.
241  void setRenderTime(fpreal t) { myRenderTime = t; }
242 
243  /// If the image file has a recorded render memory, this
244  /// returns the render memory, else it returns 0.
245  int64 getRenderMemory() const { return myRenderMemory; }
246  /// Sets the render time from the image file.
247  void setRenderMemory(int64 mem) { myRenderMemory = mem; }
248 
249  /// @{
250  /// @brief Set how deep samples are interpolated.
251  void setDeepStat(const img_DeepStatPtr &deep)
252  { myDeepStat = deep; }
254  { return myDeepStat; }
255  /// @}
256 
257 
258  // prints out the color model and data type.
259  static const char *getColorModel(IMG_ColorModel cm);
260  static const char *getDataType(IMG_DataType dt);
261 
262  /// Returns the total number of components across all planes.
263  int64 getComponentCount() const;
264 
265  /// Returns the number of components for the deep pixel image. This
266  /// excludes any pseudo-planes, such as "Depth-Complexity".
267  int64 getDeepPixelComponentCount() const;
268 
269 
270  /// Returns the number of bytes for a single pixel made up of all planes.
271  int64 bytesPerPixel() const;
272 
273  /// Returns the total number of bytes for the entire image. Returns -1 for
274  /// deep images, since the size is dependent on sample count.
275  int64 bytesPerImage() const;
276 
277  /// Returns the total number of bytes for a single scanline. Returns -1 for
278  /// deep images, since the size is dependent on sample count.
279  int64 bytesPerScanline() const;
280 
281  /// @{
282  /// Returns the number bytes for a single scanline. Returns -1 for
283  /// deep images, since the size is dependent on sample count.
284  int64 bytesPerPlaneScan(const IMG_Plane &pi) const;
285  int64 bytesPerPlaneScan(int i) const;
286  /// @}
287 
288  /// @{
289  /// For 2D images, returns the offset into the data for a plane in a given
290  /// scanline. Plane data is arranged consecutively by scanline.
291  /// For deep images, returns the offset into a pixel sample for a given
292  /// plane's data. Planes are interleaved by a pixel sample.
293  int planeOffset(const IMG_Plane &pi) const;
294  int planeOffset(int i) const;
295  /// @}
296 
297  /// Sets the color space for all planes. gamma is only needed for the
298  /// PXL_CS_CUSTOM_GAMMA space.
299  void setColorSpace(PXL_ColorSpace cs, fpreal gamma = 0.0);
300 
301  /// Set the color space on planes with an unknown color space to 'cs'.
302  /// gamma is only needed for the PXL_CS_CUSTOM_GAMMA space.
303  void setColorSpaceForUnknownPlanes(PXL_ColorSpace cs,
304  fpreal gamma = 0.0);
305 
306 
307 protected:
308  friend class IMG_Plane;
309  void recomputeOffsets();
310 private:
311  void init(int xres, int yres);
312 
313  IMG_ImageType myImageType;
314  UT_String myName;
315  UT_ValArray<IMG_Plane *> myPlanes;
316  UT_IntArray myPlaneOffset;
317  fpreal myDataWindowColor[4];
318  UT_DimRect myDataWindow;
319  fpreal myAspectRatio;
320  fpreal myFPS;
321  fpreal myRenderTime;
322  int64 myRenderMemory;
323  img_DeepStatPtr myDeepStat;
324  unsigned myXres, myYres;
325  int myNumFrames;
326  int myScanlineSize;
327  bool myDataStreakFlag;
328  bool myHasDataWindow;
329  bool myEnvMapPlanes;
330 };
331 
332 #endif
333 
fpreal getRenderTime() const
Definition: IMG_Stat.h:239
fpreal getAspectRatio() const
Definition: IMG_Stat.h:99
void setFPS(fpreal fps)
Definition: IMG_Stat.h:235
fpreal getFPS() const
Definition: IMG_Stat.h:233
IMG_ImageType
Type of image we want to create or have opened.
int64 getRenderMemory() const
Definition: IMG_Stat.h:245
int getNumFrames() const
Definition: IMG_Stat.h:227
void setResolution(unsigned xres, unsigned yres)
Definition: IMG_Stat.h:81
IMG_ImageType getImageType() const
Definition: IMG_Stat.h:76
Describes the format and layout of a single plane in an image The plane specifies the format and name...
Definition: IMG_Plane.h:44
png_uint_32 i
Definition: png.h:2877
void setRenderTime(fpreal t)
Sets the render time from the image file.
Definition: IMG_Stat.h:241
const img_DeepStatPtr & getDeepStat() const
Set how deep samples are interpolated.
Definition: IMG_Stat.h:253
void setAspectRatio(fpreal aspect)
Definition: IMG_Stat.h:98
long long int64
Definition: SYS_Types.h:106
#define IMG_API
Definition: IMG_API.h:10
bool isEnvMap() const
isEnvMap() will return true, only if the image is an environment map.
Definition: IMG_Stat.h:152
bool getBackgroundStreak() const
Definition: IMG_Stat.h:213
IMG_DataType
Definition: IMG_FileTypes.h:17
UT_SharedPtr< IMG_DeepStat > img_DeepStatPtr
Definition: IMG_Stat.h:43
unsigned getYres() const
Definition: IMG_Stat.h:93
unsigned getXres() const
Definition: IMG_Stat.h:92
const UT_DimRect & getDataWindow() const
Return the data window for the image.
Definition: IMG_Stat.h:200
IMG_Plane * addDefaultPlane()
Add a default 8bit, RGBA plane to the image.
Definition: IMG_Stat.h:143
GLuint const GLchar * name
Definition: glcorearb.h:785
IMG_Stat information used when creating deep images.
Definition: IMG_DeepStat.h:56
void setRenderMemory(int64 mem)
Sets the render time from the image file.
Definition: IMG_Stat.h:247
void swapPlaneOrder(const IMG_Plane *p, int plane_b)
Definition: IMG_Stat.h:178
double fpreal
Definition: SYS_Types.h:269
IMG_Stat(const IMG_Stat &s)
Definition: IMG_Stat.h:58
void setFilename(const char *name)
Definition: IMG_Stat.h:106
PXL_ColorSpace
Definition: PXL_Common.h:42
IMG_ColorModel
Definition: IMG_FileTypes.h:53
Contains the details of a specific image file, used by IMG_File. This class contains all the high-lev...
Definition: IMG_Stat.h:40
int getPlaneIndex() const
Definition: IMG_Plane.h:127
GLboolean r
Definition: glcorearb.h:1221
void setBackgroundStreak(bool streak)
Definition: IMG_Stat.h:211
const UT_String & getFilename() const
Definition: IMG_Stat.h:107
IMG_Stat & operator=(const IMG_Stat &s)
Definition: IMG_Stat.h:62
void setNumFrames(int nf)
Definition: IMG_Stat.h:230
void setDeepStat(const img_DeepStatPtr &deep)
Set how deep samples are interpolated.
Definition: IMG_Stat.h:251
GLenum src
Definition: glcorearb.h:1792