HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
RV_TextureCache.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: RV_TextureCache.h (RV Library, C++)
7  *
8  * COMMENTS:
9  */
10 #ifndef RV_TextureCache_h
11 #define RV_TextureCache_h
12 
13 #include "RV_API.h"
14 #include "RV_Type.h"
15 #include "RV_VKImage.h"
16 
17 #include <PXL/PXL_Raster.h>
18 #include <UT/UT_Array.h>
19 #include <UT/UT_Cache.h>
20 #include <UT/UT_NonCopyable.h>
21 #include <UT/UT_Map.h>
22 #include <UT/UT_MemoryResource.h>
23 #include <UT/UT_Set.h>
24 #include <UT/UT_StringMap.h>
25 #include <UT/UT_StringHolder.h>
26 #include <UT/UT_UniquePtr.h>
27 #include <UT/UT_VectorTypes.h>
28 
29 #include <SYS/SYS_Types.h>
30 
31 #define RV_INVALID_OP_ID -1
32 
33 typedef void (*RV_TextureHDAResolverCB)(const char *optable_optype,
34  const char *pattern,
35  UT_StringArray &files);
36 
37 class RV_Render;
39 class RV_TextureResolver;
40 class RV_Instance;
41 
42 class PXL_Raster;
43 class IMG_Stat;
44 
45 /// Global cache of vulkan textures sourced from files.
47 {
48 public:
49  /// Initialize the cache (only used by the system during startup)
50  static void init(const UT_StringHolder &device_name);
51  /// Destroy the cache (only used by the system during exit)
52  static void cleanup();
53 
54  /// Clear all images out of the cache.
55  static void clear();
56  /// Mark any textures as dirty if their file source has been modified
57  static void updateTextures();
58 
59  /// The serial version of the cache. Incremented when a texture is added
60  static exint cacheVersion();
61  /// The serial refresh count of the cache. Incremented when the user
62  /// explicity updates the textures
63  static exint cacheRefresh();
64 
65  static exint currentSizeBytes();
66 
67  static exint totalTextureCount();
68 
69  static exint freeSomeMem(exint mem_in_bytes);
70 
71  /// If the texture is missing, one of these generic placeholders is used.
73  {
74  MISSING_BLACK_CLEAR, // 0,0,0,0
75  MISSING_BLACK_SOLID, // 0,0,0,1
76  MISSING_WHITE_SOLID, // 1,1,1,1
77  MISSING_RED_SOLID, // 1,0,0,1
78  MISSING_NORMAL_MAP, // 0.5, 0.5, 1, 0
79  MISSING_FALLBACK, // custom color
80 
81  MAX_PLACEHOLDER
82  };
83 
85  {
90  PRIORITY_CRITICAL
91  };
92 
93  /// Load the map (if needed) and bind the resulting texture to 'sampler_name'
94  /// in 'set'. If it cannot be loaded, bind a placeholder texture instead.
95  /// This method is equivalent to calling loadTextureRef() and then
96  /// bindTextureRef() or bindPlaceholder(). If the map is a reference to a
97  /// mofr with op:, op_id will contain its unique ID.
98  static bool bindTexture(RV_Render *r,
99  RV_TextureRef &map,
100  const RV_TextureParms &map_parms,
101  const UT_StringHolder &map_name,
102  const UT_StringHolder &relative_to_node,
103  RV_ImageDim tex_type,
105  const UT_StringHolder &sampler_name,
106  bool deferred_load,
107  bool &deferred_loaded,
108  int &op_id,
109  TexturePriority priority = PRIORITY_NORMAL,
110  PlaceholderType missing=MISSING_WHITE_SOLID,
111  UT_Vector4F *fallback_color = nullptr);
112 
113  /// Binds an existing texture ref to the set at 'sampler_name'. It should not
114  /// be a placeholder image (use bindPlaceholder instead).
115  static bool bindTextureRef(RV_Render *r,
118  const UT_StringHolder &sampler_name);
119 
120  /// Bind a small placeholder texture (1x1) to 'sampler_name' in 'set'.
121  /// The RGBA texture color is defined by the placeholder_type, or can be a
122  /// custom/ color if the type is FALLBACK. The texture is 8b unorm RGBA.
123  static bool bindPlaceholder(RV_Render *r,
124  RV_ImageDim tex_type,
126  const UT_StringHolder &sampler_name,
127  PlaceholderType placeholder_type,
128  const UT_Vector4F *fallbackcolor=nullptr);
129 
130  /// Load the map info a texture ref without binding it to a shader. If the
131  /// map could not be loaded, map.isPlaceholder() will be true.
132  /// If allow_deferred_load is true, background load the texture. Keep calling
133  /// this in subsequent redraws until defer_load_finished is true.
134  static bool loadTextureRef(RV_Render *r,
135  RV_TextureRef &map,
136  const RV_TextureParms &map_parms,
137  const UT_StringHolder &map_name,
138  const UT_StringHolder &relative_to_node,
139  RV_ImageDim tex_type,
140  bool allow_deferred_load,
141  bool &defer_load_finished,
142  int &op_id,
143  TexturePriority priority = PRIORITY_NORMAL,
144  UT_Vector3i *resolution = nullptr);
145 
146  /// Cache an existing 2D Image. The name should be prefixed with exp:
147  /// (explicitly cached).
148  static bool cacheAsTexture(RV_Render *r,
149  RV_TextureRef &map,
150  const PXL_Raster *source_image,
151  const RV_TextureParms &map_parms,
152  const UT_StringHolder &map_name);
153  /// Remove a cached 2D Image
154  static bool removeCachedTexture(RV_TextureRef &map);
155 
156  /// Cache an existing image. The cache takes ownership (use std::move for
157  /// the image). If the image is a UDIM, you can optionally pass the bounds.
158  /// The map name should be prefixed with exp: (explicitly cached).
159  static bool cacheImage(UT_UniquePtr<RV_VKImage> image,
160  RV_TextureRef &map,
161  const UT_StringHolder &map_name,
162  UT_DimRect *udim_bounds = nullptr);
163  /// Remove a cached image from the cache, taking ownership of it.
164  /// If udim_bounds is not null, write the bounds to it.
166  uncacheImage(RV_TextureRef &map,
167  UT_DimRect *udim_bounds = nullptr);
168 
169 
170  /// Check if the texture is out of date. Flag the ref and set `dirty` if so.
171  /// doesn't touch either if it's current.
172  static void checkTextureDirty(RV_TextureRef &map, bool &dirty);
173 
174  /// Check if the texture has an alpha channel
175  static void checkTextureHasAlpha(const RV_TextureRef &ref, bool &has_alpha);
176 
177  /// For resolving a bunch of files to a 2D array, this is the separator
178  /// character between the filenames.
179  static const char * getFileSeparator() { return "\x1f"; }
180 
181  static void setSingleTexMemLimitMB(exint mem_in_mb);
182  static exint singleTexMemLimitMB();
183 
184  static void setCacheSize(exint mem_in_bytes);
185 
186  /// Reduce all textures in the cache by at least this amount.
187  static void setReductionFactor(fpreal reduce);
188 
189  /// For resolving
190  static void installHDACallback(RV_TextureHDAResolverCB resolver_func);
191 
192  /// @internal
194  {
195  public:
196  ImageInfo();
197  ~ImageInfo();
198 
206  int udim_x = 0;
207  int udim_y = 0;
208  int udim_w = 0;
209  int udim_h = 0;
210  int width = 1;
211  int height = 1;
212  int depth = 1;
213  bool check_alpha = false;
214  bool alpha = false;
215  time_t modtime = 0;
216  fpreal optime = 0.0;
217  int op_id = RV_INVALID_OP_ID;
218  int version = 0;
219  bool valid = false;
220  bool loading = false;
221  fpreal downscale = 1.0;
222  };
223 
224 protected:
225  class Image
226  {
227  public:
228  RV_VKImage *image = nullptr;
229  int udim_x = 0;
230  int udim_y = 0;
231  int udim_w = 0;
232  int udim_h = 0;
233  int op_id = RV_INVALID_OP_ID;
234  };
235 
236  static RV_TextureCache::Image getTexture(exint id);
237 
238  exint resolveTexture(RV_Render *r,
239  const UT_StringHolder &map_name,
240  const UT_StringHolder &relative_to_node,
241  const RV_TextureParms &tex_parms,
242  RV_ImageDim tex_type,
243  bool force_update,
244  bool deferred_load,
245  bool &defer_loaded,
246  int &op_id,
247  bool &missing_texture,
249  TexturePriority priority,
251 
252  static RV_VKImage *getPlaceholder(RV_Render *r, RV_ImageDim tex_type,
253  PlaceholderType type =MISSING_WHITE_SOLID,
254  const UT_Vector4F *fallbackcolor =nullptr);
255 
256  RV_TextureCache::Image privGetTexture(exint id);
257 
259  ~RV_TextureCache() override;
260 
262 
263  // UT_Cache interface
264  const char *utGetCacheName() const override
265  { return "Vulkan Texture Cache"; }
266  int64 utGetCurrentSize() const override
267  { return myCurrentSize; }
268  int64 utReduceCacheSizeBy(int64 amount) override
269  { return freeTextures(amount, true, false); }
270  bool utHasMaxSize() const override { return true; }
271  int64 utGetMaxSize() const override;
272  void utSetMaxSize(int64) override { }
273 
274 
275 private:
276 
277  exint freeTextures(exint needed_to_free, bool free_used, bool must_free);
278  exint cachedSizeBytes() const;
279 
280  class GraphicsMemoryClient : public UT_MemoryClient
281  {
282  public:
283  GraphicsMemoryClient(RV_TextureCache &cache) : myCache(cache) {}
284 
285  const char *name() const override
286  { return "Vulkan Texture Cache";}
287 
288  bool freeMemoryRequest(const UT_MemoryResource *resource,
289  RequestSeverity severity,
290  Niceness nice_level,
291  exint size_in_bytes,
292  exint &freed_amount_in_bytes) override;
293  bool memoryUse(const UT_MemoryResource *resource,
294  exint &in_use_bytes,
295  exint &cached_bytes) override;
296 
297  ~GraphicsMemoryClient() override {}
298  UT_NON_COPYABLE(GraphicsMemoryClient)
299 
300  private:
301  RV_TextureCache &myCache;
302  };
303 
304  GraphicsMemoryClient myResource;
305  UT_Array< UT_Map<exint, ImageInfo > > myImages;
306  UT_Map<exint, RV_ImageDim> myTypeMap;
307 
308  struct ResolveEntry
309  {
310  exint id = 0;
311  TexturePriority priority = RV_TextureCache::PRIORITY_NORMAL;
313  };
314  UT_StringMap<ResolveEntry> myResolveMap;
315  UT_StringMap<fpreal> myReductionTable;
316 
318  UT_Array<UT_UniquePtr<RV_VKImage>> myPlaceholders;
319  UT_Array<UT_Map<int32, RV_VKImagePtr>> myFallbackTextures;
320  UT_Lock myLock;
321  UT_Set<exint> myDeferImages;
322 
323  exint myCurrentSize = 0;
324  fpreal myReductionFactor = 1.0;
325  UT_StringHolder myDeviceName;
326 };
327 
328 #endif
A collection of Vulkan UBO, SSBO, and Image shader bindings (descriptor set)
int64 utGetCurrentSize() const override
required - return the current cache size, in bytes
Unsorted map container.
Definition: UT_Map.h:109
void
Definition: png.h:1083
int64 exint
Definition: SYS_Types.h:125
Opaque reference to a texture stored in the RV_TextureCache.
Definition: RV_Type.h:203
GLenum GLenum GLsizei void * image
Definition: glad.h:5132
UT_SharedPtr< RV_TextureRef::CacheData > refs
bool utHasMaxSize() const override
optional - override if the cache has a well defined maximum size
std::unique_ptr< T, Deleter > UT_UniquePtr
A smart pointer for unique ownership of dynamically allocated objects.
Definition: UT_UniquePtr.h:39
GLint GLsizei GLsizei height
Definition: glcorearb.h:103
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:108
GLint ref
Definition: glcorearb.h:124
std::shared_ptr< T > UT_SharedPtr
Wrapper around std::shared_ptr.
Definition: UT_SharedPtr.h:36
constexpr auto set(type rhs) -> int
Definition: core.h:610
T reduce(RangeT range, const T &identity, const FuncT &func, const JoinT &join)
Definition: Reduce.h:42
UT_Array< UT_UniquePtr< PXL_Raster > > rasters
#define RV_INVALID_OP_ID
#define UT_NON_COPYABLE(CLASS)
Define deleted copy constructor and assignment operator inside a class.
#define RV_API
Definition: RV_API.h:10
long long int64
Definition: SYS_Types.h:116
GLfloat GLfloat GLfloat alpha
Definition: glcorearb.h:112
GLenum GLenum severity
Definition: glcorearb.h:2539
void utSetMaxSize(int64) override
UT_UniquePtr< IMG_Stat > stat
HUSD_API const char * resolution()
GLuint const GLchar * name
Definition: glcorearb.h:786
GLushort pattern
Definition: glad.h:2583
PlaceholderType
If the texture is missing, one of these generic placeholders is used.
Handle to the main interface of Vulkan.
Definition: RV_Instance.h:44
Common base class for various caches.
Definition: UT_Cache.h:21
static const char * getFileSeparator()
FS_API bool cleanup(UT_StringArray &removed, UT_StringArray &error_files, exint &memory_freed, bool dry_run, const char *override_path=nullptr)
GLint GLint GLsizei GLsizei GLsizei depth
Definition: glcorearb.h:476
GT_API const UT_StringHolder version
Global cache of vulkan textures sourced from files.
fpreal64 fpreal
Definition: SYS_Types.h:278
Contains the details of a specific image file, used by IMG_File. This class contains all the high-lev...
Definition: IMG_Stat.h:38
GLint GLsizei width
Definition: glcorearb.h:103
Wrapper for a client of a limit memory resource.
GLboolean r
Definition: glcorearb.h:1222
void(* RV_TextureHDAResolverCB)(const char *optable_optype, const char *pattern, UT_StringArray &files)
RV_ImageDim
Definition: RV_Type.h:120
int64 utReduceCacheSizeBy(int64 amount) override
UT_UniquePtr< RV_VKImage > image