Interface for the asset resolution system. More...
Public Member Functions | |
ArResolver (const ArResolver &)=delete | |
ArResolver & | operator= (const ArResolver &)=delete |
Path Resolution Operations | |
virtual AR_API void | ConfigureResolverForAsset (const std::string &path)=0 |
Configures the resolver for a given asset path. More... | |
virtual AR_API std::string | AnchorRelativePath (const std::string &anchorPath, const std::string &path)=0 |
Returns the path formed by anchoring path to anchorPath . More... | |
virtual AR_API bool | IsRelativePath (const std::string &path)=0 |
Returns true if the given path is a relative path. More... | |
virtual AR_API bool | IsRepositoryPath (const std::string &path)=0 |
Returns true if the given path is a repository path. More... | |
virtual AR_API bool | IsSearchPath (const std::string &path)=0 |
Returns whether this path is a search path. More... | |
virtual AR_API std::string | GetExtension (const std::string &path)=0 |
Returns the normalized extension for the given path . More... | |
virtual AR_API std::string | ComputeNormalizedPath (const std::string &path)=0 |
Returns a normalized version of the given path . More... | |
virtual AR_API std::string | ComputeRepositoryPath (const std::string &path)=0 |
Returns the computed repository path using the current resolver. More... | |
virtual AR_API std::string | ComputeLocalPath (const std::string &path)=0 |
Returns the local path for the given path . More... | |
virtual AR_API std::string | Resolve (const std::string &path)=0 |
Returns the resolved filesystem path for the file identified by the given path if it exists. More... | |
Asset Resolver Context Operations | |
virtual AR_API void | BindContext (const ArResolverContext &context, VtValue *bindingData)=0 |
Binds the given context to this resolver. More... | |
virtual AR_API void | UnbindContext (const ArResolverContext &context, VtValue *bindingData)=0 |
Unbind the given context from this resolver. More... | |
virtual AR_API ArResolverContext | CreateDefaultContext ()=0 |
Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified. More... | |
virtual AR_API ArResolverContext | CreateDefaultContextForAsset (const std::string &filePath)=0 |
Return a default ArResolverContext that may be bound to this resolver to resolve the asset located at filePath when no other context is explicitly specified. More... | |
virtual AR_API void | RefreshContext (const ArResolverContext &context)=0 |
Refresh any caches associated with the given context. More... | |
virtual AR_API ArResolverContext | GetCurrentContext ()=0 |
Returns the currently-bound asset resolver context. More... | |
File/asset-specific Operations | |
virtual AR_API std::string | ResolveWithAssetInfo (const std::string &path, ArAssetInfo *assetInfo)=0 |
Returns the resolved filesystem path for the file identified by path following the same path resolution behavior as in Resolve(const std::string&). More... | |
virtual AR_API void | UpdateAssetInfo (const std::string &identifier, const std::string &filePath, const std::string &fileVersion, ArAssetInfo *assetInfo)=0 |
Update assetInfo with respect to the given fileVersion . More... | |
virtual AR_API VtValue | GetModificationTimestamp (const std::string &path, const std::string &resolvedPath)=0 |
Returns a value representing the last time the asset identified by path was modified. More... | |
virtual AR_API bool | FetchToLocalResolvedPath (const std::string &path, const std::string &resolvedPath)=0 |
Fetch the asset identified by path to the filesystem location specified by resolvedPath . More... | |
virtual AR_API std::shared_ptr < ArAsset > | OpenAsset (const std::string &resolvedPath)=0 |
Returns an ArAsset object for the asset located at resolvedPath . More... | |
virtual AR_API bool | CreatePathForLayer (const std::string &path)=0 |
Create path needed to write a file to the given path . More... | |
virtual AR_API bool | CanWriteLayerToPath (const std::string &path, std::string *whyNot)=0 |
Returns true if a file may be written to the given path , false otherwise. More... | |
virtual AR_API bool | CanCreateNewLayerWithIdentifier (const std::string &identifier, std::string *whyNot)=0 |
Returns true if a new file may be created using the given identifier , false otherwise. More... | |
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.
| |
virtual AR_API void | BeginCacheScope (VtValue *cacheScopeData)=0 |
Mark the start of a resolution caching scope. More... | |
virtual AR_API void | EndCacheScope (VtValue *cacheScopeData)=0 |
Mark the end of a resolution caching scope. More... | |
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 57 of file resolver_v1.h.
|
pure virtual |
Returns the path formed by anchoring path
to anchorPath
.
If anchorPath
ends with a trailing '/', it is treated as a directory to which path
will be anchored. Otherwise, it is treated as a file and path
will be anchored to its containing directory.
If anchorPath
is empty, path
will be returned as-is.
If path
is empty or not a relative path, it will be returned as-is.
Implemented in ArDefaultResolver.
|
pure virtual |
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.
Implemented in ArDefaultResolver.
|
pure virtual |
Binds the given context to this resolver.
Clients should generally use ArResolverContextBinder instead of calling this function directly.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns true if a new file may be created using the given identifier
, false otherwise.
If this function returns false and whyNot
is not nullptr
, it will be filled in with an explanation.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns true if a file may be written to the given path
, false otherwise.
In practice, when writing a layer, CanWriteLayerToPath will be called first to check if writing is permitted. If this returns true, then CreatePathForLayer will be called before writing the layer out.
If this function returns false and whyNot
is not nullptr
, it will be filled in with an explanation.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns the local path for the given path
.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns a normalized version of the given path
.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns the computed repository path using the current resolver.
Implemented in ArDefaultResolver.
|
pure virtual |
Configures the resolver for a given asset path.
Implemented in ArDefaultResolver.
|
pure virtual |
Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other context is explicitly specified.
This function should not automatically bind this context, but should create one that may be used later.
Implemented in ArDefaultResolver.
|
pure virtual |
Return a default ArResolverContext that may be bound to this resolver to resolve the asset located at filePath
when no other context is explicitly specified.
This function should not automatically bind this context, but should create one that may be used later.
Implemented in ArDefaultResolver.
|
pure virtual |
Create path needed to write a file to the given path
.
For example:
path
.In practice, when writing a layer, CanWriteLayerToPath will be called first to check if writing is permitted. If this returns true, then CreatePathForLayer will be called before writing the layer out.
Returns true on success, false otherwise.
Implemented in ArDefaultResolver.
|
pure virtual |
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.
Implemented in ArDefaultResolver.
|
pure virtual |
Fetch the asset identified by path
to the filesystem location specified by resolvedPath
.
resolvedPath
is the resolved path that results from calling Resolve or ResolveWithAssetInfo on path
.
This method provides a way for consumers that expect assets to exist as physical files on disk to retrieve data from systems that store data in external data stores, e.g. databases, etc.
Returns true if the asset was successfully fetched to the specified resolvedPath
or if no fetching was required. If resolvedPath
is not a local path or the asset could not be fetched to that path, returns false.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns the currently-bound asset resolver context.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns the normalized extension for the given path
.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns a value representing the last time the asset identified by path
was modified.
resolvedPath
is the resolved path of the asset.
Implementations may use whatever value is most appropriate for this timestamp. The value must be equality comparable, and this function must return a different timestamp whenever an asset has been modified. For instance, if an asset is stored as a file on disk, the timestamp may simply be that file's mtime.
If a timestamp cannot be retrieved, returns an empty VtValue.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns true if the given path is a relative path.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns true if the given path is a repository path.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns whether this path is a search path.
Implemented in ArDefaultResolver.
|
pure virtual |
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.
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.
|
pure virtual |
Refresh any caches associated with the given context.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns the resolved filesystem path for the file identified by the given path
if it exists.
If the file does not exist, returns an empty string.
Implemented in ArDefaultResolver.
|
pure virtual |
Returns the resolved filesystem path for the file identified by path
following the same path resolution behavior as in Resolve(const std::string&).
If the file identified by path
represents an asset and assetInfo
is not nullptr
, the resolver should populate assetInfo
with whatever additional metadata it knows or can reasonably compute about the asset without actually opening it.
Implemented in ArDefaultResolver.
|
pure virtual |
Unbind the given context from this resolver.
Clients should generally use ArResolverContextBinder instead of calling this function directly.
Implemented in ArDefaultResolver.
|
pure virtual |
Update assetInfo
with respect to the given fileVersion
.
Implemented in ArDefaultResolver.