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 "ImfUtilExport.h"
99 
101 
102 struct Channel;
103 
104 
105 class Image
106 {
107  public:
108 
109  //
110  // Constructor and destructor
111  //
112 
114  Image ();
116  virtual ~Image ();
117 
118 
119  //
120  // Access to the image's level mode and level rounding mode.
121  //
122 
124  LevelMode levelMode() const;
127 
128 
129  //
130  // Number of levels:
131  //
132  // numXLevels() returns the image's number of levels in the x direction.
133  //
134  // if levelMode() == ONE_LEVEL:
135  // return value is: 1
136  //
137  // if levelMode() == MIPMAP_LEVELS:
138  // return value is: rfunc (log (max (w, h)) / log (2)) + 1
139  //
140  // if levelMode() == RIPMAP_LEVELS:
141  // return value is: rfunc (log (w) / log (2)) + 1
142  //
143  // where
144  // w is the width of the image's data window, max.x - min.x + 1,
145  // h is the height of the image's data window, max.y - min.y + 1,
146  // and rfunc(x) is either floor(x), or ceil(x), depending on
147  // whether levelRoundingMode() returns ROUND_DOWN or ROUND_UP.
148  //
149  // numYLevels() returns the image's number of levels in the y direction.
150  //
151  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
152  // return value is the same as for numXLevels()
153  //
154  // if levelMode() == RIPMAP_LEVELS:
155  // return value is: rfunc (log (h) / log (2)) + 1
156  //
157  //
158  // numLevels() is a convenience function for use with MIPMAP_LEVELS images.
159  //
160  // if levelMode() == ONE_LEVEL or levelMode() == MIPMAP_LEVELS:
161  // return value is the same as for numXLevels()
162  //
163  // if levelMode() == RIPMAP_LEVELS:
164  // a LogicExc exception is thrown
165  //
166 
168  int numLevels() const;
170  int numXLevels() const;
172  int numYLevels() const;
173 
174 
175  //
176  // Per-level data windows
177  //
178  // dataWindow() returns the data window for the image; this is the
179  // same as the data window for the level with level number (0, 0).
180  //
181  // dataWindowForLevel(lx, ly) returns the data window for level x,
182  // that is, the window for which the image level with level number
183  // (lx, ly) has allocated pixel storage.
184  //
185  // return value is a Box2i with min value:
186  // (dataWindow().min.x,
187  // dataWindow().min.y)
188  //
189  // and max value:
190  // (dataWindow().min.x + levelWidth(lx) - 1,
191  // dataWindow().min.y + levelHeight(ly) - 1)
192  //
193  // dataWindowForLevel(l) is a convenience function used for ONE_LEVEL
194  // and MIPMAP_LEVELS files. It returns dataWindowForLevel(l,l)).
195  //
196 
198  const IMATH_NAMESPACE::Box2i & dataWindow() const;
200  const IMATH_NAMESPACE::Box2i & dataWindowForLevel(int l) const;
202  const IMATH_NAMESPACE::Box2i & dataWindowForLevel(int lx, int ly) const;
203 
204 
205  //
206  // Size of a level:
207  //
208  // levelWidth(lx) returns the width of a level with level
209  // number (lx, *), where * is any number.
210  //
211  // return value is:
212  // max (1, rfunc (w / pow (2, lx)))
213  //
214  //
215  // levelHeight(ly) returns the height of a level with level
216  // number (*, ly), where * is any number.
217  //
218  // return value is:
219  // max (1, rfunc (h / pow (2, ly)))
220  //
221 
223  int levelWidth (int lx) const;
225  int levelHeight (int ly) const;
226 
227 
228  //
229  // Resize the image:
230  //
231  // resize(dw,lm,lrm) sets the data window of the image to dw,
232  // sets the level mode to lm and the level rounding mode to lrm,
233  // and allocates new storage for image levels and image channels.
234  // The set of channels in the image does not change.
235  //
236  // The contents of the image are lost; pixel data are not preserved
237  // across the resize operation. If resizing fails, then the image
238  // will be left with an empty data window and no image levels.
239  //
240  // resize(dw) is the same as resize(dw,levelMode(),levelRoundingMode())
241  //
242 
244  void resize(const IMATH_NAMESPACE::Box2i &dataWindow);
245 
247  virtual void resize(const IMATH_NAMESPACE::Box2i &dataWindow,
248  LevelMode levelMode,
249  LevelRoundingMode levelRoundingMode);
250 
251  //
252  // Shift the pixels and the data window of an image:
253  //
254  // shiftPixels(dx,dy) shifts the image by dx pixels horizontally and
255  // dy pixels vertically. A pixel at location (x,y) moves to position
256  // (x+dx, y+dy). The data window of the image is shifted along with
257  // the pixels. No pixel data are lost.
258  //
259  // The horizontal and vertical shift distances must be multiples of
260  // the x and y sampling rates of all image channels. If they are not,
261  // shiftPixels() throws an ArgExc exception.
262  //
263 
265  void shiftPixels(int dx, int dy);
266 
267 
268  //
269  // Insert a new channel into the image.
270  //
271  // The arguments to this function are the same as for adding a
272  // a channel to an OpenEXR file: channel name, x and y sampling
273  // rates, and a "perceptually approximately linear" flag.
274  //
275  // If the image already contains a channel with the same name
276  // as the new name then the existing channel is deleted before
277  // the new channel is added.
278  //
279 
281  void insertChannel (const std::string &name,
282  PixelType type,
283  int xSampling = 1,
284  int ySampling = 1,
285  bool pLinear = false);
286 
288  void insertChannel (const std::string &name,
289  const Channel &channel);
290 
291  //
292  // Erase channels from an image:
293  //
294  // eraseChannel(n) erases the channel with name n.
295  // clearChannels() erases all channels.
296  //
297 
299  void eraseChannel(const std::string &name);
301  void clearChannels();
302 
303 
304  //
305  // Rename an image channel:
306  //
307  // renameChannel(nOld,nNew) changes the name of the image channel
308  // with name nOld to nNew.
309  //
310  // If the image already contains a channel called nNew, or if the
311  // image does not contain a channel called nOld, then renameChannel()
312  // throws an ArgExc exception.
313  //
314  // In the (unlikely) event that renaming the image channel causes
315  // the program to run out of memory, renameChannel() erases the
316  // channel that is being renamed, and throws an exception.
317  //
318 
320  void renameChannel(const std::string &oldName,
321  const std::string &newName);
322 
323  //
324  // Rename multiple image channels at the same time:
325  //
326  // Given a map, m, from old to new channel names, renameChannels(m)
327  // assigns new names to the channels in the image. If m has an entry
328  // for a channel named c, then the channel will be renamed to m[c].
329  // If m has no entry for c, then the channel keeps its old name.
330  //
331  // If the same name would be assigned to more than one channel, then
332  // renameChannels() does not rename any channels but throws an ArgExc
333  // exception instead.
334  //
335  // In the (unlikely) event that renaming the image channel causes the
336  // program to run out of memory, renameChannels() erases all channels
337  // in the image and throws an exception.
338  //
339 
341  void renameChannels(const RenamingMap &oldToNewNames);
342 
343 
344  //
345  // Accessing image levels by level number.
346  //
347  // level(lx,ly) returns a reference to the image level
348  // with level number (lx,ly).
349  //
350  // level(l) returns level(l,l).
351  //
352 
354  virtual ImageLevel & level (int l = 0);
356  virtual const ImageLevel & level (int l = 0) const;
357 
359  virtual ImageLevel & level (int lx, int ly);
361  virtual const ImageLevel & level (int lx, int ly) const;
362 
363 
364  protected:
365 
366  virtual ImageLevel *
367  newLevel (int lx, int ly, const IMATH_NAMESPACE::Box2i &dataWindow) = 0;
368 
369  private:
370 
371  bool levelNumberIsValid (int lx, int ly) const;
372  void clearLevels ();
373 
374  struct ChannelInfo
375  {
376  ChannelInfo (PixelType type = HALF,
377  int xSampling = 1,
378  int ySampling = 1,
379  bool pLinear = false);
380 
381  PixelType type;
382  int xSampling;
383  int ySampling;
384  bool pLinear;
385  };
386 
387  typedef std::map <std::string, ChannelInfo> ChannelMap;
388 
389  IMATH_NAMESPACE::Box2i _dataWindow;
390  LevelMode _levelMode;
391  LevelRoundingMode _levelRoundingMode;
392  ChannelMap _channels;
393  Array2D<ImageLevel *> _levels;
394 };
395 
396 
398 
399 #endif
type
Definition: core.h:977
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
Definition: ImfNamespace.h:109
IMFUTIL_EXPORT const IMATH_NAMESPACE::Box2i & dataWindow() const
virtual IMFUTIL_EXPORT ImageLevel & level(int l=0)
GLuint const GLchar * name
Definition: glcorearb.h:785
IMFUTIL_EXPORT void clearChannels()
GLdouble l
Definition: glew.h:9164
IMFUTIL_EXPORT void insertChannel(const std::string &name, PixelType type, int xSampling=1, int ySampling=1, bool pLinear=false)
IMFUTIL_EXPORT void renameChannels(const RenamingMap &oldToNewNames)
IMFUTIL_EXPORT void eraseChannel(const std::string &name)
IMFUTIL_EXPORT Image()
#define IMFUTIL_EXPORT
Definition: ImfUtilExport.h:44
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER typedef std::map< std::string, std::string > RenamingMap
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
Box< V2i > Box2i
Definition: ImathBox.h:133
PixelType
Definition: ImfPixelType.h:51
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
LevelRoundingMode
IMFUTIL_EXPORT LevelRoundingMode levelRoundingMode() const
IMFUTIL_EXPORT int numLevels() const
IMFUTIL_EXPORT void renameChannel(const std::string &oldName, const std::string &newName)
IMFUTIL_EXPORT const IMATH_NAMESPACE::Box2i & dataWindowForLevel(int l) const
virtual IMFUTIL_EXPORT ~Image()
IMFUTIL_EXPORT int numYLevels() const
IMFUTIL_EXPORT int levelWidth(int lx) const
IMFUTIL_EXPORT LevelMode levelMode() const
IMFUTIL_EXPORT void shiftPixels(int dx, int dy)
#define OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
Definition: ImfNamespace.h:108
IMFUTIL_EXPORT void resize(const IMATH_NAMESPACE::Box2i &dataWindow)
virtual ImageLevel * newLevel(int lx, int ly, const IMATH_NAMESPACE::Box2i &dataWindow)=0
IMFUTIL_EXPORT int levelHeight(int ly) const
IMFUTIL_EXPORT int numXLevels() const