All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
ArResolver Class Referenceabstract

Interface for the asset resolution system. More...

#include <resolver.h>

+ Inheritance diagram for ArResolver:

Public Member Functions

 ArResolver (const ArResolver &)=delete
 
ArResolveroperator= (const ArResolver &)=delete
 
Identifiers

Identifiers are canonicalized asset paths that may be assigned to a logical asset to facilitate comparisons and lookups. They may be used to determine if different asset paths might refer to the same asset without performing resolution.

Since identifiers are just a form of asset path, they may be used with other functions on ArResolver that require an asset path, like Resolve.

If two asset paths produce the same identifier, those asset paths must refer to the same asset. However, in some cases comparing identifiers may not be sufficient to determine if assets are equal. For example, there could be two assets with the same identifier but whose contents were read from different resolved paths because different resolver contexts were bound when those assets were loaded.

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.
 
Path Resolution Operations

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.
 
Asset Resolver Context Operations

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.
 
Scoped Resolution Cache

A scoped resolution cache indicates to the resolver that results of calls to Resolve should be cached for a certain scope. This is important for performance and also for consistency – it ensures that repeated calls to Resolve with the same parameters will return the same result.

A resolution cache scope is opened by a call to BeginCacheScope and must be closed with a matching call to EndCacheScope. The resolver must cache the results of Resolve until the scope is closed. Note that these calls may be nested.

Cache scopes are thread-specific: if multiple threads are running and a cache scope is opened in one of those threads, caching should be enabled in that thread only.

When opening a scope, a resolver may return additional data for implementation-specific purposes. This data may be shared across threads, so long as it is safe to access this data concurrently.

ArResolverScopedCache is an RAII object for managing cache scope lifetimes and data. Clients should generally use that class rather than calling the BeginCacheScope and EndCacheScope functions manually.

See also
ArResolverScopedCache
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.
 
Deprecated APIs

The functions in this section are deprecated in Ar 2.0 and slated for removal. Most have default implementations to allow subclasses to ignore them completely.

AR_API bool IsRepositoryPath (const std::string &path) const
 

Protected Member Functions

virtual AR_API bool _IsRepositoryPath (const std::string &path) const
 
Implementation

