Installing

Installing the Delegate

Once you have built a custom render delegate, you’ll end up with a directory structure similar to:

├───bin/lib (May not have this)
│   └───binaries related to build plugin..
└───plugin
    └───usd
        ├───hdEmbree.so
        └───hdEmbree
            └───resources
                └───plugInfo.json

The main point of interest is the plugin/usd/ folder. In this hdEmbree example, following on from the Building section, the hdEmbree.so (.dll on Windows) is the library for the Hydra Render Delegate. The plugInfo.json file is used by USD to find the Hydra Render Delegate library and describe the plug-in. If we take a quick look inside the plugInfo.json file:

{
    "Plugins": [
        {
            "Info": {
                "Types": {
                    "HdEmbreeRendererPlugin": {
                        "bases": [
                            "HdxRendererPlugin"
                        ],
                        "displayName": "Embree",
                        "priority": 99
                    }
                }
            },
            "LibraryPath": "../hdEmbree.so",
            "Name": "hdEmbree",
            "ResourcePath": "resources",
            "Root": "..",
            "Type": "library"
        }
    ]
}

The LibraryPath specifies the where to find the .so, (or .dll on Windows) which can be a little confusing with both the Root and LibraryPath keys affecting this. In this example, the root is .., so up one folder to plugin/usd/hdEmbree/ then the library is specified as being ../hdEmbree.so, so back to plugin/usd/hdEmbree.so; which matches our install path. Here we also see that the type of this plug-in is registered as an HdxRendererPlugin which is used by USD to determine that this is a render delegate.

Once you understand this hierarchy, it can also be seen in the /path/to/Katana/plugin/usd/hdStorm directory which is shipped as the default GL renderer inside Hydra. To install your delegate, just copy your plugin folder at the same location as the plugin folder in Katana. Once this is done, either ensure that any required libraries are also on your PATH or LD_LIBRARY_PATH, or copy them into the Katana/bin folder for Katana to find them. If you’re copying the required libraries into the Katana/bin folder, ensure that step 3 of the Common Issues section is followed, otherwise you may see issues on Linux for finding the required libraries.

NOTE: In order to ensure that Katana’s USD library does not load plug-ins built for another USD build, it uses FNPXR_PLUGINPATH in place of the stock USD PXR_PLUGINPATH_NAME environment variable.

Running the Delegate

Katana’s Viewer tab reads the plug-ins loaded by Hydra, and shows their displayName from the JSON file in the Render Delegates section of its Display menu.

Common Issues

1. Switching to the custom delegate crashes Katana.

   1. This issue can occur when the plugInfo.json file for the render delegate doesn’t describe the actual path to the delegate library.

2. Errors or warnings not shown anywhere from custom delegate.

   1. This was a decision on our part to provide a flag in order to enable this debugging feature such that it doesn’t clutter users’ terminals or logs in general. You can enable logging of messages on your machine by setting the environment variable KATANA_HYDRAVIEWER_DEBUG to 1.

3. My delegate cannot find Fn<UsdLibrary> at runtime on Linux.

   1. This may be due to the RPATH setup for plugins defaulting to ../../lib rather than ../../bin. We install the USD libraries in our bin folder along with our other libraries. Therefore, you may need to edit the cmake/macros/private.cmake file, around line 1279 from USD v19.05, to add _pxr_add_rpath(rpath "${CMAKE_INSTALL_PREFIX}/bin") instead of, or in addition to _pxr_add_rpath(rpath "${CMAKE_INSTALL_PREFIX}/lib").