Wrapper File Format

When GetExtension is called on the Omniverse USD resolver, and the path is a non-local USD layer (ie: a layer which exists either on an Omniverse server, or an HTTP/S3 server), the resolver returns the file extension “.omni”. This triggers USD to load (or save) the file using the OmniUsdWrapperFileFormat

The wrapper file format delegates almost all behavior to the underlying file format, with 2 major exceptions: 1. Read will first download the file to a temporary location, then direct the underlying format to read from that. 2. Write will direct the underlying file format to write to a temporary location, then uses omniClientMove to “move” it to the remote server (essentially just a copy + delete)


There are a lot of hacks to get this to work correctly in all cases.

This entire concept

This entire class only exists because USD can only read/write to real files on disk. This changes with Ar 2.0 (which abstracts file reading/writing), at which point all this code can be deleted.

Stashing Info Inside Args

We need to know the original extension, path, version, asset name, and repo path. We stash all of this information in the file format args during InitData.

Creating an anonymous “wrapped layer”

In order to instantiate the correct SdfAbstractData, and be able to call Read/Write on the underlying file format, we must provide a layer. We cannot provide the real layer, because the file format will most likely call layer->SetData (which would override our own “OmniUsdWrapperData”), so we must create an anonymous layer.


USD versions prior to 21.08 had the InstantiateNewLayer function marked as private. We have an extremely dangerous hack to extract that function from the vtable, cast it to the correct type, and call it.


When using “OpenAsAnonymous” the wrapper format doesn’t know the underyling format (because the path is empty), so we use a “dummy file format” and defer determining the real format until Read is called for the first time (at which point we know the extension of the underlying file, and therefore the file format).