Geolib3-MT Configuration

Geolib3-MT can be configured via the RenderSettings node. All Geolib3-MT options live under the sceneTraversal heading.

sceneTraversal Parameters


text field

Default: 0

Determines how many logical cores Geolib3-MT uses during scene traversal phase.

Unlike previous versions, Geolib3-MT uses an internal thread pool to improve scene traversal time. The following diagram demonstrates the difference between Geolib3-MT and previous versions of Katana.

The default value of 0, causes Geolib3-MT to use all available logical cores on the host computer.

Note:  Whilst the core Geolib3-MT processing engine scales as the number of cores increases, individual Ops within an Op tree may not exhibit the same scaling characteristics. It is possible that an increase in threads can result in an increase of scene traversal time. In this case, the new profiling tools available in Katana 3.5 can be used to identify these Ops and optimize their behavior. The same is true of Ops marked thread unsafe, as these require the acquisition of a Global Execution Lock (GEL), which further limits scene traversal scalability.



Default: Off

When turned on, Geolib3-MT performs a pre-processing step in which it examines the topology of the Op tree to identify constructs that can be potentially optimized. One optimization is the collapsing of sequences of Ops of the same type into a single instance of that Op. There are a number of benefits to this:

  • Reduced function call overhead - There is a small cost involved in scheduling an Op to cook a scene graph location. By combining chains of similar Ops, it's possible to reduce this function call overhead.
  • Reduced memory footprint - A chain of 10 Ops occupies 10 separate cook results in the caching subsystem, while a successfully collapsed Op Chain occupies only 1 cook result per location.

The result of evaluating a collapsed chain of Ops, when observed from the most downstream Op, should be the same as if the chain of Ops were evaluated.

Note:  Op API calls to query upstream scene graph results, such as getAttr(), does not return the expected result when called within a collapsed chain if one of those Ops within the chain was responsible for setting that attribute. In this case the Op should use getOutputAttr() instead.

The Op tree optimizer attempts to collapse any chain of Ops of the same type if it calls GeolibSetupInterface::setOpsCollapsible() during the setup() call. Callers of this function must specify the name of an attribute which Geolib3 passes to the Op's cook() call as an Op argument. This attribute contains an ordered array of attributes (ordered upstream Op to downstream Op) containing the collapsed Ops' arguments. The Op is then able to deal with this batch Op argument as appropriate.



Default: Off

When turned on, verbose logging inside the Geolib3-MT runtime is enabled. This includes verbose logging during scene traversal, and Op tree optimization, if enabled.

sceneTraversal.cache Parameters

Geolib3-MT includes a number of settings to control the behavior of the caching subsystem. The caching subsystem is responsible for the storage and retrieval of previously cooked scene graph locations, known as cook results. These settings can be modified from the RenderSettings node on a project-by-project basis.

Caching, and the trade-off between memory usage and time to first pixel can have a significant impact on the performance of scene traversal time and rendering. Using the settings provided by Geolib3-MT it's possible to tune the memory footprint during the scene traversal phase of rendering.



Default: On

If turned off, no cook results are evicted from the cache.

Tip:  Whilst initially it might seem counter-intuitive to disable cache eviction, there may be scenes where it is appropriate. This may be the case when the scene and data structures required by the renderer fit comfortably into memory. Even larger scenes could benefit to some degree, as once the scene generation phase of rendering is complete, the memory pages occupied by Geolib3-MT's cook results can no longer be accessed and therefore are not eligible for paging to disk; as these pages won't be re-paged to main memory during rendering the performance penalty is minimal.


text field

Default: 1,048,576

If cacheEviction is turned on, the cacheSoftLimit governs how many cook results are stored in local caches before entries are evicted using a least recently used eviction policy.

Note:  Whilst these entries may be evicted from a local cache they may be shared amongst a number of other local caches or the central (shared cache). In which case, the entries' memory won't immediately be reclaimed.

Consider the maximum depth of the scene graph and Op tree. The cacheSoftLimit controls the size of the recently used cook result cache on a per thread basis. This means any locations cooked on a particular thread, or any locations accessed during the cooking process (such as via getAttr()), are stored in the local cache and subject to eviction based on the value of the cacheSoftLimit.


text field

Default: 10,000

If cacheEviction is turned on, the collectionFrequency governs the time, in milliseconds, between collection cycles. During a collection cycle, Geolib3-MT gathers all cache entries evicted since the previous collection cycle and if the cook result is no longer used, evict and reclaim the memory for the cook result.

Note:  Reducing the collectionFrequency interval causes more aggressive eviction of cook results leading to a reduced memory footprint but potentially at the cost of scene traversal time.



Default: On

If turned on, Geolib3-MT performs a traversal of the scene graph populating an internal cache.

The extent of this traversal can be controlled by the settings under sceneTraversal.cachePrepopulation.

sceneTraversal.cachePrepopulation Parameters



Default: Off

If turned on, Geolib3-MT first fully traverses the scene generated by any source Op (any Op with no inputs) found in the Op tree. This setting can provide benefits when loading in geometry caches or other asset types.

Note:  Empirical tests have found that source Ops are typically followed by some form of prune operation; as a result, in these cases, turning on preCookSourceOps can generate more scene graph locations than is required which can lead to increased memory consumption and traversal times.



Default: On

If turned on, Geolib3-MT identifies Ops within the Op tree that can be evaluated in parallel.

An example of this is the Merge Op:

Geolib3-MT evaluates each branch in parallel, which can reduce scene traversal times.



Default: On

If turned on, Geolib3-MT cooks all remaining scene graph locations, fully expanding the scene.

Based on the values of the above settings, on completion of the cachePrepopulation phase, the Geolib3-MT cache is pre-populated with either the whole scene graph or a subsection of it. Geolib3-MT has been optimized to provide efficient access to renderer plugins via the existing FnScenegraphIterator API to this cache. This cache is a scalable, thread safe cache, as such >we encourage renderer plugins to access this cache concurrently to improve the performance of the scene build phase.

Warning:  If the Geolib3-MT cache is not fully populated, cache access (via FnScenegraphIterator) results in a cache miss. In this case the requested location is cooked using the calling thread.