HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
packageResolver.h
Go to the documentation of this file.
1 //
2 // Copyright 2018 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_PACKAGE_RESOLVER_H
25 #define PXR_USD_AR_PACKAGE_RESOLVER_H
26 
27 /// \file ar/packageResolver.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/ar/api.h"
31 
32 #include <memory>
33 #include <string>
34 
36 
37 class ArAsset;
38 class VtValue;
39 
40 /// \class ArPackageResolver
41 ///
42 /// Interface for resolving assets within package assets. A package resolver
43 /// is responsible for processing particular package asset formats and
44 /// resolving information about assets stored within that package.
45 ///
46 /// Each package resolver is associated with particular file formats and is
47 /// invoked by asset resolution when handling package-relative paths involving
48 /// those formats. ArPackageResolver instances are only used internally by Ar
49 /// and are not directly exposed to clients.
50 ///
51 /// \section ar_implementing_package_resolver Implementing a Package Resolver
52 ///
53 /// To implement a package resolver, users must create a plugin containing a
54 /// subclass of ArPackageResolver and register it with the plugin system
55 /// so that it can be discovered and instantiated at runtime.
56 ///
57 /// - Implement an ArPackageResolver subclass
58 /// \code{.cpp}
59 /// class CustomPackageResolver : public ArPackageResolver {
60 /// // ...
61 /// }
62 /// \endcode
63 ///
64 /// - In its implementation, register the ArPackageResolver subclass using
65 /// #AR_DEFINE_PACKAGE_RESOLVER
66 /// \code{.cpp}
67 /// # custom resolver's .cpp file
68 /// AR_DEFINE_PACKAGE_RESOLVER(CustomPackageResolver, ArPackageResolver);
69 /// \endcode
70 ///
71 /// - Declare the ArPackageResolver subclass in the plugin's plugInfo.json file.
72 /// Note that the entry for the subclass must declare the file format it
73 /// handles in the 'extensions' metadata.
74 /// \code{.json}
75 /// # plugInfo.json
76 /// {
77 /// "Plugins": [
78 /// {
79 /// "Info": {
80 /// "Types" : {
81 /// "CustomPackageResolver" : {
82 /// "bases": [ "ArPackageResolver" ],
83 /// "extensions": [ "pack" ]
84 /// }
85 /// }
86 /// },
87 /// ...
88 /// },
89 /// ...
90 /// ]
91 ///
92 /// }
93 /// \endcode
94 ///
96 {
97 public:
98  ArPackageResolver(const ArPackageResolver&) = delete;
100 
101  AR_API
102  virtual ~ArPackageResolver();
103 
104  // --------------------------------------------------------------------- //
105  /// \name Packaged Path Resolution Operations
106  ///
107  /// @{
108  // --------------------------------------------------------------------- //
109 
110  /// Returns the resolved path for the asset located at \p packagedPath
111  /// in the package specified by \p resolvedPackagePath if it exists.
112  /// If the asset does not exist in the package, returns an empty string.
113  ///
114  /// When ArResolver::Resolve is invoked on a package-relative path, the
115  /// path will be parsed into the outermost package path, and the inner
116  /// packaged path. The outermost package path will be resolved by the
117  /// primary resolver. ArPackageResolver::Resolve will then be called on
118  /// the corresponding package resolver with that resolved path and the
119  /// inner packaged path. If the inner packaged path is itself a
120  /// package-relative path, this process recurses until all paths have been
121  /// resolved.
122  ///
123  /// \see ArResolver::Resolve
124  AR_API
125  virtual std::string Resolve(
126  const std::string& resolvedPackagePath,
127  const std::string& packagedPath) = 0;
128 
129  /// @}
130 
131  // --------------------------------------------------------------------- //
132  /// \name Asset-specific Operations
133  ///
134  /// @{
135  // --------------------------------------------------------------------- //
136 
137  /// Returns an ArAsset object for the asset at \p resolvedPackagedPath
138  /// located in the package asset at \p resolvedPackagePath.
139  /// Returns an invalid std::shared_ptr if object could not be created.
140  ///
141  /// \see ArResolver::OpenAsset
142  AR_API
143  virtual std::shared_ptr<ArAsset> OpenAsset(
144  const std::string& resolvedPackagePath,
145  const std::string& resolvedPackagedPath) = 0;
146 
147  // --------------------------------------------------------------------- //
148  /// \name Scoped Resolution Cache
149  ///
150  /// These functions are called when scoped resolution caches are enabled
151  /// via ArResolver.
152  ///
153  /// \see \ref ArResolver_scopedCache "Scoped Resolution Cache"
154  /// @{
155  // --------------------------------------------------------------------- //
156 
157  /// Mark the start of a resolution caching scope.
158  ///
159  /// \see ArResolver::BeginCacheScope
160  AR_API
161  virtual void BeginCacheScope(
162  VtValue* cacheScopeData) = 0;
163 
164  /// Mark the end of a resolution caching scope.
165  ///
166  /// \see ArResolver::EndCacheScope
167  AR_API
168  virtual void EndCacheScope(
169  VtValue* cacheScopeData) = 0;
170 
171 protected:
172  AR_API
174 };
175 
177 
178 #endif // PXR_USD_AR_PACKAGE_RESOLVER_H
virtual AR_API void EndCacheScope(VtValue *cacheScopeData)=0
Definition: asset.h:43
AR_API ArPackageResolver()
virtual AR_API std::string Resolve(const std::string &resolvedPackagePath, const std::string &packagedPath)=0
#define AR_API
Definition: api.h:40
virtual AR_API void BeginCacheScope(VtValue *cacheScopeData)=0
ArPackageResolver & operator=(const ArPackageResolver &)=delete
GLsizei const GLchar *const * string
Definition: glew.h:1844
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
virtual AR_API std::shared_ptr< ArAsset > OpenAsset(const std::string &resolvedPackagePath, const std::string &resolvedPackagedPath)=0
Definition: value.h:174
virtual AR_API ~ArPackageResolver()