UsdEngineWrite

Introduction

UsdEngineWrite nodes allow users to write C++ UPE Engines for Katana’s USD Processing Engine.

Note

By default, the UsdEngineWrite node type is disabled. It can be enabled by setting the KATANA_ENABLE_USDENGINEWRITE_NODE environment variable to 1 before Katana is launched.

Technical Description

The first time a UsdEngineWrite node is visited in a node graph traversal, a temporary dynamic library will be compiled with the provided C++ source code. This will literally create a .so file on Linux or a .dll file on Windows. Each UsdEngineWrite node instance will compile its own dynamic library, with its own source code. The dynamic library will be loaded and executed to define the USD Layer.

When a UsdEngineWrite node is created in the node graph, a template program is offered in its code.cpp parameter. This is the source code that will be compiled. The same API that is used when writing regular Foundry::Katana::UPE::Engine-based Engines can be used inside UsdEngineWrite nodes. A void process(UPE::Engine& engine, usg::GeomSceneContext& context) function is provided as part of the template program, which the user is to fill in. In advanced situations, also a void processScenegraph(UPE::Engine& engine, usg::GeomSceneContext& context) function can be implemented.

Static variables can be defined; they will be initialized when the dynamic library is first loaded. However, if memory is allocated at library load time, it should be freed when the library is unloaded as well, or else unrecoverable memory leaks will occur.

The dynamic libraries will be unloaded in these situations:

  • When caches are flushed in Katana.

  • When changes in the UsdEngineWrite node’s parameters invalidate the node, which means a new dynamic library needs to be compiled and loaded.

A CMake template script is also provided in the cmake.txt parameter. Usually the CMake script will remain unchanged, however, if external libraries are required, users will need to make adjustments to include such libraries and add dependencies to the default CMake target.

User Engine Args

User parameters can be added to nodes, which will then be included in the Engine when the Engine Chain is built. To query user Engine Args, Foundry::Katana::UPE::Engine::getArgs() can be used in the process() function, with the Engine Arg name in the "user.<parameter_name>" form.

By default, user Engine Args are configured as “defines geometry” (changes in their values will trigger a stage recomposition). User parameters in UsdEngineWrite nodes can define a 'definesGeometry' widget hint that, when set to 'False' (a string), will configure the corresponding user Engine Arg as “modifies values only”, avoiding stage recomposition when their value changes. From the Parameters tab, while in user parameters edit mode, the widget hint can be set by toggling the Defines Geometry option in the Widget Options… dialog for each user parameter.

Motivation For Using UsdEngineWrite Nodes

The UsdEngineWrite node type is good for prototyping C++ UPE Engines directly in a Katana session. It helps to get familiar with the USD Processing Engine and its API.

Building the dynamic libraries takes time (1 or 2 seconds for a small program, but it could take longer if the program grows large). Therefore, the recommendation is to convert the UPE Engine into a regular Katana plug-in that can be loaded on startup.

Requirements

In order to use the UsdEngineWrite node type, CMake, a build generator, and a compiler need to be available in the system.

On Linux, the CC and CXX environment variables will be respected in order to find the current compiler. On Windows, Visual Studio 2022 will be used by default (set KATANA_USDENGINEWRITE_CMAKE_GENERATOR for choosing a different compiler on Windows).

Environment Variables

  • KATANA_ENABLE_USDENGINEWRITE_NODE: Set to 1 to enable the node type.

  • KATANA_USDENGINEWRITE_CMAKE_GENERATOR: By default, Makefile will be used on Linux; Visual Studio 17 2022 will be used on Windows. Users can set this environment variable (e.g. to Ninja or Visual Studio 16 2019) to override the default generator (and the compiler in the case of Windows).