Geolib3-MT and Cache Optimization

About Geolib3-MT

Geolib3-MT is a modernized version of the Classic Geolib3 runtime (Katana's scene graph processing engine). It is designed to optimize re-use of computed scene data during multithreaded scene evaluation.

Configuring Geolib3-MT

To edit Geolib3-MT settings, open the parameters of your RenderSettings node and find the sceneTraversal section. For a complete reference, see RenderSettings.

Caching and Eviction

In 3D rendering, "cooking" refers to preparing and processing data before it is rendered. To boost performance, Katana stores frequently accessed cook results in a cache located in system memory. Scene data is stored for each scene graph location and Op. This includes output scene graph details and information needed to efficiently process descendant and downstream locations.

Note:  For more information on cook results, see Op Cook Profiling.

To improve cache efficiency, data that is less likely to be needed right away is removed, known as “eviction”. Evicting data more often reduces memory usage, but it also increases overhead and limits the availability of previously computed results, especially when their usage is not easily predictable.

Eviction during a render using the Classic runtime is managed directly by the scene traversal mechanism of the renderer plug-in, but is typically configured to evict continually and aggressively to minimize memory consumption. Instead, The Geolib3-MT runtime allows the user to control the eviction strategy.

Performance Optimization using a Cache Eviction Strategy

Cache management can have a considerable impact on the performance of your renders. Katana provides three configurable cache eviction strategies to allow optimization for particular recipes and hardware configurations.

Choosing a Cache Eviction Strategy

The optimal cache eviction strategy depends on your project, configuration options, and choice of renderer. There is no one-size-fits-all approach - it's more practical to experiment with the various strategies to determine the most effective one rather than relying solely on theoretical models.

Cache eviction strategies are found under cacheEvictionMode in the RenderSettings properties.

Dependency Protecting Cache Eviction

Dependency protection involves tracking cook dependencies in order to effectively protect scene data that may be expected to be required for subsequent cooks. This includes data pertinent to the following:

  • ‘Current’ traversal locations, defined by ‘protected cooks’. Scene Graph Iterators (used by Renderer Plug-ins for scene traversal) protect their scene graph location.

  • Optionally, Most Recently Used (MRU) scene graph locations.

Dependency protection is the default option and has been designed to deliver good performance for any scene recipe, with straightforward options for customization when necessary. By default, eviction occurs every one second.

See Dependency Protecting sceneTraversal.cache Parameters for settings.

Dependency Protecting Considerations

With Dependency Protecting, eviction should happen relatively infrequently. This is because pausing all scene cooking and evaluating the extent of cook protection is costly. However, evictions should not be so infrequent as to allow excessive memory consumption.

To be efficient, most of the scene data should be evicted at each turn. This can be assessed by enabling verboseLogging in the render settings. When enabled, you receive a report on the number of protected cooks for each eviction. This includes the reason for their protection and the size of the cache as it changes, given as the number of Cook Results.

Note:  Evicting a significant amount of the scene data is known as effective eviction.

Location-based protection usually offers enough caching (and periodic eviction means that recently used cooks are cached to some degree).

Enabling explicit protection for most recently used locations can benefit expensive scene recipes with specific access patterns. In such cases, the extra protection justifies the cost of the eviction process.

Note:  Renderer plug-ins that cache Scene Graph Iterators can cause over-protection of scene data. Scene Graph Iterator based cook protection can be disabled by setting the KATANA_GEOLIB_CDT_ITERATOR_PROTECTION_ENABLED environment variable to ”0”, in which case Render Settings should be configured to enable some level of MRU cook protection instead (set to protect more cooks than the number of render threads).

Continual Cache Eviction

Continual uses a hard-limited global scene data cache with thread-local recency lists. Cache eviction works on a per-thread Least Recently Used (LRU) basis, similar to Relaxed mode. However, unlike Relaxed, the hard limit of the global cache is actively enforced.

Continual provides several parameters to affect memory management. You can decide to set cache size or set three levels of memory usage, each with its own eviction count.

See Continual sceneTraversal.cache Parameters for settings.

Relaxed Cache Eviction

This is the original strategy for GeoLib3-MT. "Relaxed" uses global and per-thread caches of shared data. Eviction occurs periodically, and in the background, operating per-thread using the Last Recently Used (LRU) principle.

Using thread-local recency data to select which data to evict can be a lightweight option that yields good results. However, the drawback is that tighter caching limits might result in unexpected re-cooking, which can be expensive for scene recipes involving resource-intensive operations and particular access patterns.

Each thread-local cache is configured using cacheSoftLimit, which is the number of cooks results.

Relaxed mode may experience issues in managing memory consumption for the following reasons:

  • The number of cook results stored in a cache does not directly correlate with the amount of memory they consume.

  • The caches are soft-limited, and the runtime may increase their limit.

  • There is no guard against scene data getting cached faster than it can be removed.

See Relaxed sceneTraversal.cache Parameters for settings.