Omniverse USD Resolver

This is a USD plugin that allows for working with files in Omniverse

Documentation

The latest documentation can be found at http://omniverse-docs.s3-website-us-east-1.amazonaws.com/usd_resolver/

Getting

You can get the latest build from Packman. There are seperate packages for each usd flavor, python version, and platform.

They are all named: omni_usd_resolver.{usd_flavor}.{python_flavor}.{platform}

usd_flavor is one of:

  • nv-20_08

  • nv-21_11

  • pxr-20_08

python_flavor is one of:

  • nopy

  • py27

  • py37

  • py39

platform is one of:

  • windows-x86_64

  • linux-x86_64

  • linux-aarch64

All packages use the same versioning scheme: {major}.{minor}.{patch}

USD & Client Library

The package includes redist.packman.xml which point to the versions of USD and the Omniverse Client Library that this plugin was built against. You can include it in your own packman.xml file like this:

<project toolsVersion="5.0">
  <import path="../_build/target-deps/omni_usd_resolver/deps/redist.packman.xml">
  </import>
  <dependency name="usd_debug" linkPath="../_build/target-deps/usd/debug">
  </dependency>
  <dependency name="usd_release" linkPath="../_build/target-deps/usd/release">
  </dependency>
  <dependency name="omni_client_library" linkPath="../_build/target-deps/omni_client_library">
  </dependency>
</project>

NOTE: This must be in packman.xml file that is pulled after pulling this package. You can’t put it in the same packman.xml as the one that pulls this package.

This requires packman 6.4 or later.

Initializing

You must either copy the omni_usd_resolver plugin to the default USD plugin location, or register the plugin location at application startup using PXR_NS::PlugRegistry::GetInstance().RegisterPlugins.

Be sure to package both the library (.dll or .so) and the “plugInfo.xml” file. Be sure to keep the folder structure the same for the “plugInfo.xml” file. It should look like this:

  • omni_usd_resolver.dll or omni_usd_resolver.so

  • usd/omniverse/resources/plugInfo.xml

If you use RegisterPlugins, provide it the path to the “resources” folder. Otherwise, you can copy the entire ‘debug’ or ‘release’ folders into the standard USD folder structure.

Live Mode

In order to send/receive updates you must:

  1. #include <OmniClient.h> (from client library)

  2. Create or open a “.live” file on an Omniverse server

  3. Call omniClientLiveProcess(); periodically

For “frame based” applications, you can safely just call omniClientLiveProcess inside your main loop.

For event based applications, you can register a callback function using omniClientLiveSetQueuedCallback to receive a notification that an update is queued and ready to be processed.

In either case, make sure that nothing (ie: no other thread) is using the USD library when you call omniClientLiveProcess because it will modify the layers and that is not thread safe.

Developing

Adding new Flavors

To add a new USD flavor, first modify tools/repoman/generate_redist_deps.py to add your flavor to the list, then add the flavor to the USD resolver configuration in Team City.

Source Linking

To run with a locally built version of the client library, modify omni-client-library.txt to contain the path to your client-library/_build/{platform} folder. The build script will then generate a redist.packman.xml file that contains the correct source-linking syntax.

Client Library Canary Builds

Any time a new build is published from the client library main branch, Team City will generate a usd-resolver ‘canary’ build that uses the new client library build. The scripts to do this are in tools/ci/update-client-library. Essentially it modifies omni-client-library.txt with the new version number, then commits that to a specially named branch. Team City will then build than branch and run the tests.

When a new release tag is pushed to the client library repo, the canary build process runs, and if all the tests are successful, Team City will automatically merge the change to use the new client library to the main branch of usd-resolver.

Branches & Merge Requests

The main branch is named “main”. Team City automatically builds all changes from this branch and publishes the artifacts to packman.

Do not submit anything directly to the “main” branch. Submit to a branch, then open a merge request. Prefer branches over forks.

Branches must be named either “feature/OM-1234” or “bugfix/OM-1234” where “OM-1234” is the Jira ticket. All changes must have an associated Jira ticket.

Testing

Tests can be ran locally by using ./run_tests.sh for Linux and run_tests.bat for Windows. Once you have all tests passing and an MR submitted, TeamCity will build / test on multiple platforms and different flavors of USD.

Once everything is passing in TeamCity you will probably want to vet larger changes against Kit. To do this you will first need to publish an artifact for your MR. This can be done through the Publish configuration in TeamCity. Find your MR branch and click Deploy. After this has run successfully the artifacts will then be published to Packman. The package should include a version for your MR number which can be found by navigating to any of the various flavors, i.e omni_usd_resolver.nv-20_08.py37.linux-x86_64@1.3.0-mr17.2893+tc.7c7c7349 refers to merge-requests/17.

Finally, to test your change in Kit you’ll want to update the rendering/deps/target-deps.packman.xml version to the version of your MR package. Following the previous example, this would be 1.3.0-mr17.2893+tc.7c7c7349. After all this is setup you can run Kit tests locally or submit a MR against integ-master

Versioning

The build scripts read the first line from CHANGELOG.md to determine the version number

The version number must be 3 numbers seperated by periods: {major}.{release}.{hotfix}

The major number must change if we make non-backwards-compatible changes. This is any change that causes previously-working code to no longer work. Please avoid making these kinds of changes.

The release number changes with every release (see below).

The hotfix number changes with every hotfix (see below).

Releases

We release a new version of the plugin periodically. We used to produce a new version number with every change, but it became extremely difficult to keep track of the version numbers. Releasing a new version consists of tagging the current main branch in git, then updating CHANGELOG.md with a new minor number.

Hot Fixes

If a fix needs to be back-ported to an older release:

  1. Create a branch from the original release tag named “hotfix/{major}.{release}”

  2. Make your changes and increase the “hotfix” number in CHANGELOG.md

  3. Create a branch named “bugfix/OM-1234-hotfix” and create a merge request into the hotfix branch.

  4. Merge once approved & pipelines pass

Team City will automatically build from the hotfix branch and publish the artifacts to team city.

The build number will look like: {major}.{release}.{hotfix}-hotfix.{build}+{builder}.{githash}

For example: 1.34.1-hotfix.2508+tc.fefefefefefefe