RV_TextureCache.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        RV_TextureCache.h (RV Library, C++)
 *
 * COMMENTS:
 */
#ifndef RV_TextureCache_h
#define RV_TextureCache_h

#include "RV_API.h"
#include "RV_Type.h"
#include "RV_VKImage.h"

#include <PXL/PXL_Raster.h>
#include <UT/UT_Array.h>
#include <UT/UT_Cache.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Map.h>
#include <UT/UT_MemoryResource.h>
#include <UT/UT_Set.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_VectorTypes.h>

#include <SYS/SYS_Types.h>

#define RV_INVALID_OP_ID -1

typedef void (*RV_TextureHDAResolverCB)(const char *optable_optype,
                                        const char *pattern,
                                        UT_StringArray &files);

class RV_Render;
class RV_ShaderVariableSet;
class RV_TextureResolver;
class RV_Instance;

class PXL_Raster;
class IMG_Stat;

/// Global cache of vulkan textures sourced from files.
class RV_API RV_TextureCache : public UT_Cache
{
public:
    /// Initialize the cache (only used by the system during startup)
    static void        init(const UT_StringHolder &device_name);
    /// Destroy the cache (only used by the system during exit)
    static void        cleanup();

    /// Clear all images out of the cache.
    static void        clear();
    /// Mark any textures as dirty if their file source has been modified
    static void        updateTextures();

    /// The serial version of the cache. Incremented when a texture is added
    static exint       cacheVersion();
    /// The serial refresh count of the cache. Incremented when the user 
    /// explicity updates the textures
    static exint       cacheRefresh();

    static exint       currentSizeBytes();

    static exint       totalTextureCount();

    static exint       freeSomeMem(exint mem_in_bytes);

    /// If the texture is missing, one of these generic placeholders is used.
    enum PlaceholderType
    {
        MISSING_BLACK_CLEAR, // 0,0,0,0
        MISSING_BLACK_SOLID, // 0,0,0,1
        MISSING_WHITE_SOLID, // 1,1,1,1
        MISSING_RED_SOLID,   // 1,0,0,1
        MISSING_NORMAL_MAP,  // 0.5, 0.5, 1, 0
        MISSING_FALLBACK,    // custom color
        
        MAX_PLACEHOLDER
    };

    enum TexturePriority
    {
        PRIORITY_UNUSED,
        PRIORITY_LOW,
        PRIORITY_NORMAL,
        PRIORITY_HIGH,
        PRIORITY_CRITICAL
    };

    /// Load the map (if needed) and bind the resulting texture to 'sampler_name'
    /// in 'set'. If it cannot be loaded, bind a placeholder texture instead.
    /// This method is equivalent to calling loadTextureRef() and then
    /// bindTextureRef() or bindPlaceholder(). If the map is a reference to a
    /// mofr with op:, op_id will contain its unique ID.
    static bool        bindTexture(RV_Render *r,
                                   RV_TextureRef &map,
                                   const RV_TextureParms &map_parms,
                                   const UT_StringHolder &map_name,
                                   const UT_StringHolder &relative_to_node,
                                   RV_ImageDim tex_type,
                                   RV_ShaderVariableSet *set,
                                   const UT_StringHolder &sampler_name,
                                   bool deferred_load,
                                   bool &deferred_loaded,
                                   int &op_id,
                                   TexturePriority priority = PRIORITY_NORMAL,
                                   PlaceholderType missing=MISSING_WHITE_SOLID,
                                   UT_Vector4F *fallback_color = nullptr);

    /// Binds an existing texture ref to the set at 'sampler_name'. It should not
    /// be a placeholder image (use bindPlaceholder instead). 
    static bool        bindTextureRef(RV_Render *r,
                                      RV_TextureRef &ref,
                                      RV_ShaderVariableSet *set,
                                      const UT_StringHolder &sampler_name);

