============
 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:

.. code-block:: json

    {
        "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/hdStream` 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
====================
Our *Viewer (Hydra)* tab will then read the plug-ins loaded by Hydra and show their `displayName` from the JSON file in the *View > Hydra Renderer > <displayName>* menus at the top of the *Viewer (Hydra)* tab.

Common Issues
=============
1) Switching to the custom delegate crashes Katana.
    a) 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.
    a) 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.
    a) 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")`.
4) My view isn't converging.
    a) To enable the viewer to continue querying the renderer, even in a static scene, we have provided an option called *Redraw Until Converged* which can be found under *View > Hydra Renderer* in the *Viewer (Hydra)* tab.