Home

Awesome

<a href="https://github.com/wetadigital/USDPluginExamples/actions?query=workflow%3A%22Build+and+test%22"><img src="https://github.com/wetadigital/USDPluginExamples/workflows/Build%20and%20test/badge.svg"/></a>

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

USDPluginExamples provides the following USD plugins:

[*] 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:

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 nameDescriptionDefault
USD_ROOTRoot directory of USD installation
TBB_ROOTRoot directory of Intel TBB installation
BOOST_ROOTRoot directory of Boost installation
ENABLE_PYTHON_SUPPORTEnable python support. Must match python support of USD installation.ON
BUILD_TESTINGEnable automated testing.ON
BUILD_HYDRA2Enable 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 VariableValue(s)
PYTHONPATH${USDPLUGINEXAMPLES_INSTALL_ROOT}/lib/python
PXR_PLUGINPATH_NAME${USDPLUGINEXAMPLES_INSTALL_ROOT}/lib/usd<br/>${USDPLUGINEXAMPLES_INSTALL_ROOT}/plugin/usd

Additionally, Windows requires:

Environment VariableValue(s)
PATH${USDPLUGINEXAMPLES_INSTALL_ROOT}/lib

Additionally, Linux requires:

Environment VariableValue(s)
LD_LIBRARY_PATH${USDPLUGINEXAMPLES_INSTALL_ROOT}/lib

<sub>Note: libraries and plugins are installed into different locations - thus PXR_PLUGINPATH_NAME specifies two separate values.</sub>

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

Environment VariableValue(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: Triangle

CMake Utilities

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

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.