This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
ArDefaultResolver Class Reference

Default asset resolution implementation used when no plugin implementation is provided. More...

#include <defaultResolver.h>

+ Inheritance diagram for ArDefaultResolver:

Static Public Member Functions

static AR_API void SetDefaultSearchPath (const std::vector< std::string > &searchPath)
 Set the default search path that will be used during asset resolution.
 

Protected Member Functions

AR_API std::string _CreateIdentifier (const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const override
 Return an identifier for the asset at the given assetPath.
 
AR_API std::string _CreateIdentifierForNewAsset (const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const override
 Return an identifier for a new asset at the given assetPath.
 
AR_API ArResolvedPath _Resolve (const std::string &assetPath) const override
 Return the resolved path for the given assetPath or an empty ArResolvedPath if no asset exists at that path.
 
AR_API ArResolvedPath _ResolveForNewAsset (const std::string &assetPath) const override
 Return the resolved path for the given assetPath that may be used to create a new asset or an empty ArResolvedPath if such a path cannot be computed.
 
AR_API ArResolverContext _CreateDefaultContext () const override
 Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified.
 
AR_API ArResolverContext _CreateDefaultContextForAsset (const std::string &assetPath) const override
 Creates a context that adds the directory containing assetPath as a first directory to be searched, when the resulting context is bound (.
 
AR_API ArResolverContext _CreateContextFromString (const std::string &contextStr) const override
 Creates an ArDefaultResolverContext from contextStr.
 
AR_API bool _IsContextDependentPath (const std::string &assetPath) const override
 Return true if the result of resolving the given assetPath may differ depending on the asset resolver context that is bound when Resolve is called, false otherwise.
 
AR_API ArTimestamp _GetModificationTimestamp (const std::string &path, const ArResolvedPath &resolvedPath) const override
 Return an ArTimestamp representing the last time the asset at assetPath was modified.
 
AR_API std::shared_ptr< ArAsset_OpenAsset (const ArResolvedPath &resolvedPath) const override
 Return an ArAsset object for the asset located at resolvedPath.
 
AR_API std::shared_ptr< ArWritableAsset_OpenAssetForWrite (const ArResolvedPath &resolvedPath, WriteMode writeMode) const override
 Creates an ArFilesystemWriteableAsset for the asset at the given resolvedPath.
 
- Protected Member Functions inherited from ArResolver
virtual AR_API bool _IsRepositoryPath (const std::string &path) const
 
virtual AR_API void _BindContext (const ArResolverContext &context, VtValue *bindingData)
 Bind the given context to this resolver.
 
virtual AR_API void _UnbindContext (const ArResolverContext &context, VtValue *bindingData)
 Unbind the given context from this resolver.
 
virtual AR_API void _RefreshContext (const ArResolverContext &context)
 Refresh any caches associated with the given context.
 
virtual AR_API ArResolverContext _GetCurrentContext () const
 Return the currently bound context.
 
virtual AR_API std::string _GetExtension (const std::string &assetPath) const
 Return the file extension for the given assetPath.
 
virtual AR_API ArAssetInfo _GetAssetInfo (const std::string &assetPath, const ArResolvedPath &resolvedPath) const
 Return an ArAssetInfo populated with additional metadata (if any) about the asset at the given assetPath.
 
virtual AR_API bool _CanWriteAssetToPath (const ArResolvedPath &resolvedPath, std::string *whyNot) const
 Return true if an asset may be written to the given resolvedPath, false otherwise.
 
virtual AR_API void _BeginCacheScope (VtValue *cacheScopeData)
 Mark the start of a resolution caching scope.
 
virtual AR_API void _EndCacheScope (VtValue *cacheScopeData)
 Mark the end of a resolution caching scope.
 
template<class ContextObj >
const ContextObj * _GetCurrentContextObject () const
 Returns a pointer to the context object of type ContextObj from the last ArResolverContext that was bound via a call to BindContext, or NULL if no context object of that type exists.
 

Additional Inherited Members

- Public Types inherited from ArResolver
enum class  WriteMode { Update = 0 , Replace }
 Enumeration of write modes for OpenAssetForWrite. More...
 
- Public Member Functions inherited from ArResolver
 ArResolver (const ArResolver &)=delete
 
ArResolveroperator= (const ArResolver &)=delete
 
AR_API std::string CreateIdentifier (const std::string &assetPath, const ArResolvedPath &anchorAssetPath=ArResolvedPath()) const
 Returns an identifier for the asset specified by assetPath.
 
AR_API std::string CreateIdentifierForNewAsset (const std::string &assetPath, const ArResolvedPath &anchorAssetPath=ArResolvedPath()) const
 Returns an identifier for a new asset specified by assetPath.
 
AR_API ArResolvedPath Resolve (const std::string &assetPath) const
 Returns the resolved path for the asset identified by the given assetPath if it exists.
 
AR_API ArResolvedPath ResolveForNewAsset (const std::string &assetPath) const
 Returns the resolved path for the given assetPath that may be used to create a new asset.
 
AR_API void BindContext (const ArResolverContext &context, VtValue *bindingData)
 Binds the given context to this resolver.
 
AR_API void UnbindContext (const ArResolverContext &context, VtValue *bindingData)
 Unbind the given context from this resolver.
 
AR_API ArResolverContext CreateDefaultContext () const
 Return an ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified.
 
AR_API ArResolverContext CreateDefaultContextForAsset (const std::string &assetPath) const
 Return an ArResolverContext that may be bound to this resolver to resolve the asset located at assetPath or referenced by that asset when no other context is explicitly specified.
 
AR_API ArResolverContext CreateContextFromString (const std::string &contextStr) const
 Return an ArResolverContext created from the primary ArResolver implementation using the given contextStr.
 
AR_API ArResolverContext CreateContextFromString (const std::string &uriScheme, const std::string &contextStr) const
 Return an ArResolverContext created from the ArResolver registered for the given uriScheme using the given contextStr.
 
AR_API ArResolverContext CreateContextFromStrings (const std::vector< std::pair< std::string, std::string > > &contextStrs) const
 Return an ArResolverContext created by combining the ArResolverContext objects created from the given contextStrs.
 
AR_API void RefreshContext (const ArResolverContext &context)
 Refresh any caches associated with the given context.
 
AR_API ArResolverContext GetCurrentContext () const
 Returns the asset resolver context currently bound in this thread.
 
AR_API bool IsContextDependentPath (const std::string &assetPath) const
 Returns true if assetPath is a context-dependent path, false otherwise.
 
AR_API void BeginCacheScope (VtValue *cacheScopeData)
 Mark the start of a resolution caching scope.
 
AR_API void EndCacheScope (VtValue *cacheScopeData)
 Mark the end of a resolution caching scope.
 
AR_API bool IsRepositoryPath (const std::string &path) const
 
AR_API std::string GetExtension (const std::string &assetPath) const
 Returns the file extension for the given assetPath.
 
AR_API ArAssetInfo GetAssetInfo (const std::string &assetPath, const ArResolvedPath &resolvedPath) const
 Returns an ArAssetInfo populated with additional metadata (if any) about the asset at the given assetPath.
 
AR_API ArTimestamp GetModificationTimestamp (const std::string &assetPath, const ArResolvedPath &resolvedPath) const
 Returns an ArTimestamp representing the last time the asset at assetPath was modified.
 
AR_API std::shared_ptr< ArAssetOpenAsset (const ArResolvedPath &resolvedPath) const
 Returns an ArAsset object for the asset located at resolvedPath.
 
AR_API std::shared_ptr< ArWritableAssetOpenAssetForWrite (const ArResolvedPath &resolvedPath, WriteMode writeMode) const
 Returns an ArWritableAsset object for the asset located at resolvedPath using the specified writeMode.
 
AR_API bool CanWriteAssetToPath (const ArResolvedPath &resolvedPath, std::string *whyNot=nullptr) const
 Returns true if an asset may be written to the given resolvedPath, false otherwise.
 

Detailed Description

Default asset resolution implementation used when no plugin implementation is provided.

In order to resolve assets specified by relative paths, this resolver implements a simple "search path" scheme. The resolver will anchor the relative path to a series of directories and return the first absolute path where the asset exists.

The first directory will always be the current working directory. The resolver will then examine the directories specified via the following mechanisms (in order):

The environment variable PXR_AR_DEFAULT_SEARCH_PATH may be used to specify an inital search path value. This is expected to be a list of directories delimited by the platform's standard path separator. A search path specified in this manner is overwritten by any call to ArDefaultResolver::SetDefaultSearchPath.

ArDefaultResolver supports creating an ArDefaultResolverContext via ArResolver::CreateContextFromString by passing a list of directories delimited by the platform's standard path separator.

Definition at line 50 of file defaultResolver.h.

Member Function Documentation

◆ _CreateContextFromString()

AR_API ArResolverContext _CreateContextFromString ( const std::string &  contextStr) const
overrideprotectedvirtual

Creates an ArDefaultResolverContext from contextStr.

This string is expected to be a list of directories delimited by the platform's standard path separator.

Reimplemented from ArResolver.

◆ _CreateDefaultContext()

AR_API ArResolverContext _CreateDefaultContext ( ) const
overrideprotectedvirtual

Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified.

When CreateDefaultContext is called on the configured asset resolver, Ar will call this method on the primary resolver and all URI/IRI resolvers and merge the results into a single ArResolverContext that will be returned to the consumer.

This function should not automatically bind this context, but should create one that may be used later.

The default implementation returns a default-constructed ArResolverContext.

Example uses:

  • UsdStage will call CreateDefaultContext when creating a new stage with an anonymous root layer and without a given context. The returned context will be bound when resolving asset paths on that stage.

Reimplemented from ArResolver.

◆ _CreateDefaultContextForAsset()

AR_API ArResolverContext _CreateDefaultContextForAsset ( const std::string &  assetPath) const
overrideprotectedvirtual

Creates a context that adds the directory containing assetPath as a first directory to be searched, when the resulting context is bound (.

See also
ArResolverContextBinder).

If assetPath is empty, returns an empty context; otherwise, if assetPath is not an absolute filesystem path, it will first be anchored to the process's current working directory.

Reimplemented from ArResolver.

◆ _CreateIdentifier()

AR_API std::string _CreateIdentifier ( const std::string &  assetPath,
const ArResolvedPath anchorAssetPath 
) const
overrideprotectedvirtual

Return an identifier for the asset at the given assetPath.

See Identifiers for more information.

If anchorAssetPath is non-empty, it should be used as the anchoring asset if assetPath is relative. For example, for a filesystem-based implementation _CreateIdentifier might return:

_CreateIdentifier( /* assetPath = ‍/ "/abs/path/to/model.usd", / anchorAssetPath = *‍/ ArResolvedPath("/abs/path/to/shot.usd")) => "/abs/path/to/model.usd"

_CreateIdentifier( /* assetPath = ‍/ "relative/model.usd", / anchorAssetPath = *‍/ ArResolvedPath("/abs/path/to/shot.usd")) => "/abs/path/to/relative/model.usd"

Identifiers may be compared to determine if given paths refer to the same asset, so implementations should take care to canonicalize and normalize the returned identifier to a consistent format.

If either assetPath or anchorAssetPath have a URI/IRI scheme, this function will be called on the resolver associated with that URI/IRI scheme, if any.

Example uses:

  • When opening a layer via SdfLayer::FindOrOpen or Find, CreateIdentifier will be called with the asset path given to those functions and no anchoring asset path. The result will be used as the layer's identifier.
  • When processing composition arcs that refer to other layers, this function will be called with the asset path of the referenced layer and the resolved path of the layer where the composition arc was authored. The result will be passed to SdfLayer::FindOrOpen to open the referenced layer.

Implements ArResolver.

◆ _CreateIdentifierForNewAsset()

AR_API std::string _CreateIdentifierForNewAsset ( const std::string &  assetPath,
const ArResolvedPath anchorAssetPath 
) const
overrideprotectedvirtual

Return an identifier for a new asset at the given assetPath.

This is similar to _CreateIdentifier but is used to create identifiers for assets that may not exist yet and are being created.

Example uses:

  • When creating a new layer via SdfLayer::CreateNew, CreateIdentifierForNewAsset will be called with the asset path given to the function. The result will be used as the new layer's identifier.

Implements ArResolver.

◆ _GetModificationTimestamp()

AR_API ArTimestamp _GetModificationTimestamp ( const std::string &  assetPath,
const ArResolvedPath resolvedPath 
) const
overrideprotectedvirtual

Return an ArTimestamp representing the last time the asset at assetPath was modified.

resolvedPath is the resolved path computed for the given assetPath. If a timestamp cannot be retrieved, return an invalid ArTimestamp.

The default implementation returns an invalid ArTimestamp.

Example uses:

  • SdfLayer will call GetModificationTimestamp when opening a layer and store the returned timestamp. When SdfLayer::Reload is called on that layer, this method will be called again. If the returned timestamp differs from the stored timestamp, or if it is invalid, the layer will be reloaded.

Reimplemented from ArResolver.

◆ _IsContextDependentPath()

AR_API bool _IsContextDependentPath ( const std::string &  assetPath) const
overrideprotectedvirtual

Return true if the result of resolving the given assetPath may differ depending on the asset resolver context that is bound when Resolve is called, false otherwise.

The default implementation returns false.

Example uses:

  • SdfLayer will call this function to check if the identifier given to SdfLayer::Find or SdfLayer::FindOrOpen is context-dependent. If it is and a layer exists with the same identifier, SdfLayer can return it without resolving the identifier. If it is not, SdfLayer must resolve the identifier and search for a layer with the same resolved path, even if a layer exists with the same identifier.

Reimplemented from ArResolver.

◆ _OpenAsset()

AR_API std::shared_ptr< ArAsset > _OpenAsset ( const ArResolvedPath resolvedPath) const
overrideprotectedvirtual

Return an ArAsset object for the asset located at resolvedPath.

Return an invalid std::shared_ptr if object could not be created (for example, if the asset at the given path could not be opened).

Note that clients may still be using the data associated with this object even after the last shared_ptr has been destroyed. For example, a client may have created a memory mapping using the FILE* presented in the ArAsset object; this would preclude truncating or overwriting any of the contents of that file.

Implements ArResolver.

◆ _OpenAssetForWrite()

AR_API std::shared_ptr< ArWritableAsset > _OpenAssetForWrite ( const ArResolvedPath resolvedPath,
WriteMode  writeMode 
) const
overrideprotectedvirtual

Creates an ArFilesystemWriteableAsset for the asset at the given resolvedPath.

Implements ArResolver.

◆ _Resolve()

AR_API ArResolvedPath _Resolve ( const std::string &  assetPath) const
overrideprotectedvirtual

Return the resolved path for the given assetPath or an empty ArResolvedPath if no asset exists at that path.

Implements ArResolver.

◆ _ResolveForNewAsset()

AR_API ArResolvedPath _ResolveForNewAsset ( const std::string &  assetPath) const
overrideprotectedvirtual

Return the resolved path for the given assetPath that may be used to create a new asset or an empty ArResolvedPath if such a path cannot be computed.

Implements ArResolver.

◆ SetDefaultSearchPath()

static AR_API void SetDefaultSearchPath ( const std::vector< std::string > &  searchPath)
static

Set the default search path that will be used during asset resolution.

Calling this function will trigger a ResolverChanged notification to be sent if the search path differs from the currently set default value.

The inital search path may be specified using via the environment variable PXR_AR_DEFAULT_SEARCH_PATH. Calling this function will override any path specified in this manner.

This function is not thread-safe and should not be called concurrently with any other ArResolver operations


The documentation for this class was generated from the following file: