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:
#include <OmniClient.h>
(from client library)Create or open a “.live” file on an Omniverse server
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:
Create a branch from the original release tag named “hotfix/{major}.{release}”
Make your changes and increase the “hotfix” number in CHANGELOG.md
Create a branch named “bugfix/OM-1234-hotfix” and create a merge request into the hotfix branch.
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