virtual std::string _CreateIdentifier (const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const =0
 Return an identifier for the asset at the given assetPath.
 
virtual std::string _CreateIdentifierForNewAsset (const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const =0
 Return an identifier for a new asset at the given assetPath.
 
virtual ArResolvedPath _Resolve (const std::string &assetPath) const =0
 Return the resolved path for the given assetPath or an empty ArResolvedPath if no asset exists at that path.
 
virtual ArResolvedPath _ResolveForNewAsset (const std::string &assetPath) const =0
 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.
 
Context Operations Implementation

If any of these functions are implemented in a subclass, the plugin metadata for that subclass in the plugin library's plugInfo.json must specify:

"implementsContexts" : true.

If a subclass indicates that it implements any of these functions, its plugin library will be loaded and these functions will be called when the corresponding public ArResolver API is called. Otherwise, these functions will not be called.

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 ArResolverContext _CreateDefaultContext () const
 Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified.
 
virtual 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.
 
virtual AR_API ArResolverContext _CreateContextFromString (const std::string &contextStr) const
 Return an ArResolverContext created from the given contextStr.
 
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 bool _IsContextDependentPath (const std::string &assetPath) const
 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.
 
Asset Operations Implementation

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 ArTimestamp _GetModificationTimestamp (const std::string &assetPath, const ArResolvedPath &resolvedPath) const
 Return an ArTimestamp representing the last time the asset at assetPath was modified.
 
virtual AR_API std::shared_ptr< ArAsset_OpenAsset (const ArResolvedPath &resolvedPath) const =0
 Return an ArAsset object for the asset located at resolvedPath.
 
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 std::shared_ptr< ArWritableAsset_OpenAssetForWrite (const ArResolvedPath &resolvedPath, WriteMode writeMode) const =0
 Return an ArWritableAsset object for the asset at resolvedPath using the specified writeMode.
 
Scoped Resolution Cache Implementation

If any of these functions are implemented in a subclass, the plugin metadata for that subclass in the plugin library's plugInfo.json must specify:

"implementsScopedCaches" : true.

If a subclass indicates that it implements these functions, ArResolver will assume the subclass is handling all caching of resolved paths and will call these functions when a caching scope is opened and closed. Otherwise, these functions will not be called. Instead, ArResolver itself will handle caching and returning resolved paths as needed.

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.
 
Implementation Utilities

Utility functions for implementations.

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.
 

File/asset-specific Operations

enum class  WriteMode { Update = 0 , Replace }
 Enumeration of write modes for OpenAssetForWrite. More...
 
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

Interface for the asset resolution system.

An asset resolver is responsible for resolving asset information (including the asset's physical path) from a logical path.

See ar_implementing_resolver for information on how to customize asset resolution behavior by implementing a subclass of ArResolver. Clients may use ArGetResolver to access the configured asset resolver.

Definition at line 42 of file resolver.h.

Member Enumeration Documentation

◆ WriteMode

enum class WriteMode
strong

Enumeration of write modes for OpenAssetForWrite.

Enumerator
Update 

Open asset for in-place updates.

If the asset exists, its contents will not be discarded and writes may overwrite existing data. Otherwise, the asset will be created.

Replace 

Open asset for replacement.

If the asset exists, its contents will be discarded by the time the ArWritableAsset is destroyed. Otherwise, the asset will be created.

Definition at line 294 of file resolver.h.

Member Function Documentation

◆ _BeginCacheScope()

virtual AR_API void _BeginCacheScope ( VtValue cacheScopeData)
protectedvirtual

Mark the start of a resolution caching scope.

Resolvers may fill cacheScopeData with arbitrary data. Clients may also pass in a cacheScopeData populated by an earlier call to BeginCacheScope to allow the resolver access to that information.

See Scoped Resolution Cache Implementation for more implementation details.

◆ _BindContext()

virtual AR_API void _BindContext ( const ArResolverContext context,
VtValue bindingData 
)
protectedvirtual

Bind the given context to this resolver.

bindingData may be populated with additional information that will be kept alive while context is bound. Both context and bindingData will be passed to UnbindContext when the context is being unbound.

Contexts may be nested; if multiple contexts are bound, the context that was most recently bound must take precedence and block all previously bound contexts.

Context binding is thread-specific; contexts bound in a thread must only affect other resolver calls in the same thread.

ArResolver itself manages thread-local stacks of bound contexts. Subclasses can retrieve the most recent context object which was passed to BindContext using _GetCurrentContextObject. Because of this, subclasses typically do not need to implement this function unless they need to be informed when a context object is bound. For example, this may be needed if the context needs to be passed on to another subsystem that manages these bindings itself.

The default implementation does nothing.

◆ _CanWriteAssetToPath()

virtual AR_API bool _CanWriteAssetToPath ( const ArResolvedPath resolvedPath,
std::string *  whyNot 
) const
protectedvirtual

Return true if an asset may be written to the given resolvedPath, false otherwise.

If this function returns false and whyNot is not nullptr, it may be filled with an explanation. The default implementation returns true.

◆ _CreateContextFromString()

virtual AR_API ArResolverContext _CreateContextFromString ( const std::string &  contextStr) const
protectedvirtual

Return an ArResolverContext created from the given contextStr.

The default implementation returns a default-constructed ArResolverContext.

Reimplemented in ArDefaultResolver.

◆ _CreateDefaultContext()

virtual AR_API ArResolverContext _CreateDefaultContext ( ) const
protectedvirtual

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 in ArDefaultResolver.

◆ _CreateDefaultContextForAsset()

virtual AR_API ArResolverContext _CreateDefaultContextForAsset ( const std::string &  assetPath) const
protectedvirtual

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.

When CreateDefaultContextForAsset 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.

Note that this means this method may be called with asset paths that are not associated with this resolver. For example, this method may be called on a URI/IRI resolver with a non-URI/IRI asset path. This is to support cases where the asset at assetPath references other assets with URI/IRI schemes that differ from the URI/IRI scheme (if any) in assetPath.

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 CreateDefaultContextForAsset when creating a new stage with a non-anonymous root layer and without a given context. The resolved path of the root layer will be passed in as the assetPath. The returned context will be bound when resolving asset paths on that stage.

Reimplemented in ArDefaultResolver.

◆ _CreateIdentifier()

virtual std::string _CreateIdentifier ( const std::string &  assetPath,
const ArResolvedPath anchorAssetPath 
) const
protectedpure virtual

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.

Implemented in ArDefaultResolver.

◆ _CreateIdentifierForNewAsset()

virtual std::string _CreateIdentifierForNewAsset ( const std::string &  assetPath,
const ArResolvedPath anchorAssetPath 
) const
protectedpure virtual

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.

Implemented in ArDefaultResolver.

◆ _EndCacheScope()

virtual AR_API void _EndCacheScope ( VtValue cacheScopeData)
protectedvirtual

Mark the end of a resolution caching scope.

cacheScopeData should contain the data that was populated by the previous corresponding call to BeginCacheScope.

See Scoped Resolution Cache Implementation for more implementation details.

◆ _GetAssetInfo()

virtual AR_API ArAssetInfo _GetAssetInfo ( const std::string &  assetPath,
const ArResolvedPath resolvedPath 
) const
protectedvirtual

Return an ArAssetInfo populated with additional metadata (if any) about the asset at the given assetPath.

resolvedPath is the resolved path computed for the given assetPath. The default implementation returns a default-constructed ArAssetInfo.

◆ _GetCurrentContext()

virtual AR_API ArResolverContext _GetCurrentContext ( ) const
protectedvirtual

Return the currently bound context.

Since context binding is thread-specific, this should return the context that was most recently bound in this thread.

Subclasses typically do not need to implement this function since ArResolver itself keeps track of the contexts that are bound via calls to BindContext. However, if a subclass is managing bound contexts itself and allows clients to bind context objects via other API outside of BindContext, this function should return the context object as described above. This typically happens with subclasses that are wrappers around other resolution subsystems.

See also
_BindContext for more information.

The default implementation returns a default-constructed ArResolverContext.

◆ _GetCurrentContextObject()

const ContextObj * _GetCurrentContextObject ( ) const
inlineprotected

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.

Typically, a subclass might use this in their _Resolve function to get the currently bound context to drive their resolution behavior.

if (const MyContextObject* ctx =
_GetCurrentContextObject<MyContextObject>()) {
// Use information in ctx to resolve given path
}
else {
// Resolve given path with no context object
}

This is the same as GetCurrentContext().Get<ContextObj>() but more efficient, since it does not make a copy of the ArResolverContext. However, it is not the same as _GetCurrentContext().Get<ContextObj>(). Subclasses that manage context binding themselves may have overridden _GetCurrentContext to return a context that was bound without calling BindContext. These subclasses should not use this function and should retrieve the current context from their own internal data structures.

Definition at line 826 of file resolver.h.

◆ _GetExtension()

virtual AR_API std::string _GetExtension ( const std::string &  assetPath) const
protectedvirtual

Return the file extension for the given assetPath.

This extension should not include a "." at the beginning of the string.

The default implementation returns the string after the last "." in assetPath. If assetPath begins with a ".", the extension will be empty unless there is another "." in the path. If assetPath has components separated by '/' (or '\' on Windows), only the last component will be considered.

◆ _GetModificationTimestamp()

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

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 in ArDefaultResolver.

◆ _IsContextDependentPath()

virtual AR_API bool _IsContextDependentPath ( const std::string &  assetPath) const
protectedvirtual

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 in ArDefaultResolver.

◆ _IsRepositoryPath()

virtual AR_API bool _IsRepositoryPath ( const std::string &  path) const
protectedvirtual
Deprecated:
Return true if the given path is a repository path, false otherwise. Default implementation returns false.

◆ _OpenAsset()

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

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.

Implemented in ArDefaultResolver.

◆ _OpenAssetForWrite()

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

Return an ArWritableAsset object for the asset at resolvedPath using the specified writeMode.

Return an invalid std::shared_ptr if object could not be created (for example, if writing to the given path is not allowed).

Implementations should create any parent paths that are necessary to write this asset. The returned ArWritableAsset must obey the behaviors for the given writeMode, see the documentation for the WriteMode enum for more details.

Implemented in ArDefaultResolver.

◆ _RefreshContext()

virtual AR_API void _RefreshContext ( const ArResolverContext context)
protectedvirtual

Refresh any caches associated with the given context.

If doing so would invalidate asset paths that had previously been resolved, this function should send an ArNotice::ResolverChanged notice to inform clients of this. See documentation on that class for more details.

The default implementation does nothing.

◆ _Resolve()

virtual ArResolvedPath _Resolve ( const std::string &  assetPath) const
protectedpure virtual

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

Implemented in ArDefaultResolver.

◆ _ResolveForNewAsset()

virtual ArResolvedPath _ResolveForNewAsset ( const std::string &  assetPath) const
protectedpure virtual

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.

Implemented in ArDefaultResolver.

◆ _UnbindContext()

virtual AR_API void _UnbindContext ( const ArResolverContext context,
VtValue bindingData 
)
protectedvirtual

Unbind the given context from this resolver.

It is an error if the context being unbound is not the currently bound context.

Subclasses typically do not need to implement this function since ArResolver itself keeps track of the contexts that are bound via calls to BindContext. However, subclasses may need to implement this function if they are managing these bindings itself.

The default implementation does nothing.

◆ BeginCacheScope()

AR_API void BeginCacheScope ( VtValue cacheScopeData)

Mark the start of a resolution caching scope.

Clients should generally use ArResolverScopedCache instead of calling this function directly.

Resolvers may fill cacheScopeData with arbitrary data. Clients may also pass in a cacheScopeData populated by an earlier call to BeginCacheScope to allow the resolver access to that information.

See also
ArResolverScopedCache

◆ BindContext()

AR_API void BindContext ( const ArResolverContext context,
VtValue bindingData 
)

Binds the given context to this resolver.

Clients should generally use ArResolverContextBinder instead of calling this function directly.

See also
ArResolverContextBinder

◆ CanWriteAssetToPath()

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.

If this function returns false and whyNot is not nullptr, it may be filled with an explanation.

◆ CreateContextFromString() [1/2]

AR_API ArResolverContext CreateContextFromString ( const std::string &  contextStr) const

Return an ArResolverContext created from the primary ArResolver implementation using the given contextStr.

◆ CreateContextFromString() [2/2]

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.

An empty uriScheme indicates the primary resolver and is equivalent to CreateContextFromString(string).

If no resolver is registered for uriScheme, returns an empty ArResolverContext.

Note
'uriScheme' can be used to register IRI resolvers

◆ CreateContextFromStrings()

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.

contextStrs is a list of pairs of strings. The first element in the pair is the URI/IRI scheme for the ArResolver that will be used to create the ArResolverContext from the second element in the pair. An empty resource identifier scheme indicates the primary resolver.

For example:

{ {"", "context str 1"},
{"my-scheme", "context str 2"} });
AR_API ArResolver & ArGetResolver()
Returns the configured asset resolver.
An asset resolver context allows clients to provide additional data to the resolver for use during re...
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...

This will use the primary resolver to create an ArResolverContext using the string "context str 1" and use the resolver registered for the "my-scheme" URI/IRI scheme to create an ArResolverContext using "context str 2". These contexts will be combined into a single ArResolverContext and returned.

If no resolver is registered for a URI/IRI scheme in an entry in contextStrs, that entry will be ignored.

◆ CreateDefaultContext()

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.

The returned ArResolverContext will contain the default context returned by the primary resolver and all URI/IRI resolvers.

◆ CreateDefaultContextForAsset()

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.

The returned ArResolverContext will contain the default context for assetPath returned by the primary resolver and all URI/IRI resolvers.

◆ CreateIdentifier()

AR_API std::string CreateIdentifier ( const std::string &  assetPath,
const ArResolvedPath anchorAssetPath = ArResolvedPath() 
) const

Returns an identifier for the asset specified by assetPath.

If anchorAssetPath is not empty, it is the resolved asset path that assetPath should be anchored to if it is a relative path.

◆ CreateIdentifierForNewAsset()

AR_API std::string CreateIdentifierForNewAsset ( const std::string &  assetPath,
const ArResolvedPath anchorAssetPath = ArResolvedPath() 
) const

Returns an identifier for a new asset specified by assetPath.

If anchorAssetPath is not empty, it is the resolved asset path that assetPath should be anchored to if it is a relative path.

◆ EndCacheScope()

AR_API void EndCacheScope ( VtValue cacheScopeData)

Mark the end of a resolution caching scope.

Clients should generally use ArResolverScopedCache instead of calling this function directly.

cacheScopeData should contain the data that was populated by the previous corresponding call to BeginCacheScope.

See also
ArResolverScopedCache

◆ GetAssetInfo()

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.

resolvedPath is the resolved path computed for the given assetPath.

◆ GetCurrentContext()

AR_API ArResolverContext GetCurrentContext ( ) const

Returns the asset resolver context currently bound in this thread.

See also
ArResolver::BindContext, ArResolver::UnbindContext

◆ GetExtension()

AR_API std::string GetExtension ( const std::string &  assetPath) const

Returns the file extension for the given assetPath.

The returned extension does not include a "." at the beginning.

◆ GetModificationTimestamp()

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.

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

◆ IsContextDependentPath()

AR_API bool IsContextDependentPath ( const std::string &  assetPath) const

Returns true if assetPath is a context-dependent path, false otherwise.

A context-dependent path may result in different resolved paths depending on what asset resolver context is bound when Resolve is called. Assets located at the same context-dependent path may not be the same since those assets may have been loaded from different resolved paths. In this case, the assets' resolved paths must be consulted to determine if they are the same.

◆ IsRepositoryPath()

AR_API bool IsRepositoryPath ( const std::string &  path) const
Deprecated:
Returns true if the given path is a repository path.

◆ OpenAsset()

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

Returns an ArAsset object for the asset located at resolvedPath.

Returns an invalid std::shared_ptr if object could not be created.

The returned ArAsset object provides functions for accessing the contents of the specified asset.

◆ OpenAssetForWrite()

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

Returns an ArWritableAsset object for the asset located at resolvedPath using the specified writeMode.

Returns an invalid std::shared_ptr if object could not be created.

The returned ArWritableAsset object provides functions for writing data to the specified asset.

Note that support for reading an asset through other APIs while it is open for write is implementation-specific. For example, writes to an asset may or may not be immediately visible to other threads or processes depending on the implementation.

◆ RefreshContext()

AR_API void RefreshContext ( const ArResolverContext context)

Refresh any caches associated with the given context.

If doing so would invalidate asset paths that had previously been resolved, an ArNotice::ResolverChanged notice will be sent to inform clients of this.

Avoid calling RefreshContext() on the same context from more than one thread concurrently as ArNotice::ResolverChanged notice listeners may mutate their state in response to receiving the notice.

Avoid calling RefreshContext() with a context that is active (bound to a resolver). Unbind the context before refreshing it.

See also
Threading Model and Performance Considerations

◆ Resolve()

AR_API ArResolvedPath Resolve ( const std::string &  assetPath) const

Returns the resolved path for the asset identified by the given assetPath if it exists.

If the asset does not exist, returns an empty ArResolvedPath.

◆ ResolveForNewAsset()

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.

If such a path cannot be computed for assetPath, returns an empty ArResolvedPath.

Note that an asset might or might not already exist at the returned resolved path.

◆ UnbindContext()

AR_API void UnbindContext ( const ArResolverContext context,
VtValue bindingData 
)

Unbind the given context from this resolver.

Clients should generally use ArResolverContextBinder instead of calling this function directly.

See also
ArResolverContextBinder

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