resolver.h
Go to the documentation of this file.
1 //
2 // Copyright 2020 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_AR_RESOLVER_H
25 #define PXR_USD_AR_RESOLVER_H
26 
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/ar/api.h"
31 #include "pxr/usd/ar/ar.h"
34 #include "pxr/usd/ar/timestamp.h"
35 
36 #include <memory>
37 #include <string>
38 #include <vector>
39 
40 PXR_NAMESPACE_OPEN_SCOPE
41 
42 class ArAsset;
43 class ArAssetInfo;
44 class ArResolverContext;
45 class ArWritableAsset;
46 class TfType;
47 class VtValue;
48 
59 class ArResolver
60 {
61 public:
62  AR_API
63  virtual ~ArResolver();
64 
65  // Disallow copies
66  ArResolver(const ArResolver&) = delete;
67  ArResolver& operator=(const ArResolver&) = delete;
68 
69  // --------------------------------------------------------------------- //
90  // --------------------------------------------------------------------- //
91 
95  AR_API
96  std::string CreateIdentifier(
97  const std::string& assetPath,
98  const ArResolvedPath& anchorAssetPath = ArResolvedPath()) const;
99 
103  AR_API
104  std::string CreateIdentifierForNewAsset(
105  const std::string& assetPath,
106  const ArResolvedPath& anchorAssetPath = ArResolvedPath()) const;
107 
109 
110  // --------------------------------------------------------------------- //
115  // --------------------------------------------------------------------- //
116 
120  AR_API
122  const std::string& assetPath) const;
123 
130  AR_API
132  const std::string& assetPath) const;
133 
135 
136  // --------------------------------------------------------------------- //
141  // --------------------------------------------------------------------- //
142 
149  AR_API
150  void BindContext(
151  const ArResolverContext& context,
152  VtValue* bindingData);
153 
160  AR_API
161  void UnbindContext(
162  const ArResolverContext& context,
163  VtValue* bindingData);
164 
170  AR_API
172 
179  AR_API
181  const std::string& assetPath) const;
182 
185  AR_API
187  const std::string& contextStr) const;
188 
197  AR_API
199  const std::string& uriScheme, const std::string& contextStr) const;
200 
225  AR_API
227  const std::vector<
228  std::pair<std::string, std::string>>& contextStrs) const;
229 
234  AR_API
235  void RefreshContext(
236  const ArResolverContext& context);
237 
241  AR_API
243 
253  AR_API
255  const std::string& assetPath) const;
256 
258 
259  // --------------------------------------------------------------------- //
264  // --------------------------------------------------------------------- //
265 
268  AR_API
269  std::string GetExtension(
270  const std::string& assetPath) const;
271 
275  AR_API
277  const std::string& assetPath,
278  const ArResolvedPath& resolvedPath) const;
279 
284  AR_API
286  const std::string& assetPath,
287  const ArResolvedPath& resolvedPath) const;
288 
294  AR_API
295  std::shared_ptr<ArAsset> OpenAsset(
296  const ArResolvedPath& resolvedPath) const;
297 
299  enum class WriteMode
300  {
304  Update = 0,
305 
309  Replace
310  };
311 
323  AR_API
324  std::shared_ptr<ArWritableAsset> OpenAssetForWrite(
325  const ArResolvedPath& resolvedPath,
326  WriteMode writeMode) const;
327 
331  AR_API
332  bool CanWriteAssetToPath(
333  const ArResolvedPath& resolvedPath,
334  std::string* whyNot = nullptr) const;
335 
337 
338  // --------------------------------------------------------------------- //
367  // --------------------------------------------------------------------- //
368 
379  AR_API
380  void BeginCacheScope(
381  VtValue* cacheScopeData);
382 
392  AR_API
393  void EndCacheScope(
394  VtValue* cacheScopeData);
395 
397 
398  // --------------------------------------------------------------------- //
407  // --------------------------------------------------------------------- //
408 
411  AR_API
412  bool IsRepositoryPath(const std::string& path) const;
413 
415 
416 protected:
417  AR_API
418  ArResolver();
419 
420  // --------------------------------------------------------------------- //
425 
462  virtual std::string _CreateIdentifier(
463  const std::string& assetPath,
464  const ArResolvedPath& anchorAssetPath) const = 0;
465 
476  virtual std::string _CreateIdentifierForNewAsset(
477  const std::string& assetPath,
478  const ArResolvedPath& anchorAssetPath) const = 0;
479 
482  virtual ArResolvedPath _Resolve(
483  const std::string& assetPath) const = 0;
484 
489  const std::string& assetPath) const = 0;
490 
492 
493  // --------------------------------------------------------------------- //
510 
532  AR_API
533  virtual void _BindContext(
534  const ArResolverContext& context,
535  VtValue* bindingData);
536 
548  AR_API
549  virtual void _UnbindContext(
550  const ArResolverContext& context,
551  VtValue* bindingData);
552 
571  AR_API
573 
602  AR_API
604  const std::string& assetPath) const;
605 
610  AR_API
612  const std::string& contextStr) const;
613 
621  AR_API
622  virtual void _RefreshContext(
623  const ArResolverContext& context);
624 
639  AR_API
640  virtual ArResolverContext _GetCurrentContext() const;
641 
656  AR_API
657  virtual bool _IsContextDependentPath(
658  const std::string& assetPath) const;
659 
661 
662  // --------------------------------------------------------------------- //
667 
676  AR_API
677  virtual std::string _GetExtension(
678  const std::string& assetPath) const;
679 
684  AR_API
685  virtual ArAssetInfo _GetAssetInfo(
686  const std::string& assetPath,
687  const ArResolvedPath& resolvedPath) const;
688 
702  AR_API
704  const std::string& assetPath,
705  const ArResolvedPath& resolvedPath) const;
706 
716  AR_API
717  virtual std::shared_ptr<ArAsset> _OpenAsset(
718  const ArResolvedPath& resolvedPath) const = 0;
719 
724  AR_API
725  virtual bool _CanWriteAssetToPath(
726  const ArResolvedPath& resolvedPath,
727  std::string* whyNot) const;
728 
738  AR_API
739  virtual std::shared_ptr<ArWritableAsset>
741  const ArResolvedPath& resolvedPath,
742  WriteMode writeMode) const = 0;
743 
745 
746  // --------------------------------------------------------------------- //
764 
773  AR_API
774  virtual void _BeginCacheScope(
775  VtValue* cacheScopeData);
776 
784  AR_API
785  virtual void _EndCacheScope(
786  VtValue* cacheScopeData);
787 
789 
793  AR_API
794  virtual bool _IsRepositoryPath(
795  const std::string& path) const;
796 
797  // --------------------------------------------------------------------- //
804 
830  template <class ContextObj>
831  const ContextObj* _GetCurrentContextObject() const
832  {
833  const ArResolverContext* ctx = _GetInternallyManagedCurrentContext();
834  return ctx ? ctx->Get<ContextObj>() : nullptr;
835  }
836 
838 
839 private:
840  // Returns pointer to ArResolverContext that was most recently bound
841  // via BindContext. This is *not* the same as GetCurrentContext,
842  // since subclasses may return an ArResolverContext that hasn't
843  // been bound via BindContext in their implementations.
844  AR_API
845  const ArResolverContext* _GetInternallyManagedCurrentContext() const;
846 
847 };
848 
874 AR_API
876 
888 AR_API
889 void ArSetPreferredResolver(const std::string& resolverTypeName);
890 
898 
907 AR_API
909 
926 AR_API
927 std::vector<TfType> ArGetAvailableResolvers();
928 
946 AR_API
947 std::unique_ptr<ArResolver> ArCreateResolver(const TfType& resolverType);
948 
950 
951 PXR_NAMESPACE_CLOSE_SCOPE
952 
953 #endif
virtual AR_API std::string _GetExtension(const std::string &assetPath) const
Return the file extension for the given assetPath.
Represents a timestamp for an asset.
Definition: timestamp.h:42
AR_API bool IsContextDependentPath(const std::string &assetPath) const
Returns true if assetPath is a context-dependent path, false otherwise.
AR_API std::shared_ptr< ArAsset > OpenAsset(const ArResolvedPath &resolvedPath) const
Returns an ArAsset object for the asset located at resolvedPath.
virtual AR_API bool _IsRepositoryPath(const std::string &path) const
AR_API std::unique_ptr< ArResolver > ArCreateResolver(const TfType &resolverType)
Construct an instance of the ArResolver subclass specified by resolverType.
AR_API void RefreshContext(const ArResolverContext &context)
Refresh any caches associated with the given context.
AR_API ArResolverContext CreateDefaultContext() const
Return an ArResolverContext that may be bound to this resolver to resolve assets when no other contex...
Open asset for in-place updates.
Interface for writing data to an asset.
Definition: writableAsset.h:43
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...
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...
Interface for accessing the contents of an asset.
Definition: asset.h:44
virtual AR_API ArResolverContext _CreateContextFromString(const std::string &contextStr) const
Return an ArResolverContext created from the given contextStr.
AR_API ArResolverContext CreateContextFromString(const std::string &contextStr) const
Return an ArResolverContext created from the primary ArResolver implementation using the given contex...
virtual AR_API void _BeginCacheScope(VtValue *cacheScopeData)
Mark the start of a resolution caching scope.
AR_API void BeginCacheScope(VtValue *cacheScopeData)
Mark the start of a resolution caching scope.
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...
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...
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...
AR_API void UnbindContext(const ArResolverContext &context, VtValue *bindingData)
Unbind the given context from this resolver.
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.
AR_API void BindContext(const ArResolverContext &context, VtValue *bindingData)
Binds the given context to this resolver.
Open asset for replacement.
AR_API ArResolver & ArGetResolver()
Returns the configured asset resolver.
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...
AR_API std::string GetExtension(const std::string &assetPath) const
Returns the file extension for the given assetPath.
virtual AR_API void _BindContext(const ArResolverContext &context, VtValue *bindingData)
Bind the given context to this resolver.
AR_API void ArSetPreferredResolver(const std::string &resolverTypeName)
Set the preferred ArResolver subclass used by ArGetResolver.
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.
AR_API std::vector< TfType > ArGetAvailableResolvers()
Returns list of TfTypes for available ArResolver subclasses.
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.
AR_API ArResolvedPath Resolve(const std::string &assetPath) const
Returns the resolved path for the asset identified by the given assetPath if it exists.
Represents a resolved asset path.
Definition: resolvedPath.h:39
virtual AR_API void _RefreshContext(const ArResolverContext &context)
Refresh any caches associated with the given context.
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 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...
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...
AR_API ArResolverContext GetCurrentContext() const
Returns the asset resolver context currently bound in this thread.
const ContextObj * _GetCurrentContextObject() const
Returns a pointer to the context object of type ContextObj from the last ArResolverContext that was b...
Definition: resolver.h:831
virtual AR_API std::shared_ptr< ArAsset > _OpenAsset(const ArResolvedPath &resolvedPath) const =0
Return an ArAsset object for the asset located at resolvedPath.
AR_API ArResolver & ArGetUnderlyingResolver()
Returns the underlying ArResolver instance used by ArGetResolver.
AR_API std::string CreateIdentifier(const std::string &assetPath, const ArResolvedPath &anchorAssetPath=ArResolvedPath()) const
Returns an identifier for the asset specified by assetPath.
TfType represents a dynamic runtime type.
Definition: type.h:64
virtual AR_API ArResolverContext _GetCurrentContext() const
Return the currently bound context.
An asset resolver context allows clients to provide additional data to the resolver for use during re...
virtual AR_API ArResolverContext _CreateDefaultContext() const
Return a default ArResolverContext that may be bound to this resolver to resolve assets when no other...
virtual AR_API void _EndCacheScope(VtValue *cacheScopeData)
Mark the end of a resolution caching scope.
AR_API bool IsRepositoryPath(const std::string &path) const
virtual std::string _CreateIdentifierForNewAsset(const std::string &assetPath, const ArResolvedPath &anchorAssetPath) const =0
Return an identifier for a new asset at the given assetPath.
AR_API void EndCacheScope(VtValue *cacheScopeData)
Mark the end of a resolution caching scope.
WriteMode
Enumeration of write modes for OpenAssetForWrite.
Definition: resolver.h:299
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:166
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...
virtual AR_API void _UnbindContext(const ArResolverContext &context, VtValue *bindingData)
Unbind the given context from this resolver.
const ContextObj * Get() const
Returns pointer to the context object of the given type held in this resolver context.
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::string CreateIdentifierForNewAsset(const std::string &assetPath, const ArResolvedPath &anchorAssetPath=ArResolvedPath()) const
Returns an identifier for a new asset specified by assetPath.
Interface for the asset resolution system.
Definition: resolver.h:59
Contains information about a resolved asset.
Definition: assetInfo.h:40
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.