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