HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
dependencies.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 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_USD_UTILS_DEPENDENCIES_H
25 #define PXR_USD_USD_UTILS_DEPENDENCIES_H
26 
27 /// \file usdUtils/dependencies.h
28 ///
29 /// Utilities for the following tasks that require consideration of a USD
30 /// asset's external dependencies:
31 /// * extracting asset dependencies from a USD file.
32 /// * creating a USDZ package containing a given asset and all of its external
33 /// dependencies.
34 /// * some time in the future, localize a given asset and all of its
35 /// dependencies into a specified directory.
36 ///
37 
38 #include "pxr/pxr.h"
39 #include "pxr/usd/sdf/layer.h"
40 #include "pxr/usd/usdUtils/api.h"
41 
42 #include <string>
43 #include <vector>
44 
46 
47 class SdfAssetPath;
48 
49 /// Parses the file at \p filePath, identifying external references, and
50 /// sorting them into separate type-based buckets. Sublayers are returned in
51 /// the \p sublayers vector, references, whether prim references, value clip
52 /// references or values from asset path attributes, are returned in the
53 /// \p references vector. Payload paths are returned in \p payloads.
54 ///
55 /// \note No recursive chasing of dependencies is performed; that is the
56 /// client's responsibility, if desired.
57 ///
58 /// \note Not all returned references are actually authored explicitly in the
59 /// layer. For example, templated clip asset paths are resolved and expanded
60 /// to include all available clip files that match the specified pattern.
63  const std::string& filePath,
64  std::vector<std::string>* subLayers,
65  std::vector<std::string>* references,
66  std::vector<std::string>* payloads);
67 
68 /// Creates a USDZ package containing the specified asset, identified by its
69 /// \p assetPath. The created package will include a localized version of the
70 /// asset itself and all of its external dependencies. Due to localization, the
71 /// packaged layers might be modified to have different asset paths.
72 ///
73 /// You can optionally specify a different package-internal name for the first
74 /// layer of the asset by specifying \p firstLayerName. By default,
75 /// \p firstLayerName is empty, meaning that the original name is preserved.
76 ///
77 /// Returns true if the package was created successfully.
78 ///
79 /// \note Clients of this function must take care of configuring the asset
80 /// resolver context before invoking the function. To create a default
81 /// resolver context, use \ref CreateDefaultContextForAsset() with the
82 /// asset path.
83 ///
84 /// \note If the given asset has a dependency on a directory (i.e. an external
85 /// reference to a directory path), the dependency is ignored and the contents
86 /// of the directory are not included in the created package.
87 ///
88 /// \note This function modifies the layers referenced by \p assetPath
89 /// (including the root layer and all transitive layer dependencies) in-place.
90 /// However, it does not save the layers before copying them into the package
91 /// that is created. It also does not revert the changes it makes to the
92 /// layers. Therefore, it is strongly recommended that you run this function in
93 /// isolation after any source UsdStages have been closed. If you have UsdStages
94 /// open during the function call that reference the layers being modified, you
95 /// may receive warnings or composition errors which may not affect the
96 /// resulting package adversely.
97 ///
98 /// \sa UsdUtilsCreateNewARKitUsdzPackage()
100 bool
102  const SdfAssetPath& assetPath,
103  const std::string& usdzFilePath,
104  const std::string& firstLayerName=std::string());
105 
106 /// Similar to UsdUtilsCreateNewUsdzPackage, this function packages all of the
107 /// dependencies of the given asset. Assets targeted at the initial usdz
108 /// implementation in ARKit operate under greater constraints than usdz files
109 /// for more general 'in house' uses, and this option attempts to ensure that
110 /// these constraints are honored; this may involve more transformations to the
111 /// data, which may cause loss of features such as VariantSets.
112 ///
113 /// If \p firstLayerName is specified, it is modified to have the ".usdc"
114 /// extension, as required by the initial usdz implementation in ARKit.
115 ///
116 /// Returns true if the package was created successfully.
117 ///
118 /// \note Clients of this function must take care of configuring the asset
119 /// resolver context before invoking the function. To create a default
120 /// resolver context, use \ref CreateDefaultContextForAsset() with the
121 /// asset path.
122 ///
123 /// \note If the given asset has a dependency on a directory (i.e. an external
124 /// reference to a directory path), the dependency is ignored and the contents
125 /// of the directory are not included in the created package.
126 ///
127 /// \note This function modifies the layers referenced by \p assetPath
128 /// (including the root layer and all transitive layer dependencies) in-place.
129 /// However, it does not save the layers before copying them into the package
130 /// that is created. It also does not revert the changes it makes to the
131 /// layers. Therefore, it is strongly recommended that you run this function in
132 /// isolation after any source UsdStages have been closed. If you have UsdStages
133 /// open during the function call that reference the layers being modified, you
134 /// may receive warnings or composition errors which may not affect the
135 /// resulting package adversely.
136 ///
137 /// \sa UsdUtilsCreateNewUsdzPackage()
139 bool
141  const SdfAssetPath &assetPath,
142  const std::string &usdzFilePath,
143  const std::string &firstLayerName=std::string());
144 
145 /// Recursively computes all the dependencies of the given asset and populates
146 /// \p layers with all the dependencies that can be opened as an SdfLayer.
147 /// All of the resolved non-layer dependencies are populated in \p assets.
148 /// Any unresolved (layer and non-layer) asset paths are populated in
149 /// \p unresolvedPaths.
150 ///
151 /// The input vectors to be populated with the results are are *cleared* before
152 /// any results are added to them.
153 ///
154 /// Returns true if the given asset was resolved correctly.
156 bool
158  std::vector<SdfLayerRefPtr> *layers,
159  std::vector<std::string> *assets,
160  std::vector<std::string> *unresolvedPaths);
161 
162 /// Callback that is used to modify asset paths in a layer. The \c assetPath
163 /// will contain the string value that's authored. The returned value is the
164 /// new value that should be authored in the layer.
165 using UsdUtilsModifyAssetPathFn = std::function<std::string(
166  const std::string& assetPath)>;
167 
168 /// Helper function that visits every asset path in \c layer, calls \c modifyFn
169 /// and replaces the value with the return value of \c modifyFn. This modifies
170 /// \c layer in place.
171 ///
172 /// This can be useful in preparing a layer for consumption in contexts that do
173 /// not have access to the ArResolver for which the layer's asset paths were
174 /// authored: we can replace all paths with their fully resolved equivalents,
175 /// for example.
178  const SdfLayerHandle& layer,
179  const UsdUtilsModifyAssetPathFn& modifyFn);
180 
182 
183 #endif // PXR_USD_USD_UTILS_DEPENDENCIES_H
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1298
USDUTILS_API void UsdUtilsModifyAssetPaths(const SdfLayerHandle &layer, const UsdUtilsModifyAssetPathFn &modifyFn)
std::function< std::string(const std::string &assetPath)> UsdUtilsModifyAssetPathFn
Definition: dependencies.h:166
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
USDUTILS_API bool UsdUtilsCreateNewARKitUsdzPackage(const SdfAssetPath &assetPath, const std::string &usdzFilePath, const std::string &firstLayerName=std::string())
USDUTILS_API void UsdUtilsExtractExternalReferences(const std::string &filePath, std::vector< std::string > *subLayers, std::vector< std::string > *references, std::vector< std::string > *payloads)
USDUTILS_API bool UsdUtilsComputeAllDependencies(const SdfAssetPath &assetPath, std::vector< SdfLayerRefPtr > *layers, std::vector< std::string > *assets, std::vector< std::string > *unresolvedPaths)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
USDUTILS_API bool UsdUtilsCreateNewUsdzPackage(const SdfAssetPath &assetPath, const std::string &usdzFilePath, const std::string &firstLayerName=std::string())
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
#define USDUTILS_API
Definition: api.h:40
GLenum GLsizei GLsizei GLsizei GLsizei layers
Definition: glew.h:2878