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!

Table of Contents

• 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 Hydra 1 only prim adapter which images the Triangle prim type. [*]
• usdTriImagingHd2: A Hydra 2 only 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.

[*] We deliberatly split the Hydra 1 & 2 Triangle Prim Adapters into two plugins/sources to outline the differences

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 (Tested with CMake 3.29.2)
• USD (24.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/" \
  -DCMAKE_INSTALL_PREFIX="/apps/USDPluginExamples/" \
  ..
cmake --build  . -- VERBOSE=1 -j8 all test install

Example snippet for building a Visual Studio project on Windows (x64 Native Tools Command Prompt with Administrator privileges):

mkdir build
cd build
cmake ^
    -G "Visual Studio 15 2017 Win64" ^
    -DUSD_ROOT="D:\install\usd" ^
    -DCMAKE_INSTALL_PREFIX="D:\install\USDPluginExamples\" ^
    ..

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
BUILD_TESTING	Enable automated testing.	ON
BUILD_HYDRA2	Enable building Hydra2 plugins, will disable Hydra1 plugin building.	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.}

To run the Hydra2 Prim Adapter with Storm/GL you have to enable the SceneIndex for UsdImagingGL

Environment Variable	Value(s)
USDIMAGINGGL_ENGINE_ENABLE_SCENE_INDEX	`1``````````````````

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.