MaterialX 1.38.2
ImageHandler.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_IMAGEHANDLER_H
7#define MATERIALX_IMAGEHANDLER_H
8
11
14
16
18
19namespace MaterialX
20{
21
22extern MX_RENDER_API const string IMAGE_PROPERTY_SEPARATOR;
23extern MX_RENDER_API const string UADDRESS_MODE_SUFFIX;
24extern MX_RENDER_API const string VADDRESS_MODE_SUFFIX;
25extern MX_RENDER_API const string FILTER_TYPE_SUFFIX;
26extern MX_RENDER_API const string DEFAULT_COLOR_SUFFIX;
27
28class ImageHandler;
29class ImageLoader;
30class VariableBlock;
31
33using ImageHandlerPtr = std::shared_ptr<ImageHandler>;
34
36using ImageLoaderPtr = std::shared_ptr<ImageLoader>;
37
39using ImageLoaderMap = std::unordered_map< string, std::vector<ImageLoaderPtr> >;
40
43class MX_RENDER_API ImageSamplingProperties
44{
45 public:
50 void setProperties(const string& fileNameUniform,
51 const VariableBlock& uniformBlock);
52
55 enum class AddressMode : int
56 {
57 UNSPECIFIED = -1,
58 CONSTANT = 0,
59 CLAMP = 1,
60 PERIODIC = 2,
61 MIRROR = 3
62 };
63
65 AddressMode uaddressMode = AddressMode::UNSPECIFIED;
67 AddressMode vaddressMode = AddressMode::UNSPECIFIED;
68
71 enum class FilterType : int
72 {
73 UNSPECIFIED = -1,
74 CLOSEST = 0,
75 LINEAR = 1,
76 CUBIC = 2
77 };
78
80 FilterType filterType = FilterType::UNSPECIFIED;
81
83 bool enableMipmaps = true;
84
87 Color4 defaultColor = { 0.0f, 0.0f, 0.0f, 1.0f };
88};
89
92class MX_RENDER_API ImageLoader
93{
94 public:
96 {
97 }
98 virtual ~ImageLoader() { }
99
101 static const string BMP_EXTENSION;
102 static const string EXR_EXTENSION;
103 static const string GIF_EXTENSION;
104 static const string HDR_EXTENSION;
105 static const string JPG_EXTENSION;
106 static const string JPEG_EXTENSION;
107 static const string PIC_EXTENSION;
108 static const string PNG_EXTENSION;
109 static const string PSD_EXTENSION;
110 static const string TGA_EXTENSION;
111 static const string TIF_EXTENSION;
112 static const string TIFF_EXTENSION;
113 static const string TXT_EXTENSION;
114 static const string TX_EXTENSION;
115 static const string TXR_EXTENSION;
116
120 {
121 return _extensions;
122 }
123
129 virtual bool saveImage(const FilePath& filePath,
130 ConstImagePtr image,
131 bool verticalFlip = false);
132
136 virtual ImagePtr loadImage(const FilePath& filePath);
137
138 protected:
139 // List of supported string extensions
140 StringSet _extensions;
141};
142
148class MX_RENDER_API ImageHandler
149{
150 public:
151 static ImageHandlerPtr create(ImageLoaderPtr imageLoader)
152 {
153 return ImageHandlerPtr(new ImageHandler(imageLoader));
154 }
155 virtual ~ImageHandler() { }
156
159 void addLoader(ImageLoaderPtr loader);
160
162 StringSet supportedExtensions();
163
170 bool saveImage(const FilePath& filePath, ConstImagePtr image, bool verticalFlip = false);
171
176 ImagePtr acquireImage(const FilePath& filePath);
177
181 virtual bool bindImage(ImagePtr image, const ImageSamplingProperties& samplingProperties);
182
185 virtual bool unbindImage(ImagePtr image);
186
188 void unbindImages();
189
192 {
193 _searchPath = path;
194 }
195
198 {
199 return _searchPath;
200 }
201
204 {
205 _resolver = resolver;
206 }
207
210 {
211 return _resolver;
212 }
213
215 virtual bool createRenderResources(ImagePtr image, bool generateMipMaps);
216
219 virtual void releaseRenderResources(ImagePtr image = nullptr);
220
224 {
225 releaseRenderResources();
226 _imageCache.clear();
227 }
228
231 {
232 return _zeroImage;
233 }
234
238 {
239 return _invalidImage;
240 }
241
244 ImageVec getReferencedImages(DocumentPtr doc);
245
246 protected:
247 // Protected constructor.
248 ImageHandler(ImageLoaderPtr imageLoader);
249
250 // Load an image from the file system.
251 ImagePtr loadImage(const FilePath& filePath);
252
253 // Add an image to the cache.
254 void cacheImage(const string& filePath, ImagePtr image);
255
256 // Return the cached image, if found; otherwise return an empty
257 // shared pointer.
258 ImagePtr getCachedImage(const FilePath& filePath);
259
260 protected:
261 ImageLoaderMap _imageLoaders;
262 ImageMap _imageCache;
263 FileSearchPath _searchPath;
264 StringResolverPtr _resolver;
265 ImagePtr _zeroImage;
266 ImagePtr _invalidImage;
267};
268
269} // namespace MaterialX
270
271#endif
The top-level Document class.
shared_ptr< Document > DocumentPtr
A shared pointer to a Document.
Definition: Document.h:23
shared_ptr< StringResolver > StringResolverPtr
A shared pointer to a StringResolver.
Definition: Element.h:61
Cross-platform support for file and search paths.
Image class.
shared_ptr< const Image > ConstImagePtr
A shared pointer to a const image.
Definition: Image.h:27
std::vector< ImagePtr > ImageVec
A vetor of images.
Definition: Image.h:33
std::unordered_map< string, ImagePtr > ImageMap
A map from strings to images.
Definition: Image.h:30
shared_ptr< Image > ImagePtr
A shared pointer to an image.
Definition: Image.h:24
std::shared_ptr< ImageLoader > ImageLoaderPtr
Shared pointer to an ImageLoader.
Definition: ImageHandler.h:36
std::shared_ptr< ImageHandler > ImageHandlerPtr
Shared pointer to an ImageHandler.
Definition: ImageHandler.h:33
std::unordered_map< string, std::vector< ImageLoaderPtr > > ImageLoaderMap
Map from strings to vectors of image loaders.
Definition: ImageHandler.h:39
std::set< string > StringSet
A set of strings.
Definition: Library.h:60
Macros for declaring imported and exported symbols.
A four-component color value.
Definition: Types.h:389
A generic file path, supporting both syntactic and file system operations.
Definition: File.h:28
A sequence of file paths, which may be queried to find the first instance of a given filename on the ...
Definition: File.h:213
Base image handler class.
Definition: ImageHandler.h:149
void clearImageCache()
Clear the contents of the image cache, first releasing any render resources associated with cached im...
Definition: ImageHandler.h:223
const FileSearchPath & getSearchPath() const
Return the image search path.
Definition: ImageHandler.h:197
StringResolverPtr getFilenameResolver() const
Return the filename resolver for images.
Definition: ImageHandler.h:209
void setSearchPath(const FileSearchPath &path)
Set the search path to be used for finding images on the file system.
Definition: ImageHandler.h:191
ImagePtr getInvalidImage() const
Return the sentinel invalid image, representing images that cannot be loaded and should be replaced w...
Definition: ImageHandler.h:237
ImagePtr getZeroImage() const
Return a fallback image with zeroes in all channels.
Definition: ImageHandler.h:230
void setFilenameResolver(StringResolverPtr resolver)
Set the filename resolver for images.
Definition: ImageHandler.h:203
Abstract base class for file-system image loaders.
Definition: ImageHandler.h:93
const StringSet & supportedExtensions() const
Returns a list of supported extensions.
Definition: ImageHandler.h:119
static const string BMP_EXTENSION
Standard image file extensions.
Definition: ImageHandler.h:101
Interface to describe sampling properties for images.
Definition: ImageHandler.h:44
FilterType
Filter type options.
Definition: ImageHandler.h:72
AddressMode
Address mode options.
Definition: ImageHandler.h:56
A block of variables in a shader stage.
Definition: ShaderStage.h:53