ImageHandler.h

Go to the documentation of this file.

//
// Copyright Contributors to the MaterialX Project
// SPDX-License-Identifier: Apache-2.0
//
 
#ifndef MATERIALX_IMAGEHANDLER_H
#define MATERIALX_IMAGEHANDLER_H

 
#include <MaterialXRender/Export.h>
#include <MaterialXRender/Image.h>
 
#include <MaterialXFormat/File.h>
 
#include <MaterialXCore/Document.h>
 
MATERIALX_NAMESPACE_BEGIN
 
extern MX_RENDER_API const string IMAGE_PROPERTY_SEPARATOR;
extern MX_RENDER_API const string UADDRESS_MODE_SUFFIX;
extern MX_RENDER_API const string VADDRESS_MODE_SUFFIX;
extern MX_RENDER_API const string FILTER_TYPE_SUFFIX;
extern MX_RENDER_API const string DEFAULT_COLOR_SUFFIX;
 
class ImageHandler;
class ImageLoader;
class VariableBlock;

using ImageHandlerPtr = std::shared_ptr<ImageHandler>;

using ImageLoaderPtr = std::shared_ptr<ImageLoader>;

using ImageLoaderMap = std::unordered_map<string, std::vector<ImageLoaderPtr>>;

class MX_RENDER_API ImageSamplingProperties
{
  public:
    void setProperties(const string& fileNameUniform,
                       const VariableBlock& uniformBlock);
 
    bool operator==(const ImageSamplingProperties& r) const;

    enum class AddressMode : int
    {
        UNSPECIFIED = -1,
        CONSTANT = 0,
        CLAMP = 1,
        PERIODIC = 2,
        MIRROR = 3
    };

    AddressMode uaddressMode = AddressMode::UNSPECIFIED;
    AddressMode vaddressMode = AddressMode::UNSPECIFIED;

    enum class FilterType : int
    {
        UNSPECIFIED = -1,
        CLOSEST = 0,
        LINEAR = 1,
        CUBIC = 2
    };

    FilterType filterType = FilterType::UNSPECIFIED;

    bool enableMipmaps = true;

    Color4 defaultColor = { 0.0f, 0.0f, 0.0f, 1.0f };
};

struct MX_RENDER_API ImageSamplingKeyHasher
{
    size_t operator()(const ImageSamplingProperties& k) const
    {
        return (size_t) k.enableMipmaps                   + // 1 bit
               (((size_t) k.filterType         & 3) << 1) + // 2 bit
               ((((size_t) k.uaddressMode + 1) & 7) << 3) + // 3 bit
               ((((size_t) k.vaddressMode + 1) & 7) << 6) + // 3 bit
               ((((size_t) k.defaultColor[0] + 1))  << 9) ;
    }
};

class MX_RENDER_API ImageLoader
{
  public:
    ImageLoader()
    {
    }
    virtual ~ImageLoader() { }

    static const string BMP_EXTENSION;
    static const string EXR_EXTENSION;
    static const string GIF_EXTENSION;
    static const string HDR_EXTENSION;
    static const string JPG_EXTENSION;
    static const string JPEG_EXTENSION;
    static const string PIC_EXTENSION;
    static const string PNG_EXTENSION;
    static const string PSD_EXTENSION;
    static const string TGA_EXTENSION;
    static const string TIF_EXTENSION;
    static const string TIFF_EXTENSION;
    static const string TXT_EXTENSION;
    static const string TX_EXTENSION;
    static const string TXR_EXTENSION;

    const StringSet& supportedExtensions() const
    {
        return _extensions;
    }

    virtual bool saveImage(const FilePath& filePath,
                           ConstImagePtr image,
                           bool verticalFlip = false);

    virtual ImagePtr loadImage(const FilePath& filePath);
 
  protected:
    // List of supported string extensions
    StringSet _extensions;
};

class MX_RENDER_API ImageHandler
{
  public:
    static ImageHandlerPtr create(ImageLoaderPtr imageLoader)
    {
        return ImageHandlerPtr(new ImageHandler(imageLoader));
    }
    virtual ~ImageHandler() { }

    void addLoader(ImageLoaderPtr loader);

    StringSet supportedExtensions();

    bool saveImage(const FilePath& filePath, ConstImagePtr image, bool verticalFlip = false);

    ImagePtr acquireImage(const FilePath& filePath, const Color4& defaultColor = Color4(0.0f));

    virtual bool bindImage(ImagePtr image, const ImageSamplingProperties& samplingProperties);

    virtual bool unbindImage(ImagePtr image);

    void unbindImages();

    void setSearchPath(const FileSearchPath& path)
    {
        _searchPath = path;
    }

    const FileSearchPath& getSearchPath() const
    {
        return _searchPath;
    }

    void setFilenameResolver(StringResolverPtr resolver)
    {
        _resolver = resolver;
    }

    StringResolverPtr getFilenameResolver() const
    {
        return _resolver;
    }

    virtual bool createRenderResources(ImagePtr image, bool generateMipMaps, bool useAsRenderTarget = false);

    virtual void releaseRenderResources(ImagePtr image = nullptr);

    void clearImageCache()
    {
        releaseRenderResources();
        _imageCache.clear();
    }

    ImagePtr getZeroImage() const
    {
        return _zeroImage;
    }

    ImageVec getReferencedImages(ConstDocumentPtr doc);
 
  protected:
    // Protected constructor.
    ImageHandler(ImageLoaderPtr imageLoader);
 
    // Load an image from the file system.
    ImagePtr loadImage(const FilePath& filePath);
 
    // Add an image to the cache.
    void cacheImage(const string& filePath, ImagePtr image);
 
    // Return the cached image, if found; otherwise return an empty
    // shared pointer.
    ImagePtr getCachedImage(const FilePath& filePath);
 
  protected:
    ImageLoaderMap _imageLoaders;
    ImageMap _imageCache;
    FileSearchPath _searchPath;
    StringResolverPtr _resolver;
    ImagePtr _zeroImage;
};
 
MATERIALX_NAMESPACE_END
 
#endif