===============
Getting Started
===============

What is the FnUsdShim?
======================

The FnUsdShim is a shim library which sits between USD and Katana. It allows any USD library to be
used in conjunction with Katana, regardless of the USD version built against Katana. There are
some caveats here in that if there are API changes or feature additions, Katana may or may not
support those. The API changes would require updates to the FnUsdShim source to ensure the expected
interface is maintained.

The FnUsdShim is the library in which all of Katana's UsdNative codebase calls into when it wants
to work with USD. The FnUsdShim allows our code to continue to have a stable interface regardless
of the changes to the USD codebase. The C style interface also allows a more robust symbol lookup.

Where is the FnUsdShim?
=======================
The FnUsdShim is shipped with Katana pre-compiled against the USD (FnUsd) Katana ships with. If you
do not require your own custom USD build, then there is nothing to do!

The source for this library can be found in ``<KATANA_ROOT>/plugins/Src/FnUsdShim`` where
``<KATANA_ROOT>`` is the folder where Katana is installed.

How do I use my own USD libraries
=================================

.. note:: The *Viewer Tab* links directly to FnUsd at all times. This is currently being worked upon
    to utilise the FnUsdShim instead.

To utilise a custom USD library, the FnUsdShim library must be built against the custom USD build as
described by the `How to build FnUsdShim`_ section.

The `Environment variable setup`_ section details how to then utilise a custom FnUsdShim in place of
the FnUsdShim shipped with Katana, and built against FnUsd.

If building and wanting to use the USD Python bindings, these must be built against the same Python
version. This can be found in the **Help > About Katana** menu within Katana.

If you build FnUsdShim against a custom USD you MUST build KatanaUsdPlugins as well. More
information on KatanaUsdPlugins can be found within the KatanaUsdPlugins
:doc:`/Plugins/KatanaUSDPlugins/GettingStarted` section.

How to build FnUsdShim
----------------------

The same Python version as the application must be used. It is also strongly recommended to use
the same TBB library as well, to avoid thread over-subscription or worse.

We provide a simplified CMakeLists.txt with this source code which should help starting out a build
process. You may wish to modify this if your third party dependencies, like OpenSubDiv are not set
up as CMake Targets in the same way.

- `FdkBase_DIR` : Where the FdkBaseConfig.cmake can be found using
  `find_package`.
- `FnUsdAbstraction_DIR` : Where the FnUsdAbstractionConfig.cmake can be found
  using `find_package`.
- `OpenSubdiv_DIR`: Where OpenSubDivConfig.cmake can be found, or the root to a
    standard OpenSubdiv installation. Check the CMakeLists.txt file for how this
    tries to search for the required libraries. If using USD's default install, pass
    the same as `$pxr_DIR/lib/cmake/OpenSubdiv`.
- `pxr_DIR` - path to the root of your custom USD installation.
- `CMAKE_INSTALL_PREFIX` - prefix to where FnUsdShim will be installed.

.. code-block :: bash

    Linux:
    rm -rf build && mkdir build && cd build
    cmake -S <KATANA_ROOT>/plugins/Src/FnUsdShim -G Ninja \
    -DCMAKE_BUILD_TYPE="Release" \
    -Dpxr_DIR=<path to USD installation> \
    -DFdkBase_DIR=<KATANA_ROOT>/plugin_apis/cmake \
    -DFnUsdAbstraction_DIR=<KATANA_ROOT>/plugin_apis/cmake \
    -DFnCrateCache_DIR=<KATANA_ROOT>/plugin_apis/cmake \
    -DOpenSubdiv_DIR=<path to USD installation>/lib/cmake/OpenSubdiv \
    -DCMAKE_INSTALL_PREFIX=<Path to where you want to install FnUsdShim>
    cmake --build .
    cmake --install .

    Windows:
    mkdir build && cd build
    cmake -S <KATANA_ROOT>/plugins/Src/FnUsdShim -G Ninja ^
    -DCMAKE_BUILD_TYPE="Release" ^
    -DHAVE_SNPRINTF=True ^
    -Dpxr_DIR=<path to USD installation> ^
    -DFdkBase_DIR=<KATANA_ROOT>/plugin_apis/cmake ^
    -DFnUsdAbstraction_DIR=<KATANA_ROOT>/plugin_apis/cmake/ ^
    -DFnCrateCache_DIR=<KATANA_ROOT>/plugin_apis/cmake ^
    -DOpenSubdiv_DIR=<path to USD installation>/lib/cmake/OpenSubdiv ^
    -DCMAKE_INSTALL_PREFIX=<Path to where you want to install FnUsdShim>
    cmake --build .
    cmake --install .
    cd ..


Environment variable setup
--------------------------

The main environment variable to disable Katana's internal FnUsdShim library is
`KATANA_USD_ABSTRACTION_DISABLED`. Otherwise, ensure all dependencies are added.
Below is an example after using USD's `build_script.py`.

.. code-block :: bash

    Linux:
    export KATANA_USD_ABSTRACTION_DISABLED=1
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path to install of USD>/lib
    export PYTHONPATH=$PYTHONPATH:<path to install of USD>/lib/python
    export PXR_PLUGINPATH_NAME=$PXR_PLUGINPATH_NAME:<path to install of FnUsdShim>/Libs
    export USG_SHIMLIB_PATH=<path to install of FnUsdShim>/Libs
    export USG_SHIMLIB_NAME=<Name of FnUsdShim>.so

Windows requires the additional `usg_LIB_DIRS` because directories on `PATH` are no longer added to
the dll_directories for Python 3.8+. Therefore we manually add any library under `usg_LIB_DIRS` when
the Python bindings are loading its dependencies, which are FnUsdShim and USD by default.

.. code-block :: bash

    Windows:
    set KATANA_USD_ABSTRACTION_DISABLED=1
    set usg_LIB_DIRS=<path to install of USD>/lib
    set PATH=%PATH%;<path to install of USD>/lib;<path to install of USD>/bin
    set PYTHONPATH=%PYTHONPATH%;<path to install of USD>/lib/python
    set PXR_PLUGINPATH_NAME=%PXR_PLUGINPATH_NAME%;<path to install of FnUsdShim>/Libs
    set USG_SHIMLIB_PATH=<path to install of FnUsdShim>/Libs
    set USG_SHIMLIB_NAME=<Name of FnUsdShim>.dll

Troubleshooting
---------------

Setting the environment variable ``USG_DEBUG_USDSHIMLIB=1`` will print plugin
loading information to the terminal describing how the FnUsdShim lib plugin is
being discovered.