resolver.h
Go to the documentation of this file.
1 //
2 // Copyright 2020 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_USD_AR_RESOLVER_H
8 #define PXR_USD_AR_RESOLVER_H
9 
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/ar/api.h"
14 #include "pxr/usd/ar/ar.h"
15 #include "pxr/usd/ar/resolvedPath.h"
16 #include "pxr/usd/ar/resolverContext.h"
17 #include "pxr/usd/ar/timestamp.h"
18 
19 #include <memory>
20 #include <string>
21 #include <vector>
22 
23 PXR_NAMESPACE_OPEN_SCOPE
24 
25 class ArAsset;
26 class ArAssetInfo;
27 class ArResolverContext;
28 class ArWritableAsset;
29 class TfType;
30 class VtValue;
31 
42 class ArResolver
43 {
44 public:
45  AR_API
46  virtual ~ArResolver();
47 
48  // Disallow copies
49  ArResolver(const ArResolver&) = delete;
50  ArResolver& operator=(const ArResolver&) = delete;
51 
52  // --------------------------------------------------------------------- //
73  // --------------------------------------------------------------------- //
74 
78  AR_API
79  std::string CreateIdentifier(
80  const std::string& assetPath,
81  const ArResolvedPath& anchorAssetPath = ArResolvedPath()) const;
82 
86  AR_API
87  std::string CreateIdentifierForNewAsset(
88  const std::string& assetPath,
89  const ArResolvedPath& anchorAssetPath = ArResolvedPath()) const;
90 
92 
93  // --------------------------------------------------------------------- //
98  // --------------------------------------------------------------------- //
99 
103  AR_API
104  ArResolvedPath Resolve(
105  const std::string& assetPath) const;
106 
113  AR_API
114  ArResolvedPath ResolveForNewAsset(
115  const std::string& assetPath) const;
116 
118 
119  // --------------------------------------------------------------------- //
124  // --------------------------------------------------------------------- //
125 
132  AR_API
133  void BindContext(
134  const ArResolverContext& context,
135  VtValue* bindingData);
136 
143  AR_API
144  void UnbindContext(
145  const ArResolverContext& context,
146  VtValue* bindingData);
147 
153  AR_API
154  ArResolverContext CreateDefaultContext() const;
155 
163  AR_API
164  ArResolverContext CreateDefaultContextForAsset(
165  const std::string& assetPath) const;
166 
169  AR_API
170  ArResolverContext CreateContextFromString(
171  const std::string& contextStr) const;
172 
183  AR_API
184  ArResolverContext CreateContextFromString(
185  const std::string& uriScheme, const std::string& contextStr) const;
186 
211  AR_API
212  ArResolverContext CreateContextFromStrings(
213  const std::vector<
214  std::pair<std::string, std::string>>& contextStrs) const;
215 
229  AR_API
230  void RefreshContext(
231  const ArResolverContext& context);
232 
236  AR_API
237  ArResolverContext GetCurrentContext() const;
238 
248  AR_API
249  bool IsContextDependentPath(
250  const std::string& assetPath) const;
251 
253 
254  // --------------------------------------------------------------------- //
259  // --------------------------------------------------------------------- //
260 
263  AR_API
264  std::string GetExtension(
265  const std::string& assetPath) const;
266 
270  AR_API
271  ArAssetInfo GetAssetInfo(
272  const std::string& assetPath,
273  const ArResolvedPath& resolvedPath) const;
274 
279  AR_API
280  ArTimestamp GetModificationTimestamp(
281  const std::string& assetPath,
282  const ArResolvedPath& resolvedPath) const;
283 
289  AR_API
290  std::shared_ptr<ArAsset> OpenAsset(
291  const ArResolvedPath& resolvedPath) const;
292 
294  enum class WriteMode
295  {
299  Update = 0,
300 
304  Replace
305  };
306 
318  AR_API
319  std::shared_ptr<ArWritableAsset> OpenAssetForWrite(
320  const ArResolvedPath& resolvedPath,
321  WriteMode writeMode) const;
322 
326  AR_API
327  bool CanWriteAssetToPath(
328  const ArResolvedPath& resolvedPath,
329  std::string* whyNot = nullptr) const;
330 
332 
333  // --------------------------------------------------------------------- //
362  // --------------------------------------------------------------------- //
363 
374  AR_API
375  void BeginCacheScope(
376  VtValue* cacheScopeData);
377 
387  AR_API
388  void EndCacheScope(
389  VtValue* cacheScopeData);
390 
392 
393  // --------------------------------------------------------------------- //
402  // --------------------------------------------------------------------- //
403 
406  AR_API
407  bool IsRepositoryPath(const std::string& path) const;
408 
410 
411 protected:
412  AR_API
413  ArResolver();
414 
415  // --------------------------------------------------------------------- //
420 
457  virtual std::string _CreateIdentifier(
458  const std::string& assetPath,
459  const ArResolvedPath& anchorAssetPath) const = 0;
460 
471  virtual std::string _CreateIdentifierForNewAsset(
472  const std::string& assetPath,
473  const ArResolvedPath& anchorAssetPath) const = 0;
474 
477  virtual ArResolvedPath _Resolve(
478  const std::string& assetPath) const = 0;
479 
483  virtual ArResolvedPath _ResolveForNewAsset(
484  const std::string& assetPath) const = 0;
485 
487 
488  // --------------------------------------------------------------------- //
505 
527  AR_API
528  virtual void _BindContext(
529  const ArResolverContext& context,
530  VtValue* bindingData);
531 
543  AR_API
544  virtual void _UnbindContext(
545  const ArResolverContext& context,
546  VtValue* bindingData);
547 
566  AR_API
567  virtual ArResolverContext _CreateDefaultContext() const;
568 
597  AR_API
598  virtual ArResolverContext _CreateDefaultContextForAsset(
599  const std::string& assetPath) const;
600 
605  AR_API
606  virtual ArResolverContext _CreateContextFromString(
607  const std::string& contextStr) const;
608 
616  AR_API
617  virtual void _RefreshContext(
618  const ArResolverContext& context);
619 
634  AR_API
635  virtual ArResolverContext _GetCurrentContext() const;
636 
651  AR_API
652  virtual bool _IsContextDependentPath(
653  const std::string& assetPath) const;
654 
656 
657  // --------------------------------------------------------------------- //
662 
671  AR_API
672  virtual std::string _GetExtension(
673  const std::string& assetPath) const;
674 
679  AR_API
680  virtual ArAssetInfo _GetAssetInfo(
681  const std::string& assetPath,
682  const ArResolvedPath& resolvedPath) const;
683 
697  AR_API
698  virtual ArTimestamp _GetModificationTimestamp(
699  const std::string& assetPath,
700  const ArResolvedPath& resolvedPath) const;
701 
711  AR_API
712  virtual std::shared_ptr<ArAsset> _OpenAsset(
713  const ArResolvedPath& resolvedPath) const = 0;
714 
719  AR_API
720  virtual bool _CanWriteAssetToPath(
721  const ArResolvedPath& resolvedPath,
722  std::string* whyNot) const;
723 
733  AR_API
734  virtual std::shared_ptr<ArWritableAsset>
735  _OpenAssetForWrite(
736  const ArResolvedPath& resolvedPath,
737  WriteMode writeMode) const = 0;
738 
740 
741  // --------------------------------------------------------------------- //
759 
768  AR_API
769  virtual void _BeginCacheScope(
770  VtValue* cacheScopeData);
771 
779  AR_API
780  virtual void _EndCacheScope(
781  VtValue* cacheScopeData);
782 
784 
788  AR_API
789  virtual bool _IsRepositoryPath(
790  const std::string& path) const;
791 
792  // --------------------------------------------------------------------- //
799 
825  template <class ContextObj>
826  const ContextObj* _GetCurrentContextObject() const
827  {
828  const ArResolverContext* ctx = _GetInternallyManagedCurrentContext();
829  return ctx ? ctx->Get<ContextObj>() : nullptr;
830  }
831 
833 
834 private:
835  // Returns pointer to ArResolverContext that was most recently bound
836  // via BindContext. This is *not* the same as GetCurrentContext,
837  // since subclasses may return an ArResolverContext that hasn't
838  // been bound via BindContext in their implementations.
839  AR_API
840  const ArResolverContext* _GetInternallyManagedCurrentContext() const;
841 
842 };
843 
869 AR_API
870 ArResolver& ArGetResolver();
871 
883 AR_API
884 void ArSetPreferredResolver(const std::string& resolverTypeName);
885 
893 
902 AR_API
903 ArResolver& ArGetUnderlyingResolver();
904 
921 AR_API
922 std::vector<TfType> ArGetAvailableResolvers();
923 
927 AR_API
928 const std::vector<std::string>& ArGetRegisteredURISchemes();
929 
947 AR_API
948 std::unique_ptr<ArResolver> ArCreateResolver(const TfType& resolverType);
949 
951 
952 PXR_NAMESPACE_CLOSE_SCOPE
953 
954 #endif
ArResolver::_GetExtension
virtual AR_API std::string _GetExtension(const std::string &assetPath) const
Return the file extension for the given assetPath.
ArTimestamp
Represents a timestamp for an asset.
Definition: timestamp.h:25
ArResolver::IsContextDependentPath
AR_API bool IsContextDependentPath(const std::string &assetPath) const
Returns true if assetPath is a context-dependent path, false otherwise.
ArResolver::OpenAsset
AR_API std::shared_ptr< ArAsset > OpenAsset(const ArResolvedPath &resolvedPath) const
Returns an ArAsset object for the asset located at resolvedPath.
ArResolver::_IsRepositoryPath
virtual AR_API bool _IsRepositoryPath(const std::string &path) const
ArCreateResolver
AR_API std::unique_ptr< ArResolver > ArCreateResolver(const TfType &resolverType)
Construct an instance of the ArResolver subclass specified by resolverType.
ArResolver::RefreshContext
AR_API void RefreshContext(const ArResolverContext &context)
Refresh any caches associated with the given context.
ArResolver::CreateDefaultContext
AR_API ArResolverContext CreateDefaultContext() const
Return an ArResolverContext that may be bound to this resolver to resolve assets when no other contex...
ArResolver::WriteMode::Update
Open asset for in-place updates.
ArWritableAsset
Interface for writing data to an asset.
Definition: writableAsset.h:26
ArResolver::_GetAssetInfo
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 assetP...
ArResolver::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 asset...
ArAsset
Interface for accessing the contents of an asset.
Definition: asset.h:27
ArResolver::_CreateContextFromString
virtual AR_API ArResolverContext _CreateContextFromString(const std::string &contextStr) const
Return an ArResolverContext created from the given contextStr.
ArResolver::CreateContextFromString
AR_API ArResolverContext CreateContextFromString(const std::string &contextStr) const
Return an ArResolverContext created from the primary ArResolver implementation using the given contex...
ArResolver::_BeginCacheScope
virtual AR_API void _BeginCacheScope(VtValue *cacheScopeData)
Mark the start of a resolution caching scope.
ArResolver::BeginCacheScope
AR_API void BeginCacheScope(VtValue *cacheScopeData)
Mark the start of a resolution caching scope.
ArResolver::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...
ArResolver::_CreateDefaultContextForAsset
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 assetP...
ArResolver::_Resolve
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 tha...
ArResolver::UnbindContext
AR_API void UnbindContext(const ArResolverContext &context, VtValue *bindingData)
Unbind the given context from this resolver.
ArResolver::_OpenAssetForWrite
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.
ArGetRegisteredURISchemes
AR_API const std::vector< std::string > & ArGetRegisteredURISchemes()
Returns list of all URI schemes for which a resolver has been registered.
ArResolver::BindContext
AR_API void BindContext(const ArResolverContext &context, VtValue *bindingData)
Binds the given context to this resolver.
ArResolver::WriteMode::Replace
Open asset for replacement.
ArGetResolver
AR_API ArResolver & ArGetResolver()
Returns the configured asset resolver.
ArResolver::_IsContextDependentPath
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...
ArResolver::GetExtension
AR_API std::string GetExtension(const std::string &assetPath) const
Returns the file extension for the given assetPath.
ArResolver::_BindContext
virtual AR_API void _BindContext(const ArResolverContext &context, VtValue *bindingData)
Bind the given context to this resolver.
ArSetPreferredResolver
AR_API void ArSetPreferredResolver(const std::string &resolverTypeName)
Set the preferred ArResolver subclass used by ArGetResolver.
ArResolver::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.
ArGetAvailableResolvers
AR_API std::vector< TfType > ArGetAvailableResolvers()
Returns list of TfTypes for available ArResolver subclasses.
ArResolver::_CanWriteAssetToPath
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.
ArResolver::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.
ArResolvedPath
Represents a resolved asset path.
Definition: resolvedPath.h:22
ArResolver::_RefreshContext
virtual AR_API void _RefreshContext(const ArResolverContext &context)
Refresh any caches associated with the given context.
ArResolver::_GetModificationTimestamp
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.
ArResolver::_ResolveForNewAsset
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 A...
ArResolver::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 assetP...
ArResolver::GetCurrentContext
AR_API ArResolverContext GetCurrentContext() const
Returns the asset resolver context currently bound in this thread.
ArResolver::_GetCurrentContextObject
const ContextObj * _GetCurrentContextObject() const
Returns a pointer to the context object of type ContextObj from the last ArResolverContext that was b...
Definition: resolver.h:826
ArResolver::_OpenAsset
virtual AR_API std::shared_ptr< ArAsset > _OpenAsset(const ArResolvedPath &resolvedPath) const =0
Return an ArAsset object for the asset located at resolvedPath.
ArGetUnderlyingResolver
AR_API ArResolver & ArGetUnderlyingResolver()
Returns the underlying ArResolver instance used by ArGetResolver.
ArResolver::CreateIdentifier
AR_API std::string CreateIdentifier(const std::string &assetPath, const ArResolvedPath &anchorAssetPath=ArResolvedPath()) const
Returns an identifier for the asset specified by assetPath.
TfType
TfType represents a dynamic runtime type.
Definition: type.h:47
ArResolver::_GetCurrentContext
virtual AR_API ArResolverContext _GetCurrentContext() const
Return the currently bound context.
ArResolverContext
An asset resolver context allows clients to provide additional data to the resolver for use during re...
Definition: resolverContext.h:107
ArResolver::_CreateDefaultContext
virtual AR_API ArResolverContext _CreateDefaultContext() const
Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other...
ArResolver::_EndCacheScope
virtual AR_API void _EndCacheScope(VtValue *cacheScopeData)
Mark the end of a resolution caching scope.
ArResolver::IsRepositoryPath
AR_API bool IsRepositoryPath(const std::string &path) const
ArResolver::_CreateIdentifierForNewAsset
virtual std::string _CreateIdentifierForNewAsset(const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const =0
Return an identifier for a new asset at the given assetPath.
ArResolver::EndCacheScope
AR_API void EndCacheScope(VtValue *cacheScopeData)
Mark the end of a resolution caching scope.
ArResolver::WriteMode
WriteMode
Enumeration of write modes for OpenAssetForWrite.
Definition: resolver.h:294
VtValue
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:89
ArResolver::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...
ArResolver::_UnbindContext
virtual AR_API void _UnbindContext(const ArResolverContext &context, VtValue *bindingData)
Unbind the given context from this resolver.
ArResolverContext::Get
const ContextObj * Get() const
Returns pointer to the context object of the given type held in this resolver context.
Definition: resolverContext.h:178
ArResolver::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.
ArResolver::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.
ArResolver
Interface for the asset resolution system.
Definition: resolver.h:42
ArAssetInfo
Contains information about a resolved asset.
Definition: assetInfo.h:24
ArResolver::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.