HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
flattenLayerStack.h
Go to the documentation of this file.
1 //
2 // Copyright 2017 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_FLATTEN_LAYER_STACK_H
25 #define PXR_USD_USD_UTILS_FLATTEN_LAYER_STACK_H
26 
27 /// \file usdUtils/flattenLayerStack.h
28 ///
29 /// Utilities for flattening layer stacks into a single layer.
30 
31 #include "pxr/pxr.h"
32 #include "pxr/usd/usd/stage.h"
33 #include "pxr/usd/usdUtils/api.h"
36 
38 
40 
41 /// Flatten the root layer stack of the given \p stage into a single layer
42 /// with the given optional \p tag.
43 ///
44 /// The result layer can be substituted for the original layer stack
45 /// while producing the same composed UsdStage.
46 ///
47 /// Unlike UsdStage::Export(), this function does not flatten
48 /// composition arcs, such as references, payloads, inherits,
49 /// specializes, or variants.
50 ///
51 /// Sublayer time offsets on the sublayers will be applied to remap
52 /// any time-keyed scene description, such as timeSamples and clips.
53 ///
54 /// Asset paths will be resolved to absolute form, to ensure that
55 /// they continue to identify the same asset from the output layer.
56 /// \sa UsdUtilsFlattenLayerStackResolveAssetPath
57 ///
58 /// A few historical scene description features cannot be flattened
59 /// into a single opinion because they unfortunately encode
60 /// operations that are not closed under composition. Specifically,
61 /// the SdfListOp operations "add" and "reorder" cannot be flattened.
62 /// Instead, "add" will be converted to "append", and "reorder"
63 /// will be discarded.
64 ///
67 UsdUtilsFlattenLayerStack(const UsdStagePtr &stage,
68  const std::string& tag = std::string());
69 
70 /// Callback function for overloaded version of \c UsdUtilsFlattenLayerStack.
71 ///
72 /// The callback is given the \c sourceLayer and the \c assetPath authored in
73 /// that layer. It should return the \c std::string that should be authored in
74 /// the flattened layer.
75 ///
76 /// \sa UsdUtilsFlattenLayerStackResolveAssetPath
77 using UsdUtilsResolveAssetPathFn = std::function<std::string(
78  const SdfLayerHandle& sourceLayer,
79  const std::string& assetPath)>;
80 
81 /// Flatten the root layer stack of the given \p stage into a single layer with
82 /// the given optional \p tag and using the \p resolveAssetPathFn to resolve
83 /// asset paths that are encountered.
84 ///
85 /// This is an advanced version of the above function.
86 ///
87 ///
88 /// One use case for this version of the function is to flatten a layer stack
89 /// that contains relative asset paths that we want to preserve as relative
90 /// paths. For example:
91 ///
92 /// \code
93 /// /source/root.usd # sublayers a.usd and b.usd
94 /// /source/a.usd # contains reference to ./subdir/layer.usd
95 /// /source/b.usd
96 /// /source/subdir/layer.usd
97 /// \endcode
98 ///
99 /// We may want to generate \c "/dest/root.flat.usd" knowing that we will
100 /// (by some other means) also be copying \c "/source/subdir" into \c
101 /// "/dest/subdir". It's useful then to preserve the relative paths.
102 ///
103 /// Note, only the caller knows the ultimate destination of the flattened layer.
104 /// So to accomplish this, we can provide a \c resolveAssetPathFn callback that
105 /// captures the outputDir, tests if the authored path is relative, and if so,
106 /// computes a new relative path (based on where it will eventually be
107 /// exported).
110 UsdUtilsFlattenLayerStack(const UsdStagePtr &stage,
111  const UsdUtilsResolveAssetPathFn& resolveAssetPathFn,
112  const std::string& tag = std::string());
113 
114 /// The default \c UsdUtilsResolvePathFn used by \c UsdUtilsFlattenLayerStack.
115 /// For paths that the current ArResolver identifies as searchpaths or absolute
116 /// paths, we return the unmodified path. However, any "Layer relative path"
117 /// (see SdfComputeAssetPathRelativeToLayer) will be absolutized, because we do
118 /// not know if the flattened layer's containing directory will be the same as
119 /// any given source layer's in the incoming layerStack.
123  const SdfLayerHandle& sourceLayer,
124  const std::string& assetPath);
125 
126 
128 
129 #endif /* PXR_USD_USD_UTILS_FLATTEN_LAYER_STACK_H */
Definition: layer.h:94
USDUTILS_API SdfLayerRefPtr UsdUtilsFlattenLayerStack(const UsdStagePtr &stage, const std::string &tag=std::string())
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USDUTILS_API std::string UsdUtilsFlattenLayerStackResolveAssetPath(const SdfLayerHandle &sourceLayer, const std::string &assetPath)
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfLayer)
std::function< std::string(const SdfLayerHandle &sourceLayer, const std::string &assetPath)> UsdUtilsResolveAssetPathFn
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
#define USDUTILS_API
Definition: api.h:40