HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImfImage.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2014, 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 #ifndef INCLUDED_IMF_IMAGE_H
36 #define INCLUDED_IMF_IMAGE_H
37 
38 //----------------------------------------------------------------------------
39 //
40 // class Image -- an in-memory data structure that can hold an arbitrary
41 // OpenEXR image, flat or deep, with one or multiple resolution levels,
42 // and with an arbitrary set of channels.
43 //
44 // An image is a container for a set of image levels, and an image level
45 // is a container for a set of image channels. An image channel contains
46 // an array of pixel values of type half, float or unsigned int.
47 //
48 // For example:
49 //
50 // image --+-- level 0 --+-- channel "R" --- pixel data
51 // | |
52 // | +-- channel "G" --- pixel data
53 // | |
54 // | +-- channel "B" --- pixel data
55 // |
56 // +-- level 1 --+-- channel "R" --- pixel data
57 // | |
58 // | +-- channel "G" --- pixel data
59 // | |
60 // | +-- channel "B" --- pixel data
61 // |
62 // +-- level 2 --+-- channel "R" --- pixel data
63 // |
64 // +-- channel "G" --- pixel data
65 // |
66 // +-- channel "B" --- pixel data
67 //
68 // An image has a level mode, which can be ONE_LEVEL, MIPMAP_LEVELS or
69 // RIPMAP_LEVELS, and a level rounding mode, which can be ROUND_UP or
70 // ROUND_DOWN. Together, the level mode and the level rounding mode
71 // determine how many levels an image contains, and how large the data
72 // window for each level is. All levels in an image have the same set
73 // of channels.
74 //
75 // An image channel has a name (e.g. "R", "Z", or "xVelocity"), a type
76 // (HALF, FLOAT or UINT) and x and y sampling rates. A channel stores
77 // samples for a pixel if the pixel is inside the data window of the
78 // level to which the channel belongs, and the x and y coordinates of
79 // the pixel are divisible by the x and y sampling rates of the channel.
80 //
81 // An image can be either flat or deep. In a flat image each channel
82 // in each level stores at most one value per pixel. In a deep image
83 // each channel in each level stores an arbitrary number of values per
84 // pixel. As an exception, each level of a deep image has a sample count
85 // channel with a single value per pixel; this value determines how many
86 // values each of the other channels in the same level has at the same
87 // pixel location.
88 //
89 // The classes Image, ImageLevel and ImageChannel are abstract base
90 // classes. Two sets of concrete classes, one for flat and one for
91 // deep images, are derived from the base classes.
92 //
93 //----------------------------------------------------------------------------
94 
95 #include "ImfImageLevel.h"
96 #include <ImfTileDescription.h>
97 #include <ImfArray.h>
98 #include "ImfExport.h"
99 
101 
102 class Channel;
103 
104 
106 {
107  public:
108 
109  //
110  // Constructor and destructor
111  //
112 
113  Image ();
114  virtual ~Image ();
115 
116 
117  //
118  // Access to the image's level mode and level rounding mode.
119  //
120 
121  LevelMode levelMode() const;
122  LevelRoundingMode levelRoundingMode() const;
123 
124 
125  //
126  // Number of levels:
127  //
128  // numXLevels() returns the image's number of levels in the x direction.
129  //
130  // if levelMode() == ONE_LEVEL:
131  // return value is: 1
132  //
133  // if levelMode() == MIPMAP_LEVELS:
134  // return value is: rfunc (log (max (w, h)) / log (2)) + 1
135  //
136  // if levelMode() == RIPMAP_LEVELS:
137  // return value is: rfunc (log (w) / log (2)) + 1
138  //
139  // where
140  // w is the width of the image's data window, max.x - min.x + 1,
141  // h is the height of the image's data window, max.y - min.y + 1,
142  // and rfunc(x) is either floor(x), or ceil(x), depending on
143  // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
144  //
145  // numYLevels() returns the image's number of levels in the y direction.
146  //
147  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
148  // return value is the same as for numXLevels()
149  //
150  // if levelMode() == RIPMAP_LEVELS:
151  // return value is: rfunc (log (h) / log (2)) + 1
152  //
153  //
154  // numLevels() is a convenience function for use with MIPMAP_LEVELS images.
155  //
156  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
157  // return value is the same as for numXLevels()
158  //
159  // if levelMode() == RIPMAP_LEVELS:
160  // a LogicExc exception is thrown
161  //
162 
163  int numLevels() const;
164  int numXLevels() const;
165  int numYLevels() const;
166 
167 
168  //
169  // Per-level data windows
170  //
171  // dataWindow() returns the data window for the image; this is the
172  // same as the data window for the level with level number (0, 0).
173  //
174  // dataWindowForLevel(lx, ly) returns the data window for level x,
175  // that is, the window for which the image level with level number
176  // (lx, ly) has allocated pixel storage.
177  //
178  // return value is a Box2i with min value:
179  // (dataWindow().min.x,
180  // dataWindow().min.y)
181  //
182  // and max value:
183  // (dataWindow().min.x + levelWidth(lx) - 1,
184  // dataWindow().min.y + levelHeight(ly) - 1)
185  //
186  // dataWindowForLevel(l) is a convenience function used for ONE_LEVEL
187  // and MIPMAP_LEVELS files. It returns dataWindowForLevel(l,l)).
188  //
189 
190  const IMATH_NAMESPACE::Box2i & dataWindow() const;
191  const IMATH_NAMESPACE::Box2i & dataWindowForLevel(int l) const;
192  const IMATH_NAMESPACE::Box2i & dataWindowForLevel(int lx, int ly) const;
193 
194 
195  //
196  // Size of a level:
197  //
198  // levelWidth(lx) returns the width of a level with level
199  // number (lx, *), where * is any number.
200  //
201  // return value is:
202  // max (1, rfunc (w / pow (2, lx)))
203  //
204  //
205  // levelHeight(ly) returns the height of a level with level
206  // number (*, ly), where * is any number.
207  //
208  // return value is:
209  // max (1, rfunc (h / pow (2, ly)))
210  //
211 
212  int levelWidth (int lx) const;
213  int levelHeight (int ly) const;
214 
215 
216  //
217  // Resize the image:
218  //
219  // resize(dw,lm,lrm) sets the data window of the image to dw,
220  // sets the level mode to lm and the level rounding mode to lrm,
221  // and allocates new storage for image levels and image channels.
222  // The set of channels in the image does not change.
223  //
224  // The contents of the image are lost; pixel data are not preserved
225  // across the resize operation. If resizing fails, then the image
226  // will be left with an empty data window and no image levels.
227  //
228  // resize(dw) is the same as resize(dw,levelMode(),levelRoundingMode())
229  //
230 
231  void resize(const IMATH_NAMESPACE::Box2i &dataWindow);
232 
233  virtual void resize(const IMATH_NAMESPACE::Box2i &dataWindow,
234  LevelMode levelMode,
235  LevelRoundingMode levelRoundingMode);
236 
237  //
238  // Shift the pixels and the data window of an image:
239  //
240  // shiftPixels(dx,dy) shifts the image by dx pixels horizontally and
241  // dy pixels vertically. A pixel at location (x,y) moves to position
242  // (x+dx, y+dy). The data window of the image is shifted along with
243  // the pixels. No pixel data are lost.
244  //
245  // The horizontal and vertical shift distances must be multiples of
246  // the x and y sampling rates of all image channels. If they are not,
247  // shiftPixels() throws an ArgExc exception.
248  //
249 
250  void shiftPixels(int dx, int dy);
251 
252 
253  //
254  // Insert a new channel into the image.
255  //
256  // The arguments to this function are the same as for adding a
257  // a channel to an OpenEXR file: channel name, x and y sampling
258  // rates, and a "perceptually approximately linear" flag.
259  //
260  // If the image already contains a channel with the same name
261  // as the new name then the existing channel is deleted before
262  // the new channel is added.
263  //
264 
265  void insertChannel (const std::string &name,
266  PixelType type,
267  int xSampling = 1,
268  int ySampling = 1,
269  bool pLinear = false);
270 
271  void insertChannel (const std::string &name,
272  const Channel &channel);
273 
274  //
275  // Erase channels from an image:
276  //
277  // eraseChannel(n) erases the channel with name n.
278  // clearChannels() erases all channels.
279  //
280 
281  void eraseChannel(const std::string &name);
282  void clearChannels();
283 
284 
285  //
286  // Rename an image channel:
287  //
288  // renameChannel(nOld,nNew) changes the name of the image channel
289  // with name nOld to nNew.
290  //
291  // If the image already contains a channel called nNew, or if the
292  // image does not contain a channel called nOld, then renameChannel()
293  // throws an ArgExc exception.
294  //
295  // In the (unlikely) event that renaming the image channel causes
296  // the program to run out of memory, renameChannel() erases the
297  // channel that is being renamed, and throws an exception.
298  //
299 
300  void renameChannel(const std::string &oldName,
301  const std::string &newName);
302 
303  //
304  // Rename multiple image channels at the same time:
305  //
306  // Given a map, m, from old to new channel names, renameChannels(m)
307  // assigns new names to the channels in the image. If m has an entry
308  // for a channel named c, then the channel will be renamed to m[c].
309  // If m has no entry for c, then the channel keeps its old name.
310  //
311  // If the same name would be assigned to more than one channel, then
312  // renameChannels() does not rename any channels but throws an ArgExc
313  // exception instead.
314  //
315  // In the (unlikely) event that renaming the image channel causes the
316  // program to run out of memory, renameChannels() erases all channels
317  // in the image and throws an exception.
318  //
319 
320  void renameChannels(const RenamingMap &oldToNewNames);
321 
322 
323  //
324  // Accessing image levels by level number.
325  //
326  // level(lx,ly) returns a reference to the image level
327  // with level number (lx,ly).
328  //
329  // level(l) returns level(l,l).
330  //
331 
332  virtual ImageLevel & level (int l = 0);
333  virtual const ImageLevel & level (int l = 0) const;
334 
335  virtual ImageLevel & level (int lx, int ly);
336  virtual const ImageLevel & level (int lx, int ly) const;
337 
338 
339  protected:
340 
341  virtual ImageLevel *
342  newLevel (int lx, int ly, const IMATH_NAMESPACE::Box2i &dataWindow) = 0;
343 
344  private:
345 
346  bool levelNumberIsValid (int lx, int ly) const;
347  void clearLevels ();
348 
349  struct ChannelInfo
350  {
351  ChannelInfo (PixelType type = HALF,
352  int xSampling = 1,
353  int ySampling = 1,
354  bool pLinear = false);
355 
356  PixelType type;
357  int xSampling;
358  int ySampling;
359  bool pLinear;
360  };
361 
362  typedef std::map <std::string, ChannelInfo> ChannelMap;
363 
364  IMATH_NAMESPACE::Box2i _dataWindow;
365  LevelMode _levelMode;
366  LevelRoundingMode _levelRoundingMode;
367  ChannelMap _channels;
368  Array2D<ImageLevel *> _levels;
369 };
370 
371 
373 
374 #endif
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
Definition: ImfNamespace.h:109
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
GLint level
Definition: glcorearb.h:107
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER typedef std::map< std::string, std::string > RenamingMap
Box< V2i > Box2i
Definition: ImathBox.h:133
PixelType
Definition: ImfPixelType.h:51
LevelRoundingMode
#define IMF_EXPORT
Definition: ImfExport.h:59
GLuint const GLchar * name
Definition: glcorearb.h:785
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
Definition: ImfNamespace.h:108
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107