    /// Bind a small placeholder texture (1x1) to 'sampler_name' in 'set'.
    /// The RGBA texture color is defined by the placeholder_type, or can be a
    /// custom/ color if the type is FALLBACK. The texture is 8b unorm RGBA.
    static bool        bindPlaceholder(RV_Render *r,
                                       RV_ImageDim tex_type,
                                       RV_ShaderVariableSet *set,
                                       const UT_StringHolder &sampler_name,
                                       PlaceholderType placeholder_type,
                                       const UT_Vector4F *fallbackcolor=nullptr);

    /// Load the map info a texture ref without binding it to a shader. If the
    /// map could not be loaded, map.isPlaceholder() will be true.
    /// If allow_deferred_load is true, background load the texture. Keep calling
    /// this in subsequent redraws until defer_load_finished is true.
    static bool        loadTextureRef(RV_Render *r,
                                      RV_TextureRef &map,
                                      const RV_TextureParms &map_parms,
                                      const UT_StringHolder &map_name,
                                      const UT_StringHolder &relative_to_node,
                                      RV_ImageDim tex_type,
                                      bool allow_deferred_load,
                                      bool &defer_load_finished,
                                      int &op_id,
                                      TexturePriority priority = PRIORITY_NORMAL,
                                      UT_Vector3i *resolution = nullptr,
                                      UT_Vector4F *fallback_color = nullptr);
    
    /// Cache an existing 2D Image. The name should be prefixed with exp:
    /// (explicitly cached).
    static bool         cacheAsTexture(RV_Render *r,
                                       RV_TextureRef &map,
                                       const PXL_Raster *source_image,
                                       const RV_TextureParms &map_parms,
                                       const UT_StringHolder &map_name);
    /// Remove a cached 2D Image
    static bool         removeCachedTexture(RV_TextureRef &map);

    /// Cache an existing image. The cache takes ownership (use std::move for
    /// the image). If the image is a UDIM, you can optionally pass the bounds.
    /// The map name should be prefixed with exp:  (explicitly cached). 
    static bool         cacheImage(UT_UniquePtr<RV_VKImage> image,
                                   RV_TextureRef &map,
                                   const UT_StringHolder &map_name,
                                   UT_DimRect *udim_bounds = nullptr);
    /// Remove a cached image from the cache, taking ownership of it.
    /// If udim_bounds is not null, write the bounds to it.
    static UT_UniquePtr<RV_VKImage>
                        uncacheImage(RV_TextureRef &map,
                                     UT_DimRect *udim_bounds = nullptr);
                                   

    /// Check if the texture is out of date. Flag the ref and set `dirty` if so.
    /// doesn't touch either if it's current.
    static void  checkTextureDirty(RV_TextureRef &map, bool &dirty);

    /// Check if the texture has an alpha channel
    static void  checkTextureHasAlpha(const RV_TextureRef &ref, bool &has_alpha);

    /// For resolving a bunch of files to a 2D array, this is the separator
    /// character between the filenames.
    static const char * getFileSeparator() { return "\x1f"; }

    static void setSingleTexMemLimitMB(exint mem_in_mb);
    static exint singleTexMemLimitMB();

    static void setCacheSize(exint mem_in_bytes);

    /// Reduce all textures in the cache by at least this amount.
    static void setReductionFactor(fpreal reduce);

    /// For resolving 
    static void installHDACallback(RV_TextureHDAResolverCB resolver_func);

    /// @internal
    class RV_API ImageInfo : public UT_NonCopyable
    {
    public:
        ImageInfo();
        ~ImageInfo();
        
        UT_StringHolder map_name;
        UT_StringHolder op_relative;
        UT_StringHolder cache_name;
        UT_UniquePtr<RV_VKImage> image;
        UT_Array<UT_UniquePtr<PXL_Raster>> rasters;
        UT_SharedPtr<RV_TextureRef::CacheData> refs;
        UT_UniquePtr<IMG_Stat> stat;
        int udim_x = 0;
        int udim_y = 0;
        int udim_w = 0;
        int udim_h = 0;
        int width = 1;
        int height = 1;
        int depth = 1;
        bool check_alpha = false;
        bool alpha = false;
        time_t modtime = 0;
        fpreal optime = 0.0;
        int op_id = RV_INVALID_OP_ID;
        int version = 0;
        bool valid = false;
        bool loading = false;
        fpreal downscale = 1.0;
    };

protected:
    class Image
    {
    public:
        RV_VKImage *image = nullptr;
        int udim_x = 0;
        int udim_y = 0;
        int udim_w = 0;
        int udim_h = 0;
        int op_id  = RV_INVALID_OP_ID;
    };

