HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ImageHandler.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_IMAGEHANDLER_H
7 #define MATERIALX_IMAGEHANDLER_H
8 
9 /// @file
10 /// Image handler interfaces
11 
12 #include <MaterialXRender/Export.h>
13 #include <MaterialXRender/Image.h>
14 
15 #include <MaterialXFormat/File.h>
16 
17 #include <MaterialXCore/Document.h>
18 
20 
21 extern MX_RENDER_API const string IMAGE_PROPERTY_SEPARATOR;
22 extern MX_RENDER_API const string UADDRESS_MODE_SUFFIX;
23 extern MX_RENDER_API const string VADDRESS_MODE_SUFFIX;
24 extern MX_RENDER_API const string FILTER_TYPE_SUFFIX;
25 extern MX_RENDER_API const string DEFAULT_COLOR_SUFFIX;
26 
27 class ImageHandler;
28 class ImageLoader;
29 class VariableBlock;
30 
31 /// Shared pointer to an ImageHandler
32 using ImageHandlerPtr = std::shared_ptr<ImageHandler>;
33 
34 /// Shared pointer to an ImageLoader
35 using ImageLoaderPtr = std::shared_ptr<ImageLoader>;
36 
37 /// Map from strings to vectors of image loaders
38 using ImageLoaderMap = std::unordered_map<string, std::vector<ImageLoaderPtr>>;
39 
40 /// @class ImageSamplingProperties
41 /// Interface to describe sampling properties for images.
43 {
44  public:
45  /// Set the properties based on data in a uniform block.
46  /// @param fileNameUniform Name of the file name uniform. Used to find
47  /// corresponding sampler data in the uniform block
48  /// @param uniformBlock Block containing sampler uniforms
49  void setProperties(const string& fileNameUniform,
50  const VariableBlock& uniformBlock);
51 
52  bool operator==(const ImageSamplingProperties& r) const;
53 
54  /// Address mode options. Matches enumerations allowed for image address
55  /// modes, except UNSPECIFIED which indicates no explicit mode was defined.
56  enum class AddressMode : int
57  {
58  UNSPECIFIED = -1,
59  CONSTANT = 0,
60  CLAMP = 1,
61  PERIODIC = 2,
62  MIRROR = 3
63  };
64 
65  /// Address mode in U
66  AddressMode uaddressMode = AddressMode::UNSPECIFIED;
67  /// Address mode in V
68  AddressMode vaddressMode = AddressMode::UNSPECIFIED;
69 
70  /// Filter type options. Matches enumerations allowed for image filter
71  /// types, except UNSPECIFIED which indicates no explicit type was defined.
72  enum class FilterType : int
73  {
74  UNSPECIFIED = -1,
75  CLOSEST = 0,
76  LINEAR = 1,
77  CUBIC = 2
78  };
79 
80  /// Filter type
81  FilterType filterType = FilterType::UNSPECIFIED;
82 
83  /// Enable mipmaps
84  bool enableMipmaps = true;
85 
86  /// Default color. Corresponds to the "default" value on the image
87  /// node definition.
88  Color4 defaultColor = { 0.0f, 0.0f, 0.0f, 1.0f };
89 };
90 
91 /// @struct ImageSamplingKeyHasher
92 /// Class used for hashing ImageSamplingProperties in an unordered_map
94 {
95  size_t operator()(const ImageSamplingProperties& k) const
96  {
97  return (size_t) k.enableMipmaps + // 1 bit
98  (((size_t) k.filterType & 3) << 1) + // 2 bit
99  ((((size_t) k.uaddressMode + 1) & 7) << 3) + // 3 bit
100  ((((size_t) k.vaddressMode + 1) & 7) << 6) + // 3 bit
101  ((((size_t) k.defaultColor[0] + 1)) << 9) ;
102  }
103 };
104 
105 /// @class ImageLoader
106 /// Abstract base class for file-system image loaders
108 {
109  public:
111  {
112  }
113  virtual ~ImageLoader() { }
114 
115  /// Standard image file extensions
116  static const string BMP_EXTENSION;
117  static const string EXR_EXTENSION;
118  static const string GIF_EXTENSION;
119  static const string HDR_EXTENSION;
120  static const string JPG_EXTENSION;
121  static const string JPEG_EXTENSION;
122  static const string PIC_EXTENSION;
123  static const string PNG_EXTENSION;
124  static const string PSD_EXTENSION;
125  static const string TGA_EXTENSION;
126  static const string TIF_EXTENSION;
127  static const string TIFF_EXTENSION;
128  static const string TXT_EXTENSION;
129  static const string TX_EXTENSION;
130  static const string TXR_EXTENSION;
131 
132  /// Returns a list of supported extensions
133  /// @return List of support extensions
135  {
136  return _extensions;
137  }
138 
139  /// Save an image to the file system. This method must be implemented by derived classes.
140  /// @param filePath File path to be written
141  /// @param image The image to be saved
142  /// @param verticalFlip Whether the image should be flipped in Y during save
143  /// @return if save succeeded
144  virtual bool saveImage(const FilePath& filePath,
146  bool verticalFlip = false);
147 
148  /// Load an image from the file system. This method must be implemented by derived classes.
149  /// @param filePath The requested image file path.
150  /// @return On success, a shared pointer to the loaded image; otherwise an empty shared pointer.
151  virtual ImagePtr loadImage(const FilePath& filePath);
152 
153  protected:
154  // List of supported string extensions
156 };
157 
158 /// @class ImageHandler
159 /// Base image handler class. Keeps track of images which are loaded from
160 /// disk via supplied ImageLoader. Derived classes are responsible for
161 /// determinining how to perform the logic for "binding" of these resources
162 /// for a given target (such as a given shading language).
164 {
165  public:
167  {
168  return ImageHandlerPtr(new ImageHandler(imageLoader));
169  }
170  virtual ~ImageHandler() { }
171 
172  /// Add another image loader to the handler, which will be invoked if
173  /// existing loaders cannot load a given image.
174  void addLoader(ImageLoaderPtr loader);
175 
176  /// Get a list of extensions supported by the handler.
177  StringSet supportedExtensions();
178 
179  /// Save image to disk. This method must be implemented by derived classes.
180  /// The first image loader which supports the file name extension will be used.
181  /// @param filePath File path to be written
182  /// @param image The image to be saved
183  /// @param verticalFlip Whether the image should be flipped in Y during save
184  /// @return if save succeeded
185  bool saveImage(const FilePath& filePath, ConstImagePtr image, bool verticalFlip = false);
186 
187  /// Acquire an image from the cache or file system. If the image is not
188  /// found in the cache, then each image loader will be applied in turn.
189  /// If the image cannot be found by any loader, then a uniform image of the
190  /// given default color will be returned.
191  /// @param filePath File path of the image.
192  /// @param defaultColor Default color to use as a fallback for missing images.
193  /// @return On success, a shared pointer to the acquired image.
194  ImagePtr acquireImage(const FilePath& filePath, const Color4& defaultColor = Color4(0.0f));
195 
196  /// Bind an image for rendering.
197  /// @param image The image to bind.
198  /// @param samplingProperties Sampling properties for the image.
199  virtual bool bindImage(ImagePtr image, const ImageSamplingProperties& samplingProperties);
200 
201  /// Unbind an image, making it no longer active for rendering.
202  /// @param image The image to unbind.
203  virtual bool unbindImage(ImagePtr image);
204 
205  /// Unbind all images that are currently stored in the cache.
206  void unbindImages();
207 
208  /// Set the search path to be used for finding images on the file system.
210  {
211  _searchPath = path;
212  }
213 
214  /// Return the image search path.
216  {
217  return _searchPath;
218  }
219 
220  /// Set the filename resolver for images.
222  {
223  _resolver = resolver;
224  }
225 
226  /// Return the filename resolver for images.
228  {
229  return _resolver;
230  }
231 
232  /// Create rendering resources for the given image.
233  virtual bool createRenderResources(ImagePtr image, bool generateMipMaps, bool useAsRenderTarget = false);
234 
235  /// Release rendering resources for the given image, or for all cached images
236  /// if no image pointer is specified.
237  virtual void releaseRenderResources(ImagePtr image = nullptr);
238 
239  /// Clear the contents of the image cache, first releasing any render
240  /// resources associated with cached images.
242  {
243  releaseRenderResources();
244  _imageCache.clear();
245  }
246 
247  /// Return a fallback image with zeroes in all channels.
249  {
250  return _zeroImage;
251  }
252 
253  /// Acquire all images referenced by the given document, and return the
254  /// images in a vector.
255  ImageVec getReferencedImages(ConstDocumentPtr doc);
256 
257  protected:
258  // Protected constructor.
259  ImageHandler(ImageLoaderPtr imageLoader);
260 
261  // Load an image from the file system.
262  ImagePtr loadImage(const FilePath& filePath);
263 
264  // Add an image to the cache.
265  void cacheImage(const string& filePath, ImagePtr image);
266 
267  // Return the cached image, if found; otherwise return an empty
268  // shared pointer.
269  ImagePtr getCachedImage(const FilePath& filePath);
270 
271  protected:
277 };
278 
280 
281 #endif
static const string TXT_EXTENSION
Definition: ImageHandler.h:128
#define CLAMP(EXPR, TYPE)
ImagePtr getZeroImage() const
Return a fallback image with zeroes in all channels.
Definition: ImageHandler.h:248
typedef int(APIENTRYP RE_PFNGLXSWAPINTERVALSGIPROC)(int)
static const string GIF_EXTENSION
Definition: ImageHandler.h:118
static const string EXR_EXTENSION
Definition: ImageHandler.h:117
Definition: File.h:26
std::unordered_map< string, ImagePtr > ImageMap
A map from strings to images.
Definition: Image.h:29
#define MATERIALX_NAMESPACE_BEGIN
Definition: Generated.h:25
StringResolverPtr _resolver
Definition: ImageHandler.h:275
StringResolverPtr getFilenameResolver() const
Return the filename resolver for images.
Definition: ImageHandler.h:227
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
std::vector< ImagePtr > ImageVec
A vetor of images.
Definition: Image.h:32
AddressMode vaddressMode
Address mode in V.
Definition: ImageHandler.h:68
static ImageHandlerPtr create(ImageLoaderPtr imageLoader)
Definition: ImageHandler.h:166
GLenum GLenum GLsizei void * image
Definition: glad.h:5132
Selectively extract and filter point data using a custom filter operator.
const FileSearchPath & getSearchPath() const
Return the image search path.
Definition: ImageHandler.h:215
static const string TIFF_EXTENSION
Definition: ImageHandler.h:127
std::unordered_map< string, std::vector< ImageLoaderPtr >> ImageLoaderMap
Map from strings to vectors of image loaders.
Definition: ImageHandler.h:38
MX_RENDER_API const string FILTER_TYPE_SUFFIX
OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER IMFUTIL_EXPORT void saveImage(const std::string &fileName, const Header &hdr, const Image &img, DataWindowSource dws=USE_IMAGE_DATA_WINDOW)
virtual ~ImageHandler()
Definition: ImageHandler.h:170
const StringSet & supportedExtensions() const
Definition: ImageHandler.h:134
static const string PIC_EXTENSION
Definition: ImageHandler.h:122
bool operator==(const BaseDimensions< T > &a, const BaseDimensions< Y > &b)
Definition: Dimensions.h:137
static const string PNG_EXTENSION
Definition: ImageHandler.h:123
static const string TGA_EXTENSION
Definition: ImageHandler.h:125
GLfloat f
Definition: glcorearb.h:1926
std::shared_ptr< ImageHandler > ImageHandlerPtr
Shared pointer to an ImageHandler.
Definition: ImageHandler.h:32
MATERIALX_NAMESPACE_BEGIN MX_RENDER_API const string IMAGE_PROPERTY_SEPARATOR
static const string JPEG_EXTENSION
Definition: ImageHandler.h:121
std::shared_ptr< ImageLoader > ImageLoaderPtr
Shared pointer to an ImageLoader.
Definition: ImageHandler.h:35
void setSearchPath(const FileSearchPath &path)
Set the search path to be used for finding images on the file system.
Definition: ImageHandler.h:209
MX_RENDER_API const string VADDRESS_MODE_SUFFIX
size_t operator()(const ImageSamplingProperties &k) const
Definition: ImageHandler.h:95
AddressMode uaddressMode
Address mode in U.
Definition: ImageHandler.h:66
static const string TX_EXTENSION
Definition: ImageHandler.h:129
ImagePtr _zeroImage
Definition: ImageHandler.h:276
shared_ptr< StringResolver > StringResolverPtr
A shared pointer to a StringResolver.
Definition: Element.h:66
MX_RENDER_API const string UADDRESS_MODE_SUFFIX
#define MX_RENDER_API
Definition: Export.h:18
ImageMap _imageCache
Definition: ImageHandler.h:273
static const string TIF_EXTENSION
Definition: ImageHandler.h:126
static const string TXR_EXTENSION
Definition: ImageHandler.h:130
FileSearchPath _searchPath
Definition: ImageHandler.h:274
ImageLoaderMap _imageLoaders
Definition: ImageHandler.h:272
std::set< string > StringSet
A set of strings.
Definition: Library.h:61
FilterType filterType
Filter type.
Definition: ImageHandler.h:81
#define MATERIALX_NAMESPACE_END
Definition: Generated.h:26
GLboolean r
Definition: glcorearb.h:1222
void clearImageCache()
Definition: ImageHandler.h:241
static const string JPG_EXTENSION
Definition: ImageHandler.h:120
shared_ptr< Image > ImagePtr
A shared pointer to an image.
Definition: Image.h:23
static const string HDR_EXTENSION
Definition: ImageHandler.h:119
static const string PSD_EXTENSION
Definition: ImageHandler.h:124
StringSet _extensions
Definition: ImageHandler.h:155
shared_ptr< const Document > ConstDocumentPtr
A shared pointer to a const Document.
Definition: Document.h:24
void setFilenameResolver(StringResolverPtr resolver)
Set the filename resolver for images.
Definition: ImageHandler.h:221
static const string BMP_EXTENSION
Standard image file extensions.
Definition: ImageHandler.h:116
shared_ptr< const Image > ConstImagePtr
A shared pointer to a const image.
Definition: Image.h:26
bool enableMipmaps
Enable mipmaps.
Definition: ImageHandler.h:84
MX_RENDER_API const string DEFAULT_COLOR_SUFFIX
virtual ~ImageLoader()
Definition: ImageHandler.h:113
IMFUTIL_EXPORT Image * loadImage(const std::string &fileName, Header &hdr)