RenderSettings

The RenderSettings node defines the 3D render output settings (camera to use, renderer, size of output) for an image.

Connection Type

Connection Name

Function

Input

input

The place in the node graph where you want to define the 3D render output settings.

 

Control (UI)

Default Value

Function

cameraName

/root/world/cam/camera

Specifies the camera that the scene should be rendered through. The field contains a path to the camera's location in the scene graph. The cameraName parameter options are available by clicking the dropdown menu.

For more information, refer to the Scene Graph Location Widget Type in Common Parameter Widgets.

renderer

dl

Specifies the renderer to use.

resolution

512x512

Sets the size of the output image.

overscan

0

Pads the data window of the resulting render by the specified pixel amount on each side. The frame window is unchanged.

adjustScreenWindow

No adjustment

Adjusts the pixel aspect ratio to match one of the device aspect ratio's dimensions. Either the height or the width of the screen window is adjusted to match the output resolution.

maxTimeSamples

1

Sets how many times a point is sampled when the shutter is open. For animated parameters within Katana (such as transforms), this is how many samples are evaluated from shutter open to close. The higher the number, the more accurate the motion blur.

shutterOpen

0

Specifies the timing of the opening and closing of the camera shutter.

shutterClose

0

cropWindow

0.0, 1.0, 0.0, 1.0

Specifies the render crop window in normalized coordinates: xmin xmax ymin ymax, starting in the upper left-hand corner. The part of the image that renders has a dotted red line around it.

Note:  The dotted red line isn't displayed unless you are viewing the RenderSettings node.

interactiveOutputs

all

Specifies whether all the AOVs are rendered during Preview Render, or whether only the primary pass is rendered. If you set the output to primary, the Local Assignment box turns yellow to indicate that you are using local values.

interactivePrecision

float

The data type to use for encoding pixels that are transmitted between a render process and Katana. You can use this to reduce the bandwidth required for transmitting images, but at the cost of a loss of fidelity.

Choose between three options:

  • float : Single-precision floating-point format (32 bits).

  • half : Half-precision floating-point format (16 bits).

  • byte : Reduced precision resulting in the lowest bandwidth, but possibly visible banding artifacts and a loss of fidelity when stopping images up or down (8 bits). This clamps pixel values to a range between 0 and 1.

The default value can be set using the KATANA_DISPLAYDRIVER_PRECISION environment variable.

geolibRuntime

Geolib3-MT

Set which Geolib3 Runtime to use. In the majority of cases, you should select Geolib3-MT. However, a small number of scenes that are not set up for concurrent scene traversal may perform better with the Classic Runtime from Katana 3.2.

See Geolib3-MT sceneTraversal Parameters for parameter details.

cacheEvictionMode

DependencyProtecting

Choose a cache eviction strategy from one of the three options:

  • Dependency protecting

  • Continual

  • Relaxed

For details see Performance Optimization using a Cache Eviction Strategy.

 

deferredUsdToKatanaEnabled

on

Toggles the conversion of USD data to Katana data when performing a render or with Implicit Resolvers enabled.

adjustScreenWindowWhen

deferred

Determines how the adjustScreenWindow parameter (see above) is handled:

  • deferred - adjustScreenWindow is evaluated by the AdjustScreenWindowResolve Op as an implicit resolver.

  •  immediate - adjustScreenWindow parameter takes effect immediately.

 

Geolib3-MT sceneTraversal Parameters

opTreeOptimizations

checkbox

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.

verboseLogging

checkbox

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

Each Geolib3-MT cache eviction strategy, listed under the cacheEvictionMode parameter, includes a number of configurable settings based on which eviction strategy you choose. These settings can be modified from the sceneTraversal.cache menu and can be optimized 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 it's possible to tune the memory footprint during the scene traversal phase of rendering.

cacheEviction

checkbox

Default: On

When enabled, data in the cache will be periodically removed (evicted) based on the selected cacheEvictionMode.

 

Note:  The Geolib3-MT Runtime maintains a cache to improve the locality of previously cooked data. Cache entries are keyed on pairs of scene graph location and Op ID.

Disabling cache eviction can decrease scene graph traversal times but may lead to higher memory usage. When cacheEviction is disabled with large scene graphs, the available memory can quickly become full.

Tip:  While 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.

Dependency Protecting sceneTraversal.cache Parameters

evictionTriggerTimeInterval

Default: 1000ms

The time interval for the time-based scene data cache eviction trigger is specified in milliseconds.

0ms disables time-based eviction.

evictionTriggerCookCount

Default: 0

The cook count for which the cook-based scene data cache eviction is triggered.

0 disables cook-based eviction.

mruCookProtectionCount

Default: 0

Specify the maximum number of recently used cooks to safeguard scene data from being evicted.

Continual sceneTraversal.cache Parameters

cacheLimitingMode

Default: Fixed cache size

Specifies the method for cache eviction.

  • Fixed cache size : If the cache size reaches a set limit of the number of entries, every new entry triggers the removal of one of the least-recently used.

  • Memory-based : If the used memory in the system reaches a set level, each new cache entry causes removal of a set number of the least-recently used entries.

For Memory-based, you can set three levels of memory usage: light, medium, and heavy, to increase the amount of memory used for the cache. Each level has an eviction count to set how many entries are evicted when the cache hits that level.

cacheLimitingMode: Fixed cache size

cacheSize

Default: 1000000

Determines the set size of the cache. Each entry in the cache is identified by a combination of a scene graph location and an Op ID.

When the cache limit is reached, every new cache entry triggers the removal of one of the least-recently used.

A smaller cache size uses less memory, but it may lead to recooking of evicted data if it gets removed prematurely, leading to reduced performance.

cacheLimitingMode: Memory-based

lightMemoryLevel

Default: 70%

lightEvictionCount

Default: 1

Set the lowest percentage level of memory usage at which new entries will trigger the removal of least-recently used entries. The number removed is set by lightEvictionCount

mediumMemoryLevel

Default: 80%

mediumEvictionCount

Default: 2

Set the middle percentage level of memory usage at which new entries will trigger the removal of least-recently used entries. The number removed is set by mediumEvictionCount

heavyMemoryLevel

Default: 90%

heavyEvictionCount

Default: 3

Set the middle percentage level of memory usage at which new entries will trigger the removal of least-recently used entries. The number removed is set by heavyEvictionCount

Relaxed sceneTraversal.cache Parameters

 

cacheSoftLimit

text field

Default: 1,048,576

If cacheEviction is 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.

collectionFrequency

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.

useCachePrepopulation

checkbox

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.

maxCores

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.

Relaxed sceneTraversal.cachePrepopulation Parameters

preCookSourceOps

checkbox

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.

preCookKeyOps

checkbox

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.

preCookAllLocations

checkbox

Default: On

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

Based on the values of the settings above, 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.

deferredUsdToKatana Settings

These settings determine how the USD data is converted to Geolib data before being sent to a renderer.

They are the same settings found in UsdToKatana but in this case, the conversion is deferred to render time.