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_NonCopyable.h>
#include <UT/UT_Map.h>
#include <UT/UT_StringMap.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;

/// Global cache of vulkan textures sourced from files.
class RV_API RV_TextureCache : public UT_NonCopyable
{
public:
    /// Initialize the cache (only used by the system during startup)
    static void        init();
    /// 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();

    /// 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
    };

    /// 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,
                                   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,
                                      UT_Vector3i *resolution = 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"; }

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

    /// @internal
    class RV_API ImageInfo : public UT_NonCopyable
    {
    public:
        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;
        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;
    };

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_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);
    
    virtual ~RV_TextureCache();

private:

    UT_Array< UT_Map<exint, ImageInfo > > myImages;
    UT_Map<exint, RV_ImageDim>            myTypeMap;
    UT_StringMap<exint>                   myResolveMap;

    UT_Array< RV_TextureResolver *>       myResolvers;
    UT_Array< UT_UniquePtr<RV_VKImage> >  myPlaceholders;
    UT_Array< UT_Map<int32, RV_VKImagePtr > >  myFallbackTextures;
    
    exint             myCurrentSize = 0;
    //TODO:
    //exint             myMaxSize = 0;
};

#endif