All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Ar: Asset Resolution

Overview

The Ar (asset resolution) library provides functions for interacting with asset paths in USD. An asset path is a string that describes the location of an asset in a user's system. These paths are used extensively throughout USD; for example, asset paths are used to specify sublayers, references, and other composition arcs in scene description.

Ar's primary responsibility is to 'resolve' an asset path into a corresponding filesystem path. By default, Ar assumes that all asset paths are simple filesystem paths and treats them accordingly. However, clients may implement their own resolver class by implementing the ArResolver interface to provide custom resolution logic for asset paths. This allows clients to use asset paths that are appropriate for their situation.

For example, a client might have an asset management system that uses URLs to identify assets. That client could implement a custom resolver that would resolve those URLs and fetch data from a server to the local filesystem and return that filesystem path as the 'resolved' path. This would enable the client to use these URLs in scene description (e.g., for referencing) for USD.

Accessing the Resolver

Consumers may access the asset resolver by calling ArGetResolver.

Default Resolver

If no custom implementation of ArResolver is found, Ar will fall back to using an ArDefaultResolver, which assumes all asset paths it encounters are filesystem paths. ArDefaultResolver also performs simple search path-based resolution that will search for an asset in a specified list of directories. See documentation on ArDefaultResolver for more information on configuring this behavior.

Implementing a Custom Resolver

To implement a custom asset resolver, users must create a plugin containing a subclass of ArResolver. This subclass must be registered with the plugin system so that it can be discovered and instantiated at runtime. Keep in mind that the subclass may be constructed at any time; at a minimum, the subclass will be constructed during the first call to ArGetResolver.

  • Implement an ArResolver subclass
    class CustomResolver : public ArResolver {
    // ...
    }
  • In its implementation, register the ArResolver subclass with the TfType system using AR_DEFINE_RESOLVER
    # custom resolver's .cpp file
    AR_DEFINE_RESOLVER(CustomResolver, ArResolver);
  • Declare the ArResolver subclass in the plugin's plugInfo.json file. See PlugRegistry for more details.
    # plugInfo.json
    {
    "Plugins": [
    {
    "Info": {
    "Types" : {
    "CustomResolver" : {
    "bases": [ "ArResolver" ]
    }
    }
    },
    ...
    },
    ...
    ]
    }
  • Ensure that the resolver plugin is located where the plugin system can find it.
Note
Ar does not support custom resolvers implemented in Python to avoid performance issues, especially for multi-threaded consumers.

Resolver Context Objects

Each custom resolver can reason about its own ArResolverContext type, which allows a single process to access multiple different state-sets (contexts) to guide asset resolution differently for different datasets/contexts.

Users may declare that a particular object type may be used as a context object by using AR_DECLARE_RESOLVER_CONTEXT. This allows ArResolverContext objects to be constructed from objects of this type.

Resolver Scoped Caches

Since resolving assets to filesystem paths can be expensive, and typically clients (such as USD) will commonly attempt to resolve the same assets over and over again, we also provide an RAII ArResolverScopedCache that can greatly speed up asset resolution by caching results. See ArDefaultResolver for an example implementation.