HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Image.h
Go to the documentation of this file.
1 //
2 // TM & (c) 2017 Lucasfilm Entertainment Company Ltd. and Lucasfilm Ltd.
3 // All rights reserved. See LICENSE.txt for license.
4 //
5 
6 #ifndef MATERIALX_IMAGE_H
7 #define MATERIALX_IMAGE_H
8 
9 /// @file
10 /// Image class
11 
12 #include <MaterialXRender/Export.h>
13 
14 #include <MaterialXFormat/File.h>
15 
16 #include <MaterialXCore/Types.h>
17 
19 
20 class Image;
21 
22 /// A shared pointer to an image
23 using ImagePtr = shared_ptr<Image>;
24 
25 /// A shared pointer to a const image
26 using ConstImagePtr = shared_ptr<const Image>;
27 
28 /// A map from strings to images.
29 using ImageMap = std::unordered_map<string, ImagePtr>;
30 
31 /// A vetor of images.
32 using ImageVec = std::vector<ImagePtr>;
33 
34 /// A pair of images.
35 using ImagePair = std::pair<ImagePtr, ImagePtr>;
36 
37 /// A function to perform image buffer deallocation
38 using ImageBufferDeallocator = std::function<void(void*)>;
39 
40 /// @class Image
41 /// Class representing an image in system memory
43 {
44  public:
45  enum class BaseType
46  {
47  UINT8 = 0,
48  UINT16 = 1,
49  HALF = 2,
50  FLOAT = 3
51  };
52 
53  public:
54  /// Create an empty image with the given properties.
55  static ImagePtr create(unsigned int width, unsigned int height, unsigned int channelCount, BaseType baseType = BaseType::UINT8)
56  {
57  return ImagePtr(new Image(width, height, channelCount, baseType));
58  }
59 
60  ~Image();
61 
62  /// @name Property Accessors
63  /// @{
64 
65  /// Return the width of the image.
66  unsigned int getWidth() const
67  {
68  return _width;
69  }
70 
71  /// Return the height of the image.
72  unsigned int getHeight() const
73  {
74  return _height;
75  }
76 
77  /// Return the channel count of the image.
78  unsigned int getChannelCount() const
79  {
80  return _channelCount;
81  }
82 
83  /// Return the base type of the image.
85  {
86  return _baseType;
87  }
88 
89  /// Return the stride of our base type in bytes.
90  unsigned int getBaseStride() const;
91 
92  /// Return the stride of an image row in bytes.
93  unsigned int getRowStride() const
94  {
95  return _width * _channelCount * getBaseStride();
96  }
97 
98  /// Return the maximum number of mipmaps for this image.
99  unsigned int getMaxMipCount() const;
100 
101  /// @}
102  /// @name Texel Accessors
103  /// @{
104 
105  /// Set the texel color at the given coordinates. If the coordinates
106  /// or image resource buffer are invalid, then an exception is thrown.
107  void setTexelColor(unsigned int x, unsigned int y, const Color4& color);
108 
109  /// Return the texel color at the given coordinates. If the coordinates
110  /// or image resource buffer are invalid, then an exception is thrown.
111  Color4 getTexelColor(unsigned int x, unsigned int y) const;
112 
113  /// @}
114  /// @name Image Analysis
115  /// @{
116 
117  /// Compute the average color of the image.
118  Color4 getAverageColor();
119 
120  /// Return true if all texels of this image are identical in color.
121  /// @param uniformColor Return the uniform color of the image, if any.
122  bool isUniformColor(Color4* uniformColor = nullptr);
123 
124  /// @}
125  /// @name Image Processing
126  /// @{
127 
128  /// Set all texels of this image to a uniform color.
129  void setUniformColor(const Color4& color);
130 
131  /// Apply the given matrix transform to all texels of this image.
132  void applyMatrixTransform(const Matrix33& mat);
133 
134  /// Apply the given gamma transform to all texels of this image.
135  void applyGammaTransform(float gamma);
136 
137  /// Create a copy of this image with the given channel count and base type.
138  ImagePtr copy(unsigned int channelCount, BaseType baseType) const;
139 
140  /// Apply a 3x3 box blur to this image, returning a new blurred image.
141  ImagePtr applyBoxBlur();
142 
143  /// Apply a 7x7 Gaussian blur to this image, returning a new blurred image.
144  ImagePtr applyGaussianBlur();
145 
146  /// Split this image by the given luminance threshold, returning the
147  /// resulting underflow and overflow images.
148  ImagePair splitByLuminance(float luminance);
149 
150  /// Save a channel of this image to disk as a text table, in a format
151  /// that can be used for curve and surface fitting.
152  void writeTable(const FilePath& filePath, unsigned int channel);
153 
154  /// @}
155  /// @name Resource Buffers
156  /// @{
157 
158  /// Set the resource buffer for this image.
160  {
161  _resourceBuffer = buffer;
162  }
163 
164  /// Return the resource buffer for this image.
165  void* getResourceBuffer() const
166  {
167  return _resourceBuffer;
168  }
169 
170  /// Allocate a resource buffer for this image that matches its properties.
171  void createResourceBuffer();
172 
173  /// Release the resource buffer for this image.
174  void releaseResourceBuffer();
175 
176  /// Set the resource buffer deallocator for this image.
178  {
179  _resourceBufferDeallocator = deallocator;
180  }
181 
182  /// Return the resource buffer deallocator for this image.
184  {
185  return _resourceBufferDeallocator;
186  }
187 
188  /// @}
189  /// @name Resource IDs
190  /// @{
191 
192  /// Set the resource ID for this image.
193  void setResourceId(unsigned int id)
194  {
195  _resourceId = id;
196  }
197 
198  /// Return the resource ID for this image.
199  unsigned int getResourceId() const
200  {
201  return _resourceId;
202  }
203 
204  /// @}
205 
206  protected:
207  Image(unsigned int width, unsigned int height, unsigned int channelCount, BaseType baseType);
208 
209  protected:
210  unsigned int _width;
211  unsigned int _height;
212  unsigned int _channelCount;
214 
217  unsigned int _resourceId;
218 };
219 
220 /// Create a uniform-color image with the given properties.
221 MX_RENDER_API ImagePtr createUniformImage(unsigned int width, unsigned int height, unsigned int channelCount, Image::BaseType baseType, const Color4& color);
222 
223 /// Create a horizontal image strip from a vector of images with identical resolutions and formats.
224 MX_RENDER_API ImagePtr createImageStrip(const vector<ImagePtr>& imageVec);
225 
226 /// Compute the maximum width and height of all images in the given vector.
227 MX_RENDER_API std::pair<unsigned int, unsigned int> getMaxDimensions(const vector<ImagePtr>& imageVec);
228 
230 
231 #endif
unsigned int getWidth() const
Return the width of the image.
Definition: Image.h:66
BaseType getBaseType() const
Return the base type of the image.
Definition: Image.h:84
Definition: File.h:26
std::unordered_map< string, ImagePtr > ImageMap
A map from strings to images.
Definition: Image.h:29
void setResourceBuffer(void *buffer)
Set the resource buffer for this image.
Definition: Image.h:159
HALF
Definition: ImfPixelType.h:25
#define MATERIALX_NAMESPACE_BEGIN
Definition: Generated.h:23
OIIO_UTIL_API bool copy(string_view from, string_view to, std::string &err)
FLOAT
Definition: ImfPixelType.h:26
unsigned int getRowStride() const
Return the stride of an image row in bytes.
Definition: Image.h:93
ImageBufferDeallocator getResourceBufferDeallocator() const
Return the resource buffer deallocator for this image.
Definition: Image.h:183
GLuint color
Definition: glcorearb.h:1261
unsigned int _channelCount
Definition: Image.h:212
MX_RENDER_API std::pair< unsigned int, unsigned int > getMaxDimensions(const vector< ImagePtr > &imageVec)
Compute the maximum width and height of all images in the given vector.
std::vector< ImagePtr > ImageVec
A vetor of images.
Definition: Image.h:32
Definition: Image.h:42
GLuint buffer
Definition: glcorearb.h:660
unsigned int getChannelCount() const
Return the channel count of the image.
Definition: Image.h:78
GLint GLenum GLint x
Definition: glcorearb.h:409
BaseType
Definition: Image.h:45
Definition: core.h:760
std::function< void(void *)> ImageBufferDeallocator
A function to perform image buffer deallocation.
Definition: Image.h:38
static ImagePtr create(unsigned int width, unsigned int height, unsigned int channelCount, BaseType baseType=BaseType::UINT8)
Create an empty image with the given properties.
Definition: Image.h:55
void * _resourceBuffer
Definition: Image.h:215
GLuint id
Definition: glcorearb.h:655
MX_RENDER_API ImagePtr createUniformImage(unsigned int width, unsigned int height, unsigned int channelCount, Image::BaseType baseType, const Color4 &color)
Create a uniform-color image with the given properties.
MX_RENDER_API ImagePtr createImageStrip(const vector< ImagePtr > &imageVec)
Create a horizontal image strip from a vector of images with identical resolutions and formats...
GLint GLsizei width
Definition: glcorearb.h:103
unsigned int _resourceId
Definition: Image.h:217
GLint GLsizei GLsizei height
Definition: glcorearb.h:103
unsigned int _width
Definition: Image.h:210
#define MX_RENDER_API
Definition: Export.h:18
void setResourceBufferDeallocator(ImageBufferDeallocator deallocator)
Set the resource buffer deallocator for this image.
Definition: Image.h:177
unsigned int _height
Definition: Image.h:211
ImageBufferDeallocator _resourceBufferDeallocator
Definition: Image.h:216
#define MATERIALX_NAMESPACE_END
Definition: Generated.h:24
BaseType _baseType
Definition: Image.h:213
shared_ptr< Image > ImagePtr
A shared pointer to an image.
Definition: Image.h:23
unsigned int getHeight() const
Return the height of the image.
Definition: Image.h:72
void * getResourceBuffer() const
Return the resource buffer for this image.
Definition: Image.h:165
unsigned int getResourceId() const
Return the resource ID for this image.
Definition: Image.h:199
GLint y
Definition: glcorearb.h:103
void setResourceId(unsigned int id)
Set the resource ID for this image.
Definition: Image.h:193
shared_ptr< const Image > ConstImagePtr
A shared pointer to a const image.
Definition: Image.h:26
std::pair< ImagePtr, ImagePtr > ImagePair
A pair of images.
Definition: Image.h:35