HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
usdzPackage.h
Go to the documentation of this file.
1 //
2 // Copyright 2023 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_USDZ_PACKAGE_H
25 #define PXR_USD_USD_UTILS_USDZ_PACKAGE_H
26 
27 /// \file usdUtils/usdzPackage.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/sdf/layer.h"
31 #include "pxr/usd/usdUtils/api.h"
32 
33 #include <string>
34 #include <vector>
35 
37 
38 class SdfAssetPath;
39 
40 /// Creates a USDZ package containing the specified asset, identified by its
41 /// \p assetPath. The created package will include a localized version of the
42 /// asset itself and all of its external dependencies. Any anonymous layers that
43 /// are encountered during dependency discovery will be serialized into the
44 /// resulting package. Due to localization, the packaged layers might be
45 /// modified to have different asset paths.
46 ///
47 /// You can optionally specify a different package-internal name for the first
48 /// layer of the asset by specifying \p firstLayerName. By default,
49 /// \p firstLayerName is empty, meaning that the original name is preserved.
50 ///
51 /// The \p editLayersInPlace parameter controls the strategy used for managing
52 /// changes to layers (including the root layer and all transitive layer
53 /// dependencies) that occur during the package creation process. When
54 /// \p editLayersInPlace is false, a temporary, anonymous copy of each
55 /// modified layer is created and written into the package. This has the
56 /// advantage of leaving source layers untouched at the expense of creating a
57 /// copy of each modified layer in memory for the duration of this function.
58 ///
59 /// When \p editLayersInPlace is set to true, layers are modified in-place and
60 /// not reverted or persisted once the package has been created. In this case,
61 /// there is no overhead of creating copies of each modified layer. If you have
62 /// UsdStages open during the function call that reference the layers being
63 /// modified, you may receive warnings or composition errors. While these
64 /// errors will not affect the resulting package adversely, it is strongly
65 /// recommended that this function is run in isolation after any source
66 /// UsdStages have been closed.
67 ///
68 /// Returns true if the package was created successfully.
69 ///
70 /// \note Clients of this function must take care of configuring the asset
71 /// resolver context before invoking the function. To create a default
72 /// resolver context, use \ref CreateDefaultContextForAsset() with the
73 /// asset path.
74 ///
75 /// \note If the given asset has a dependency on a directory (i.e. an external
76 /// reference to a directory path), the dependency is ignored and the contents
77 /// of the directory are not included in the created package.
78 ///
79 /// \sa UsdUtilsCreateNewARKitUsdzPackage()
81 bool
83  const SdfAssetPath& assetPath,
84  const std::string& usdzFilePath,
85  const std::string& firstLayerName=std::string(),
86  bool editLayersInPlace = false);
87 
88 /// Similar to UsdUtilsCreateNewUsdzPackage, this function packages all of the
89 /// dependencies of the given asset. Assets targeted at the initial usdz
90 /// implementation in ARKit operate under greater constraints than usdz files
91 /// for more general 'in house' uses, and this option attempts to ensure that
92 /// these constraints are honored; this may involve more transformations to the
93 /// data, which may cause loss of features such as VariantSets. Any anonymous
94 /// layers that are encountered during dependency discovery will be serialized
95 /// into the resulting package.
96 ///
97 /// If \p firstLayerName is specified, it is modified to have the ".usdc"
98 /// extension, as required by the initial usdz implementation in ARKit.
99 ///
100 /// The \p editLayersInPlace parameter controls the strategy used for managing
101 /// changes to layers (including the root layer and all transitive layer
102 /// dependencies) that occur during the package creation process. When
103 /// \p editLayersInPlace is false, a temporary, anonymous copy of each
104 /// modified layer is created and written into the package. This has the
105 /// advantage of leaving source layers untouched at the expense of creating a
106 /// copy of each modified layer in memory for the duration of this function.
107 ///
108 /// When \p editLayersInPlace is set to true, layers are modified in-place and
109 /// not reverted or persisted once the package has been created. In this case,
110 /// there is no overhead of creating copies of each modified layer. If you have
111 /// UsdStages open during the function call that reference the layers being
112 /// modified, you may receive warnings or composition errors. While these
113 /// errors will not affect the resulting package adversely, it is strongly
114 /// recommended that this function is run in isolation after any source
115 /// UsdStages have been closed.
116 ///
117 /// Returns true if the package was created successfully.
118 ///
119 /// \note Clients of this function must take care of configuring the asset
120 /// resolver context before invoking the function. To create a default
121 /// resolver context, use \ref CreateDefaultContextForAsset() with the
122 /// asset path.
123 ///
124 /// \note If the given asset has a dependency on a directory (i.e. an external
125 /// reference to a directory path), the dependency is ignored and the contents
126 /// of the directory are not included in the created package.
127 ///
128 /// \sa UsdUtilsCreateNewUsdzPackage()
130 bool
132  const SdfAssetPath &assetPath,
133  const std::string &usdzFilePath,
134  const std::string &firstLayerName=std::string(),
135  bool editLayersInplace = false);
136 
138 
139 #endif // PXR_USD_USD_UTILS_USDZ_PACKAGE_H
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USDUTILS_API bool UsdUtilsCreateNewUsdzPackage(const SdfAssetPath &assetPath, const std::string &usdzFilePath, const std::string &firstLayerName=std::string(), bool editLayersInPlace=false)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
USDUTILS_API bool UsdUtilsCreateNewARKitUsdzPackage(const SdfAssetPath &assetPath, const std::string &usdzFilePath, const std::string &firstLayerName=std::string(), bool editLayersInplace=false)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
#define USDUTILS_API
Definition: api.h:40