USDPluginExamples

A collection of example plugins for Pixar's USD (Universal Scene Description).

This project also aims to provide a set of CMake utilities for building USD plugins outside of the USD project source tree. The utilities are heavily based on the build logic prescribed by the USD project itself.

We hope the minimal examples and surrounding build infrastructure can be useful to USD community developers interested in building and deploying their own plugin(s).

Huge thanks to Pixar's USD team for providing a highly extensible platform!

USD Plugins
Dependencies
Building
Running
CMake Utilities

USD Plugins

USDPluginExamples provides the following USD plugins:

usdTri: A schema library defining a Triangle prim type.
usdTriImaging: A prim adapter which images the Triangle prim type.
usdTriFileFormat: A file format plugin which authors a triangular mesh for a .triangle payload.
hdTri: A hydra renderer plugin which images a triangle (in the most direct sense).
usdviewTri: An usdview plugin providing a menu command to define child Triangle prim(s) under selected paths.

There are many other USD plugins available online - check out USD Working Group: Projects & Resources for more!

Dependencies

The following dependencies are required:

C++ compiler
CMake (3.13 or greater)
USD (23.05)
Boost and Intel TBB (USD dependencies)

Python may also be required, depending on python support in the USD installation.

Building

Example snippet for building the plugins on Linux (and potentially MacOS):

mkdir build
cd build
cmake \
  -DUSD_ROOT="/apps/usd/23.05/" \
  -DTBB_ROOT="/apps/usd/23.05/" \
  -DBOOST_ROOT="/apps/usd/23.05/" \
  -DBUILD_TESTING=ON \
  -DCMAKE_INSTALL_PREFIX="/apps/USDPluginExamples/" \
  ..
cmake --build  . -- VERBOSE=1 -j8 all test install

Example snippet for building a Visual Studio project on Windows:

mkdir build
cd build
cmake ^
    .. ^
    -G "Visual Studio 15 2017 Win64" ^
    -DCMAKE_INSTALL_PREFIX=D:\usd\USDPluginExamples\ ^
    -DUSE_PYTHON_3=ON ^
    -DBUILD_TESTING=ON ^
    -DUSD_ROOT="D:\usd\builds\v23.05" ^
    -DTBB_ROOT="D:\usd\builds\v23.05" ^
    -DBOOST_ROOT="D:\usd\builds\v23.05"

cmake --build . --config Release -j 8 --target ALL_BUILD RUN_TESTS INSTALL

CMake options for configuring this project:

CMake Variable name	Description	Default
`USD_ROOT`	Root directory of USD installation
`TBB_ROOT`	Root directory of Intel TBB installation
`BOOST_ROOT`	Root directory of Boost installation
`ENABLE_PYTHON_SUPPORT`	Enable python support. Must match python support of USD installation.	`ON`
`USE_PYTHON_3`	Build against Python 3 libraries.	`OFF`
`BUILD_TESTING`	Enable automated testing.	`OFF`

Running

To register the plugin(s) as part of the USD runtime, the following environment variables will need to be defined:

Environment Variable	Value(s)
`PYTHONPATH`	`${USDPLUGINEXAMPLES_INSTALL_ROOT}/lib/python`
`PXR_PLUGINPATH_NAME`	`${USDPLUGINEXAMPLES_INSTALL_ROOT}/lib/usd` `${USDPLUGINEXAMPLES_INSTALL_ROOT}/plugin/usd`

Additionally, Windows requires:

Environment Variable	Value(s)
`PATH`	`${USDPLUGINEXAMPLES_INSTALL_ROOT}/lib`

Additionally, Linux requires:

Environment Variable	Value(s)
`LD_LIBRARY_PATH`	`${USDPLUGINEXAMPLES_INSTALL_ROOT}/lib`

_{Note: libraries and plugins are installed into different locations - thus PXR_PLUGINPATH_NAME specifies
two separate values.}

Once the environment variables have been set-up, an example scene in this repo can be previewed with usdview:

usdview ./src/usdTri/scenes/triangle.usda

In the viewport, a triangle should be centered at origin:

CMake Utilities

Custom CMake functions are provided, for abstracting away USD plugin build intricacies:

usd_library: Example usage
usd_plugin: Example usage
usd_executable: Example usage
usd_test: Example usage
usd_python_library: Example usage
usd_python_test: Example usage

The interface of the above functions are largely based on those used throughout the official USD project.

USDPluginExamples can be used as a template ("Use this template" button near the top of the page).

Another option to gain access to the cmake utilities is to copy/integrate the files under cmake/ into an existing project.