    static RV_TextureCache::Image getTexture(exint id);
    
    exint  resolveTexture(RV_Render *r,
                          const UT_StringHolder &map_name,
                          const UT_StringHolder &relative_to_node,
                          const RV_TextureParms &tex_parms,
                          RV_ImageDim tex_type,
                          bool force_update,
                          bool deferred_load,
                          bool &defer_loaded,
                          int &op_id,
                          bool &missing_texture,
                          UT_SharedPtr<RV_TextureRef::CacheData> &ref,
                          TexturePriority priority,
                          const UT_Vector4F &fallback,
                          UT_Vector3i *resolution);

    static RV_VKImage *getPlaceholder(RV_Render *r, RV_ImageDim tex_type,
                                      PlaceholderType type =MISSING_WHITE_SOLID,
                                      const UT_Vector4F *fallbackcolor =nullptr);

    RV_TextureCache::Image privGetTexture(exint id);

             RV_TextureCache(const UT_StringHolder &name);
            ~RV_TextureCache() override;

    UT_NON_COPYABLE(RV_TextureCache)

    // UT_Cache interface
    const char *utGetCacheName() const override
                    { return "Vulkan Texture Cache"; }
    int64       utGetCurrentSize() const override
                    { return myCurrentSize; }
    int64       utReduceCacheSizeBy(int64 amount) override
                    { return freeTextures(amount, true, false); }
    bool        utHasMaxSize() const override { return true; }
    int64       utGetMaxSize() const override;
    void        utSetMaxSize(int64) override { }

        
private:

    exint freeTextures(exint needed_to_free, bool free_used, bool must_free);
    exint cachedSizeBytes() const;

    class GraphicsMemoryClient : public UT_MemoryClient
    {
    public:
        GraphicsMemoryClient(RV_TextureCache &cache) : myCache(cache) {}
        
        const char *name() const override
                        { return "Vulkan Texture Cache";}

        bool freeMemoryRequest(const UT_MemoryResource *resource,
                               RequestSeverity severity,
                               Niceness nice_level,
                               exint size_in_bytes,
                               exint &freed_amount_in_bytes) override;
        bool memoryUse(const UT_MemoryResource *resource,
                       exint &in_use_bytes,
                       exint &cached_bytes) override;
        
        ~GraphicsMemoryClient() override {}
        UT_NON_COPYABLE(GraphicsMemoryClient)
        
    private:
        RV_TextureCache &myCache;
    };

    GraphicsMemoryClient                  myResource;
    UT_Array< UT_Map<exint, ImageInfo > > myImages;
    UT_Map<exint, RV_ImageDim>            myTypeMap;

    struct ResolveEntry
    {
        exint id = 0;
        TexturePriority priority = RV_TextureCache::PRIORITY_NORMAL;
        UT_SharedPtr<RV_TextureRef::CacheData> refs;
    };
    UT_StringMap<ResolveEntry>            myResolveMap;
    UT_StringMap<fpreal>                  myReductionTable;

    UT_Array<UT_UniquePtr<RV_TextureResolver>>  myResolvers;
    UT_Array<UT_UniquePtr<RV_VKImage>>          myPlaceholders;
    UT_Array<UT_Map<int32, RV_VKImagePtr>>      myFallbackTextures;
    UT_Lock                                     myLock;
    UT_Set<exint>                               myDeferImages;
    
    exint             myCurrentSize = 0;
    fpreal            myReductionFactor = 1.0;
    UT_StringHolder   myDeviceName;
};

#endif